Note: The default ITS GitLab runner is a shared resource and is subject to slowdowns during heavy usage.
You can run your own GitLab runner that is dedicated just to your group if you need to avoid processing delays.

DOCUMENTATION.markdown 8.85 KB
Newer Older
Qusai Al Shidi's avatar
Qusai Al Shidi committed
1
2
<a name=".swmfpy"></a>
## swmfpy
3

Qusai Al Shidi's avatar
Autodoc    
Qusai Al Shidi committed
4
5
SWMF Tools
==========
6

Qusai Al Shidi's avatar
Autodoc    
Qusai Al Shidi committed
7
8
A collection of tools to read, write, visualize with the
Space Weather Modeling Framework (SWMF).
9

Qusai Al Shidi's avatar
Autodoc    
Qusai Al Shidi committed
10
11
Modules
-------
12

Qusai Al Shidi's avatar
Autodoc    
Qusai Al Shidi committed
13
These are automatically imported.
14

Qusai Al Shidi's avatar
Autodoc    
Qusai Al Shidi committed
15
16
17
- swmfpy.io: Input/Output tools.
- swmfpy.paramin: PARAM.in editing tools.
- swmfpy.web: Internet data downloading/uploading tools.
18

Qusai Al Shidi's avatar
Autodoc    
Qusai Al Shidi committed
19
20
Extra Modules
-------------
21

Qusai Al Shidi's avatar
Autodoc    
Qusai Al Shidi committed
22
These are not automatically imported. Might have extra dependancies.
23

Qusai Al Shidi's avatar
Autodoc    
Qusai Al Shidi committed
24
*None yet.*
25

Qusai Al Shidi's avatar
Qusai Al Shidi committed
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
<a name=".swmfpy.web"></a>
## swmfpy.web

Tools to retrieve and send data on the web.

Here are a collection of tools to work with data on the internet. Thus,
this module mostly requires an internet connection.

<a name=".swmfpy.web.get_omni_data"></a>
#### get\_omni\_data

```python
get_omni_data(time_from, time_to, **kwargs)
```

Retrieve omni solar wind data over http.

This will download omni data from https://spdf.gsfc.nasa.gov/pub/data/omni
and put it into a dictionary. If your data is large, then make a csv and
use swmfpy.io.read_omni_data().

**Arguments**:

- `time_from` _datetime.datetime_ - The start time of the solar wind
  data that you want to receive.
- `time_to` _datetime.datetime_ - The end time of the solar wind data
  you want to receive.
  

**Returns**:

- `dict` - This will be a list of *all* columns
  available in the omni data set.
  

**Examples**:

  ```python
  import datetime
  import swmfpy.web
  
  storm_start = datetime.datetime(year=2000, month=1, day=1)
  storm_end = datetime.datetime(year=2000, month=2, day=15)
  data = swmfpy.web.get_omni_data(time_from=storm_start,
  time_to=storm_end)
  ```

<a name=".swmfpy.web.download_magnetogram_adapt"></a>
#### download\_magnetogram\_adapt

```python
download_magnetogram_adapt(time, map_type='fixed', **kwargs)
```

This routine downloads GONG ADAPT magnetograms.

Downloads ADAPT magnetograms from ftp://gong2.nso.edu/adapt/maps/gong/
to a local directory. It will download all maps with the regex file
pattern: adapt4[0,1]3*yyyymmddhh

**Arguments**:

- `time` _datetime.datetime_ - Time in which you want the magnetogram.
- `map_type` _str_ - (default: 'fixed')
  Choose either 'fixed' or 'central' for
  the map type you want.
  **kwargs:
- `download_dir` _str_ - (default is current dir) Relative directory
  where you want the maps to be downloaded.
  

**Returns**:

- `str` - First unzipped filename found.
  

**Raises**:

- `NotADirectoryError` - If the adapt maps directory
  is not found on the server.
- `ValueError` - If map_type is not recognized.
  (i.e. not 'fixed' or 'central')
