Skip to content

Commit babd33e

Browse files
sourav2609sourav2609
committed
readme update
1 parent 176a660 commit babd33e

1 file changed

Lines changed: 196 additions & 57 deletions

File tree

‎README.md‎

Lines changed: 196 additions & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -23,85 +23,224 @@ If you use the code in any way, please cite the original paper.
2323

2424
---
2525

26-
## Tips
26+
## Requirements
2727

28-
### Required Packages
28+
### Python Packages
2929

30-
- `skyfield`
31-
- `numpy`
30+
- `numpy`
31+
- `skyfield`
3232
- `matplotlib`
3333
- `cvxpy`
3434
- `mosek`
3535

36-
### How to Run
36+
`cvxpy` is configured to solve with `MOSEK`, so a working MOSEK installation and license are required.
3737

38-
In the terminal:
38+
Example installation:
3939

4040
```bash
41-
python3 main.py
41+
pip install numpy skyfield matplotlib cvxpy mosek
4242
```
4343

44-
To use **Iridium satellites**, replace the satellite file in `def satSelection` within:
44+
## How To Run
4545

46+
### 1. Run A Single Configuration
47+
48+
Use [`main.py`](/Users/souravmukherjee/Documents/GitHub/CoDexCodes/dynamic%20FDD/dynamic%20FDD%20-%20Chatgpt%20Accelerated/main.py) to run one `(J, K)` case directly.
49+
50+
Example:
51+
52+
```bash
53+
python3 main.py \
54+
--num-sat 2 \
55+
--num-ue 10 \
56+
--n-iter 5 \
57+
--chunk-id 1 \
58+
--output-root Data
4659
```
47-
root/utilis/network.py
60+
61+
Main arguments:
62+
63+
- `--num-sat`: number of satellites `J`
64+
- `--num-ue`: number of UEs `K`
65+
- `--n-iter`: number of simulation iterations for this run
66+
- `--chunk-id`: chunk number used in output filenames
67+
- `--output-root`: where results are written
68+
- `--seed`: reproducible base seed
69+
- `--plot`: also save a chunk-level CDF plot
70+
71+
### 2. Run Multiple Configurations In Parallel
72+
73+
Use [`scripts/generate_experiment_jobs.py`](/Users/souravmukherjee/Documents/GitHub/CoDexCodes/dynamic%20FDD/dynamic%20FDD%20-%20Chatgpt%20Accelerated/scripts/generate_experiment_jobs.py).
74+
75+
This script now does three things automatically:
76+
77+
1. Generates chunk job scripts
78+
2. Runs the chunk jobs in parallel locally
79+
3. Merges the chunk outputs at the end
80+
81+
Example:
82+
83+
```bash
84+
python3 scripts/generate_experiment_jobs.py \
85+
--j-values 1 2 3 4 \
86+
--k-values 10 15 20 25 30 40 \
87+
--total-iterations 200 \
88+
--chunk-size 10 \
89+
--jobs-root Data/jobs \
90+
--output-root Data \
91+
--max-parallel 4
4892
```
49-
Change `'starlink.txt'` to `'iridium.txt'`.
5093

51-
---
94+
Meaning of the main batch arguments:
95+
96+
- `--j-values`: list of `J` values
97+
- `--k-values`: list of `K` values
98+
- `--total-iterations`: total iterations per configuration
99+
- `--chunk-size`: iterations per chunk job
100+
- `--jobs-root`: where generated shell scripts and logs are stored
101+
- `--output-root`: where simulation results are stored
102+
- `--max-parallel`: maximum number of chunk jobs running at the same time
103+
104+
Example:
105+
106+
- `--total-iterations 200`
107+
- `--chunk-size 10`
108+
109+
means each `(J, K)` configuration is split into `20` chunk jobs, each running `10` iterations.
110+
111+
### 3. Generate Scripts Only
112+
113+
If you only want the shell scripts without executing them:
114+
115+
```bash
116+
python3 scripts/generate_experiment_jobs.py \
117+
--j-values 1 2 \
118+
--k-values 10 15 \
119+
--total-iterations 40 \
120+
--chunk-size 10 \
121+
--jobs-root Data/jobs \
122+
--output-root Data \
123+
--generate-only
124+
```
125+
126+
## Where Results Are Stored
127+
128+
If `--output-root Data` is used, results are written under:
129+
130+
```text
131+
Data/experiments/
132+
```
133+
134+
For a configuration `(J=2, K=15)`, the structure is:
135+
136+
```text
137+
Data/experiments/J_02_K_015/
138+
├── chunks/
139+
│ ├── chunk_001.json
140+
│ ├── chunk_002.json
141+
│ └── ...
142+
├── merged/
143+
│ ├── results.json
144+
│ └── cdf_merged.eps
145+
├── plots/
146+
│ └── chunk_001.eps
147+
└── runtime/
148+
├── chunk_001_satellites.json
149+
└── ...
150+
```
151+
152+
### Chunk Results
52153

