|
| 1 | +# Running Aether |
| 2 | + |
| 3 | +See the installation.md document for how to install Aether. |
| 4 | + |
| 5 | +## The first run |
| 6 | + |
| 7 | +Once you have compiled you can run Aether. To remember which runs you're doing, |
| 8 | +we recommend creating a specific directory for each run. This can be done by |
| 9 | +copying the default run directory to have a special name, like this: |
| 10 | +```bash |
| 11 | +cd .. |
| 12 | +cp -R share/run ./run.first_run |
| 13 | +``` |
| 14 | + |
| 15 | +This creates the directory where you will do your run. In that directory is a link to the aether executable and an input file called aether.json. |
| 16 | + |
| 17 | +You can then run the executable from the directory you created. |
| 18 | +```bash |
| 19 | +cd run.first_run |
| 20 | +./aether |
| 21 | +``` |
| 22 | +You should see something like: |
| 23 | +```bash |
| 24 | +run.first_run% ./aether |
| 25 | +> Need to NOT adjust F10.7, but that isn't included yet!!! |
| 26 | +> Writing file : 3DALL_20110320_000000 |
| 27 | +> Writing file : 3DBFI_20110320_000000 |
| 28 | +> Wall Time : 4s (left : 1111h); Current Time : 2011 3 20 0 0 0 0 |
| 29 | +> Wall Time : 4s (left : 23m); Current Time : 2011 3 20 0 0 10 0 |
| 30 | +> Wall Time : 5s (left : 14m); Current Time : 2011 3 20 0 0 20 0 |
| 31 | +> Wall Time : 5s (left : 9m); Current Time : 2011 3 20 0 0 30 0 |
| 32 | +> Wall Time : 5s (left : 7m); Current Time : 2011 3 20 0 0 40 0 |
| 33 | +> Wall Time : 6s (left : 7m); Current Time : 2011 3 20 0 0 50 0 |
| 34 | +> Wall Time : 6s (left : 5m); Current Time : 2011 3 20 0 1 0 0 |
| 35 | +> Wall Time : 6s (left : 5m); Current Time : 2011 3 20 0 1 10 0 |
| 36 | +> Wall Time : 7s (left : 5m); Current Time : 2011 3 20 0 1 20 0 |
| 37 | +> Wall Time : 7s (left : 4m); Current Time : 2011 3 20 0 1 30 0 |
| 38 | +etc. |
| 39 | +``` |
| 40 | +
|
| 41 | +The successful end of this will show a timing summary, similar to: |
| 42 | +```bash |
| 43 | +>main>advance>Chemistry::calc_chemistry |
| 44 | + nTimes called : 720 |
| 45 | + timing_total (s) : 1.52599 |
| 46 | +>main>advance>Ions::calc_ion_temperature |
| 47 | + nTimes called : 720 |
| 48 | + timing_total (s) : 19.0279 |
| 49 | +>main>advance>Neutrals::exchange |
| 50 | + nTimes called : 720 |
| 51 | + timing_total (s) : 2.94398 |
| 52 | +``` |
| 53 | +
|
| 54 | +## Output Files |
| 55 | +
|
| 56 | +Aether outputs to a subdirectory called UA/output. At this time, all processors within the Aether run output their own files and they can be combined using the post processor. |
| 57 | +
|
| 58 | +### Blocks |
| 59 | +
|
| 60 | +Aether is a block-based code, so the domain is split up into different blocks that hold a given volume (for spherical grids, this is some range of latitude, longitude and altitude; for other grids it could differ). If you asked for (for example) 4 processors, then the Earth would be broken up into 4 different blocks and each output would consist of 4 different blocks. |
| 61 | +
|
| 62 | +### Ensembles |
| 63 | +
|
| 64 | +Aether can run the same simulation multiple times simultaneously with different drivers and internal parameters. The collection of these simulations is called an ensemble, with each individual simulation called a member. All of the ensemble members output to the UA/output directory. See the ensembles.md document to learn more about ensembles. |
| 65 | +
|
| 66 | +### Post processing |
| 67 | +
|
| 68 | +Because there can be multiple blocks and multiple ensemble members, there is a post processor that can pull all of the files together. By default, the post processor combines all of the block files for one ensemble member for one time into one file. This means that if there are 25 hourly outputs requested, there will be 25 total files for each ensemble member. |
| 69 | +
|
| 70 | +If there is more than one simulation, then the post processor will create a mean file for each time. If there are more than two ensemble members, a standard deviation file is also created. The mean and standard deviations are calculated across ensemble members. |
| 71 | +
|
| 72 | +To run the post processor, do the following: |
| 73 | +
|
| 74 | +```bash |
| 75 | +cd UA/output |
| 76 | +../../../srcPython/post_process.py |
| 77 | +``` |
| 78 | +
|
| 79 | +By default, this will also leave the raw files and will produce plots just to make sure that everything is working ok. If you don't need the raw files (there is not a good reason to keep these, unless you are debugging the post processor), you can run the post-processor with the "-rm" argument. If you don't want any plots, you can run with the "-alt=-1" argument. An example of this is (this is how it is often run): |
| 80 | +
|
| 81 | +```bash |
| 82 | +../../../srcPython/post_process.py -rm -alt=-1 |
| 83 | +``` |
| 84 | +
|
| 85 | +If you are going to be using Aether a lot, you may want to copy the post-processor into your bin directory. |
| 86 | +
|
| 87 | +## Input Files |
| 88 | +
|
| 89 | +Aether reads in a bunch of files, most of which are specified by the settings file. In order to minimize the number of places where new settings need to be specified, Aether uses a defaults file that sets the generic defaults of the model. This file is in UA/inputs/defaults.json. |
| 90 | +
|
| 91 | +## defaults.json file |
| 92 | +
|
| 93 | +This is a json file that sets all of the defaults within Aether. This file should never be modified! |
| 94 | +
|
| 95 | +### For Developers |
| 96 | +
|
| 97 | +Within Aether, the inputs.cpp file has a large handful of of get_ routines to get the values of the settings that the user has set. |
| 98 | +
|
| 99 | +## aether.json file |
| 100 | +
|
| 101 | +The file aether.json is read in AFTER the defaults file and these settings overwrite the defaults. So, if you want to modify the default settings, simply copy a setting out of defaults.json and paste it into aether.json. Then, you can modify the setting in aether.json. |
| 102 | +
|
| 103 | +Because the files are json files, you don't actually have to set all of the subsettings within a specific setting. For example, within the defaults.json file, the EUV setting is: |
| 104 | + |
| 105 | +```bash |
| 106 | + "Euv" : { |
| 107 | + "doUse" : true, |
| 108 | + "Model" : "euvac", |
| 109 | + "File" : "UA/inputs/euv.csv", |
| 110 | + "IncludePhotoElectrons" : true, |
| 111 | + "HeatingEfficiency" : 0.05, |
| 112 | + "dt" : 60.0}, |
| 113 | +``` |
| 114 | +
|
| 115 | +If you simply want to turn off the EUV, you can insert this into the aether.json file: |
| 116 | +
|
| 117 | +```bash |
| 118 | + "Euv" : { |
| 119 | + "doUse" : false}, |
| 120 | +``` |
| 121 | +
|
| 122 | +or, if you wanted to use the 59 wavelength bins instead of the 37 EUVAC bins, you could do: |
| 123 | +
|
| 124 | +```bash |
| 125 | + "Euv" : { |
| 126 | + "File" : "UA/inputs/euv_59.csv"}, |
| 127 | +``` |
| 128 | +
|
| 129 | +## planet.in file |
| 130 | +
|
| 131 | +Within the input file, the planet file can be set: |
| 132 | +
|
| 133 | +```bash |
| 134 | + "Planet" : { |
| 135 | + "name" : "earth", |
| 136 | + "file": "UA/inputs/earth.in"}, |
| 137 | +``` |
| 138 | +
|
| 139 | +This file defines the neutrals and ions to be modeled. For example: |
| 140 | +
|
| 141 | +```bash |
| 142 | +#NEUTRALS |
| 143 | +name, mass, vibration, thermal_cond, thermal_exp, advect, BC |
| 144 | +O, 16, 5, 5.6e-4, 0.69, 1, 5.0e17 |
| 145 | +N, 14, 5, 5.6e-4, 0.69, 1, 2.5e11 |
| 146 | +O2, 32, 7, 3.6e-4, 0.69, 1, 4.0e18 |
| 147 | +N2, 28, 7, 3.6e-4, 0.69, 1, 1.7e19 |
| 148 | +NO, 30, 7, 3.6e-4, 0.69, 1, 5.4e14 |
| 149 | +He, 4, 5, 5.6e-4, 0.69, 1, 1.5e14 |
| 150 | +N_2D, 14, 5, 5.6e-4, 0.69, 0, 2.5e9 |
| 151 | +N_2P, 14, 5, 5.6e-4, 0.69, 0, 2.5e7 |
| 152 | +H, 1, 5, 5.6e-4, 0.69, 0, 3.0e13 |
| 153 | +O_1D, 16, 5, 5.6e-4, 0.69, 0, 1.0e10 |
| 154 | +CO2, 46, 7, 3.6e-4, 0.69, 0, 4.5e15 |
| 155 | +``` |
| 156 | +
|
| 157 | +This is a comma seperated list that includes: |
| 158 | +- name - this is the common name of the species |
| 159 | +- mass - the atomic mass of the species |
| 160 | +- vibration - the degrees of freedom for the species |
| 161 | +- thermal_cond - the thermal conductivity coeficient of the species |
| 162 | +- thermal_exp - the exponent that is put on the temperature (Lambda = A * T^B) |
| 163 | +- advect - whether the species is advected or not |
| 164 | +- BC - the lower boundary condition on the species density |
| 165 | +
|
| 166 | +```bash |
| 167 | +#IONS |
| 168 | +name, mass, charge, advect |
| 169 | +O+, 16, 1, 1 |
| 170 | +O2+, 32, 1, 0 |
| 171 | +N2+, 28, 1, 0 |
| 172 | +NO+, 30, 1, 0 |
| 173 | +N+, 14, 1, 0 |
| 174 | +He+, 4, 1, 1 |
| 175 | +O+_2D, 16, 1, 0 |
| 176 | +O+_2P, 16, 1, 0 |
| 177 | +``` |
| 178 | +
|
| 179 | +This is a comma separated list that includes: |
| 180 | +- name - this is the common name of the species |
| 181 | +- mass - the atomic mass of the species |
| 182 | +- charge - the charge of the species |
| 183 | +- advect - whether the species is advected or not |
| 184 | +
|
| 185 | +```bash |
| 186 | +#TEMPERATURE |
| 187 | +alt, temp |
| 188 | +100.0, 200.0 |
| 189 | +200.0, 800.0 |
| 190 | +300.0, 800.0 |
| 191 | +``` |
| 192 | +
|
| 193 | +Within the input file (i.e., aether.json), the following can be set: |
| 194 | +
|
| 195 | +```bash |
| 196 | + "InitialConditions" : { |
| 197 | + "type" : "Planet"}, |
| 198 | +
|
| 199 | + "BoundaryConditions" : { |
| 200 | + "type" : "Planet"}, |
| 201 | +``` |
| 202 | +
|
| 203 | +If these are set to "Planet", then the temperature profile is set as the initial condition. If the boundary condition is set to "Planet", then the lowest altitude is used as a boundary condition on the temperature. |
| 204 | +
|
| 205 | +## orbits.csv file |
| 206 | +
|
| 207 | +This file contains all of the orbital, mass, rotation, and magnetic field characteristics of the planets. All of the planets within the solar system are included. Other planets (like exo-planets or artificial planets) can be included by adding lines. |
| 208 | +
|
| 209 | +## chemistry file |
| 210 | +
|
| 211 | +The chemistry file defines all of the chemical reactions within the system. |
| 212 | +
|
| 213 | +For example: |
| 214 | +```bash |
| 215 | +He+ + e- -> He, with R = 4.8e-18 * (250 / Te) ^ 0.7 |
| 216 | +``` |
| 217 | +With an exothermal energy of xxx. Also, the uncertainty of the reaction can be set too (set to 10%, or 0.1). |
| 218 | +
|
| 219 | +```bash |
| 220 | +R11,He+,e-,,,He,,,4.80E-18,(250/Te)^0.7,,1,0,,0.1,,,,gitm,250,Te,0.7,,,,1, |
| 221 | +``` |
| 222 | +
|
| 223 | +
|
0 commit comments