- `FileNotFoundError` - If maps were not found.
  

**Examples**:

  ```python
  import datetime as dt
  
  # Use datetime objects for the time
  time_flare = dt.datetime(2018, 2, 12, hour=10)
  swmfpy.web.download_magnetogram_adapt(time=time_flare,
  map_type='central',
  download_dir='./mymaps/')
  ```

<a name=".swmfpy.io"></a>
## swmfpy.io
125

Qusai Al Shidi's avatar
Autodoc    
Qusai Al Shidi committed
126
Input/Output tools
127

Qusai Al Shidi's avatar
Autodoc    
Qusai Al Shidi committed
128
Here are tools to read and write files relating to SWMF.
129

Qusai Al Shidi's avatar
Autodoc    
Qusai Al Shidi committed
130
TODO: Move pandas dependancy elsewhere.
131

Qusai Al Shidi's avatar
Qusai Al Shidi committed
132
133
<a name=".swmfpy.io.read_wdc_ae"></a>
#### read\_wdc\_ae
134

Qusai Al Shidi's avatar
Autodoc    
Qusai Al Shidi committed
135
136
137
```python
read_wdc_ae(wdc_filename)
```
Qusai Al Shidi's avatar
Qusai Al Shidi committed
138

Qusai Al Shidi's avatar
Autodoc    
Qusai Al Shidi committed
139
140
141
Read an auroral electrojet (AE) indeces from Kyoto's World Data Center
text file into a dictionary of lists.

Qusai Al Shidi's avatar
Qusai Al Shidi committed
142
143
144
145
146
**Arguments**:

  
- `wdc_filename` _str_ - Filename of wdc data from
  http://wdc.kugi.kyoto-u.ac.jp/
Qusai Al Shidi's avatar
Autodoc    
Qusai Al Shidi committed
147

Qusai Al Shidi's avatar
Qusai Al Shidi committed
148
149
150
151
152
**Returns**:

  
- `dict` - {
  Auroral indeces 'AL', 'AE', 'AO', 'AU' (int): {
Qusai Al Shidi's avatar
Qusai Al Shidi committed
153
  'times' (datetime.datetime)
Qusai Al Shidi's avatar
Qusai Al Shidi committed
154
155
156
157
158
- `'values'` _int_ - List of indeces.
  }

<a name=".swmfpy.io.read_wdc_asy_sym"></a>
#### read\_wdc\_asy\_sym
Qusai Al Shidi's avatar
Autodoc    
Qusai Al Shidi committed
159
160
161
162

```python
read_wdc_asy_sym(wdc_filename)
```
Qusai Al Shidi's avatar
Qusai Al Shidi committed
163

Qusai Al Shidi's avatar
Autodoc    
Qusai Al Shidi committed
164
Reads a WDC file for ASY/SYM data.
165

Qusai Al Shidi's avatar
Autodoc    
Qusai Al Shidi committed
166
167
168
Reads an ASY/SYM file downloaded from
http://wdc.kugi.kyoto-u.ac.jp/aeasy/index.html
and puts it into a dictionary.
169

Qusai Al Shidi's avatar
Qusai Al Shidi committed
170
**Arguments**:
171

Qusai Al Shidi's avatar
Qusai Al Shidi committed
172
173
- `wdc_filename` _str_ - Relative filename (or file handle no.) to read.
  
174

Qusai Al Shidi's avatar
Qusai Al Shidi committed
175
**Returns**:
Qusai Al Shidi's avatar
Qusai Al Shidi committed
176

Qusai Al Shidi's avatar
Qusai Al Shidi committed
177
178
179
- `dict` - of values.
- `{'[ASY-SYM]-[D-H]'` - 'times': [], 'values': []}
  
Qusai Al Shidi's avatar
Qusai Al Shidi committed
180

Qusai Al Shidi's avatar
Qusai Al Shidi committed
181
**Examples**:
182