53-
## 📁 Code Structure
154+
Each chunk file is saved here:
54155

156+
```text
157+
Data/experiments/J_XX_K_YYY/chunks/chunk_ZZZ.json
55158
```
159+
160+
Each chunk file is checkpointed after every completed iteration and overwritten in the same file.
161+
If you open the file during execution, you can see:
162+
163+
- `status`
164+
- `completed_iterations`
165+
- `target_iterations`
166+
- `iteration_results`
167+
- `results_with_spin`
168+
- `results_without_spin`
169+
170+
So if a run fails midway, the file still shows how many iterations were already completed and their values.
171+
172+
### Runtime Satellite Instances
173+
174+
For each chunk, the generated satellite geometry is stored in:
175+
176+
```text
177+
Data/experiments/J_XX_K_YYY/runtime/chunk_ZZZ_satellites.json
178+
```
179+
180+
### Merged Results
181+
182+
After all chunks finish, merged outputs are stored in:
183+
184+
```text
185+
Data/experiments/J_XX_K_YYY/merged/results.json
186+
Data/experiments/J_XX_K_YYY/merged/cdf_merged.eps
187+
```
188+
189+
The overall summary across configurations is stored in:
190+
191+
```text
192+
Data/experiments/summary.csv
193+
```
194+
195+
## Where Job Files And Logs Are Stored
196+
197+
Generated shell scripts and local execution logs are stored under:
198+
199+
```text
200+
Data/jobs/
201+
```
202+
203+
Example:
204+
205+
```text
206+
Data/jobs/J_02_K_015/
207+
├── chunk_001.sh
208+
├── chunk_002.sh
209+
├── run_all_chunks.sh
210+
└── logs/
211+
├── chunk_001.log
212+
└── chunk_002.log
213+
```
214+
215+
Useful generated files:
216+
217+
- `Data/jobs/run_all.sh`: run all chunk scripts sequentially
218+
- `Data/jobs/run_all_parallel.sh`: run all chunk scripts in parallel
219+
- `Data/jobs/manifest.json`: manifest of all generated chunk jobs
220+
221+
## Notes
222+
223+
- The default UE drop radius is controlled in [`main.py`](/Users/souravmukherjee/Documents/GitHub/CoDexCodes/dynamic%20FDD/dynamic%20FDD%20-%20Chatgpt%20Accelerated/main.py) by `DEFAULT_RADIUS_KM`.
224+
- The default local parallelism is based on CPU count if `--max-parallel` is not specified.
225+
- If you want a specific radius, pass `--radius-km ...` explicitly.
226+
227+
## Project Structure
228+
229+
```text
56230
root/
57231
├── main.py
58-
├── readme.txt
59-
└── utilis/
232+
├── satTLEgenerator.py
233+
├── scripts/
234+
│ ├── generate_experiment_jobs.py
235+
│ └── merge_experiment_results.py
236+
├── Data/
237+
├── Results/
238+
└── utils/
60239
├── __init__.py
61-
├── starlink.txt
62-
├── iridium.txt
63240
├── components.py
64-
│ └── class UE
65-
│ └── class Satellite
241+
├── helper.py
66242
├── network.py
67-
│ └── class Network
68-
│ ├── Parameters:
69-
│ │ └── numSat, numUE, central_loc, radius_km, time, UEs, satellites
70-
│ ├── def generateLayout()
71-
│ ├── def generateRandomLoc()
72-
│ ├── def satSelection()
73-
│ └── def footprint()
74-
├── simulator.py
75-
│ └── class Simulator
76-
│ ├── Parameters:
77-
│ │ └── B, freqs, Ns, Nu, L, Network, nIter, antSpacing
78-
│ ├── def run()
79-
│ ├── def plot()
80-
│ └── def save()
81243
├── optimizer.py
82-
│ └── class Optimizer
83-
│ └── def run()
84-
│ └── 'fractionalProgramming': uses `max_iter` to control convergence
85-
└── helper.py
86-
└── class Helper
87-
├── def arrayResponse()
88-
├── def getDistance()
89-
├── def pathLoss()
90-
├── def ecef_to_geodetic()
91-
├── def azimuth_elevation_from_sat()
92-
├── def channelAndPrecoder()
93-
├── def getSINR()
94-
├── def spin2Frequency()
95-
└── def twoWaySumRate()
244+
├── simulator.py
245+
└── synthetic_orbit.py
96246
```
97-
98-
99-
How to run this:
100-
python3 scripts/generate_experiment_jobs.py \
101-
--j-values 2 \
102-
--k-values 10 \
103-
--total-iterations 10 \
104-
--chunk-size 5 \
105-
--jobs-root Data/jobs \
106-
--output-root Data
107-
---

0 commit comments

Comments
 (0)