Qusai Al Shidi's avatar
Qusai Al Shidi committed
183
184
185
186
187
188
189
190
191
192
193
  ```python
  indeces = swmfpy.io.read_wdc_asy_sym('wdc.dat')
  # Plot data
  plt.plot(indeces['SYM-H']['times'],
  indeces['SYM-H']['values'],
  label='SYM-H [nT]'
  )
  plt.xlabel('Time [UT]')
  ```
  
  Important to note if there is bad data it will be filled as None.
194

Qusai Al Shidi's avatar
Qusai Al Shidi committed
195
196
<a name=".swmfpy.io.read_omni_csv"></a>
#### read\_omni\_csv
197

Qusai Al Shidi's avatar
Autodoc    
Qusai Al Shidi committed
198
199
200
```python
read_omni_csv(filename, filtering=False, **kwargs)
```
Qusai Al Shidi's avatar
Qusai Al Shidi committed
201

202
203
204
Take an OMNI csv file from cdaweb.sci.gsfc.nasa.gov
and turn it into a pandas.DataFrame.

Qusai Al Shidi's avatar
Qusai Al Shidi committed
205
**Arguments**:
206

Qusai Al Shidi's avatar
Qusai Al Shidi committed
207
208
209
210
211
- `fnames` _dict_ - dict with filenames from omni .lst files.
  The keys must be: density, temperature,
  magnetic_field, velocity
- `filtering` _bool_ - default=False Remove points where the value
  is >sigma (default: sigma=3) from mean.
Qusai Al Shidi's avatar
Qusai Al Shidi committed
212
  
Qusai Al Shidi's avatar
Qusai Al Shidi committed
213
214
215
216
217
  **kwargs:
- `coarseness` _int_ - default=3, Number of standard deviations
  above which to remove if filtering=True.
- `clean` _bool_ - default=True, Clean the omni data of bad data points
  
218

Qusai Al Shidi's avatar
Qusai Al Shidi committed
219
**Returns**:
220

Qusai Al Shidi's avatar
Qusai Al Shidi committed
221
222
223
224
225
226
- `pandas.DataFrame` - object with solar wind data
  
  Make sure to download the csv files with cdaweb.sci.gsfc.nasa.gov
  the header seperated into a json file for safety.
  
  This only tested with OMNI data specifically.
227

Qusai Al Shidi's avatar
Qusai Al Shidi committed
228
229
<a name=".swmfpy.io.write_imf_input"></a>
#### write\_imf\_input
230

Qusai Al Shidi's avatar
Autodoc    
Qusai Al Shidi committed
231
```python
Qusai Al Shidi's avatar
Qusai Al Shidi committed
232
write_imf_input(data, outfilename="IMF.dat", enable_rb=True, **kwargs)
Qusai Al Shidi's avatar
Autodoc    
Qusai Al Shidi committed
233
```
Qusai Al Shidi's avatar
Qusai Al Shidi committed
234

235
236
237
Writes the pandas.DataFrame into an input file
that SWMF can read as input IMF (IMF.dat).

Qusai Al Shidi's avatar
Qusai Al Shidi committed
238
**Arguments**:
239

Qusai Al Shidi's avatar
Qusai Al Shidi committed
240
241
242
243
244
245
- `data` - pandas.DataFrame object with solar wind data
- `outfilename` - The output file name for ballistic solar wind data.
- `(default` - "IMF.dat")
- `enable_rb` - Enables solar wind input for the radiation belt model.
- `(default` - True)
  
Qusai Al Shidi's avatar
Qusai Al Shidi committed
246
247
248
  **kwargs:
- `gse` _bool_ - (default: False) Use GSE coordinates instead of GSM.
  
Qusai Al Shidi's avatar
Qusai Al Shidi committed
249
250
251
  Other paramaters:
- `gse` - (default=False)
  Use GSE coordinate system for the file instead of GSM default.
252

Qusai Al Shidi's avatar
Qusai Al Shidi committed
253
254
<a name=".swmfpy.io.read_gm_log"></a>
#### read\_gm\_log
255

Qusai Al Shidi's avatar
Autodoc    
Qusai Al Shidi committed
256
257
258
```python
read_gm_log(filename, colnames=None, dtypes=None, index_time=True)
```
Qusai Al Shidi's avatar
Qusai Al Shidi committed
259

Qusai Al Shidi's avatar
Autodoc    
Qusai Al Shidi committed
260
261
Make a dictionary out of the indeces outputted
from the GM model log.
262

Qusai Al Shidi's avatar
Qusai Al Shidi committed
263
**Arguments**:
264

Qusai Al Shidi's avatar
Qusai Al Shidi committed
265
266
267
268
269
270
271
272
273
- `filename` _str_ - The relative filename as a string. (or file handle no.)
- `colnames` _[str]_ - (default: None) Supply the name of the columns.
  If None it will use second line
  of log file.
- `dtypes` _[types]_ - (default: None) Provide types for the columns, if
  None then all will be float.
- `index_time` _bool_ - (default: True) Make a column of dt.datetime objects
  in dictionary key 'Time [UT]'.
  
274

Qusai Al Shidi's avatar
Qusai Al Shidi committed
275
**Returns**:
Qusai Al Shidi's avatar
Qusai Al Shidi committed
276

Qusai Al Shidi's avatar
Qusai Al Shidi committed
277
278
  Dictionary of the log file
  
279

Qusai Al Shidi's avatar
Qusai Al Shidi committed
280
**Examples**:
Qusai Al Shidi's avatar
Qusai Al Shidi committed
281

Qusai Al Shidi's avatar
Qusai Al Shidi committed
282
283
284
285
286
287
288
289
  To plot AL and Dst get the log files
  ```python
  geo = swmfpy.io.read_gm_log('run/GM/IO2/geoindex_e20140215-100500.log')
  dst = swmfpy.io.read_gm_log('run/GM/IO2/log_e20140215-100500.log')
  
  # Plot AL indeces
  plt.plot(geo['times', geo['AL'])
  ```
290

Qusai Al Shidi's avatar
Qusai Al Shidi committed
291
292
<a name=".swmfpy.paramin"></a>
## swmfpy.paramin
293

Qusai Al Shidi's avatar
Autodoc    
Qusai Al Shidi committed
294
These tools are to help script the editing of PARAM.in files.
295

Qusai Al Shidi's avatar
Qusai Al Shidi committed
296
297
<a name=".swmfpy.paramin.replace_command"></a>
#### replace\_command
298

Qusai Al Shidi's avatar
Autodoc    
Qusai Al Shidi committed
299
300
301
```python
replace_command(parameters, input_file, output_file='PARAM.in')
```
Qusai Al Shidi's avatar
Qusai Al Shidi committed
302

303
304
305
306
Replace values for the parameters in a PARAM.in file.

Note, if you have repeat commands this will replace all the repeats.

Qusai Al Shidi's avatar
Qusai Al Shidi committed
307
**Arguments**:
308

Qusai Al Shidi's avatar
Qusai Al Shidi committed
309
310
311
312
313
314
- `parameters` _dict_ - Dictionary of strs with format
  replace = {'`COMMAND`': ['value', 'comments', ...]}
  This is case sensitive.
- `input_file` _str_ - String of PARAM.in file name.
- `output_file` _str_ - (default 'PARAM.in') The output file to write to.
  A value of None will not output a file.
315

Qusai Al Shidi's avatar
Qusai Al Shidi committed
316
**Returns**:
Qusai Al Shidi's avatar
Qusai Al Shidi committed
317

Qusai Al Shidi's avatar
Qusai Al Shidi committed
318
319
  A list of lines of the PARAM.in file that would be outputted.
  
320

Qusai Al Shidi's avatar
Qusai Al Shidi committed
321
**Raises**:
Qusai Al Shidi's avatar
Qusai Al Shidi committed
322

Qusai Al Shidi's avatar
Qusai Al Shidi committed
323
324
- `TypeError` - If a value given couldn't be converted to string.
  
325

Qusai Al Shidi's avatar
Qusai Al Shidi committed
326
**Examples**:
Qusai Al Shidi's avatar
Qusai Al Shidi committed
327

Qusai Al Shidi's avatar
Qusai Al Shidi committed
328
329
330
331
332
333
  ```python
  change['`SOLARWINDFILE`'] = [['T', 'UseSolarWindFile'],
  ['new_imf.dat', 'NameSolarWindFile']]
  # This will overwrite PARAM.in
  swmfpy.paramin.replace('PARAM.in.template', change)
  ```
Qusai Al Shidi's avatar
Qusai Al Shidi committed
334

Qusai Al Shidi's avatar
Qusai Al Shidi committed
335
336
<a name=".swmfpy.paramin.read_command"></a>
#### read\_command
Qusai Al Shidi's avatar
Qusai Al Shidi committed
337
338

```python
Qusai Al Shidi's avatar
Qusai Al Shidi committed
339
read_command(command, paramin_file='PARAM.in', **kwargs)
Qusai Al Shidi's avatar
Qusai Al Shidi committed
340
341
```

Qusai Al Shidi's avatar
Qusai Al Shidi committed
342
Get parameters of a certain command in PARAM.in file.
Qusai Al Shidi's avatar
Qusai Al Shidi committed
343

Qusai Al Shidi's avatar
Qusai Al Shidi committed
344
This will find the `COMMAND` and return a list of values for the parameters.
Qusai Al Shidi's avatar
Qusai Al Shidi committed
345

Qusai Al Shidi's avatar
Qusai Al Shidi committed
346
**Arguments**:
Qusai Al Shidi's avatar
Qusai Al Shidi committed
347

Qusai Al Shidi's avatar
Qusai Al Shidi committed
348
349
350
351
352
353
354
- `command` _str_ - This is the `COMMAND` you're looking for.
- `paramin_file` _str_ - (default: 'PARAM.in') The file in which you're
  looking for the command values.
  **kwargs:
- `num_of_values` _int_ - (default: None) Number of values to take from
  command.
  
Qusai Al Shidi's avatar
Qusai Al Shidi committed
355

Qusai Al Shidi's avatar
Qusai Al Shidi committed
356
**Returns**:
Qusai Al Shidi's avatar
Qusai Al Shidi committed
357

Qusai Al Shidi's avatar
Qusai Al Shidi committed
358
359
360
- `list` - Values found for the `COMMAND` in file. Index 0 is `COMMAND` and
  the values follow (1 for first argument...)
  
Qusai Al Shidi's avatar
Qusai Al Shidi committed
361

Qusai Al Shidi's avatar
Qusai Al Shidi committed
362
**Raises**:
Qusai Al Shidi's avatar
Qusai Al Shidi committed
363

Qusai Al Shidi's avatar
Qusai Al Shidi committed
364
365
- `ValueError` - When the `COMMAND` is not found.
  
Qusai Al Shidi's avatar
Qusai Al Shidi committed
366

Qusai Al Shidi's avatar
Qusai Al Shidi committed
367
**Examples**:
Qusai Al Shidi's avatar
Qusai Al Shidi committed
368

Qusai Al Shidi's avatar
Qusai Al Shidi committed
369
370
371
372
373
374
375
376
377
378
  ```python
  start_time = swmfpy.paramin.read_command('`STARTTIME`')
  end_time = swmfpy.paramin.read_command('`ENDTIME`')
  print('Starting month is ', start_time[1])
  print('Ending month is ', end_time[1])
  ```
  
  This will treat all following lines as values for the command. To suppress
  this, try using the `num_of_values` keyword. This is helpful if your
  PARAM.in is comment heavy.
Qusai Al Shidi's avatar
Qusai Al Shidi committed
379