GEMINI Example Simulations

Set of scripts containing different examples for how to initialize and run Gemini3D model. These are not all kept up-to-date with the latest GEMINI releases but many are and you can request an update to a particular example of interest by creating and issue on the github page for this repo.

Usage

The init/ directories contain a mix of Matlab and Python scripts. Some of the popular examples have scripts for both languages.

Python

The Python scripts use PyGemini. For each simulation you want to generate, for example "ARCS_eq":

import gemini3d.model

gemini3d.model.setup('init/ARCS_eq', '~/sims/ARCS_eq')

Matlab

The Matlab scripts use MatGemini. To enable these scripts, each time you startup Matlab to work with Gemini, run from the gemini-examples/ directory in Matlab:

setup

Optionally, to run a few self-test scripts in Matlab, from gemini-examples/:

buildtool test

For each simulation you want to generate, for example "ARCS_eq":

gemini3d.model.setup('init/ARCS_eq', '~/sims/ARCS_eq')

OR if the folder has Matlab .m files, run the config() config.m in that folder.

Glossary

Equilibrium simulation

GEMINI is a dynamic model - if you start it in an arbitrary state it will "ring" and take a while to settle into a equilibrium. If one is not careful this can obscure physics of interest so the best approach is to initialize GEMINI using a steady state solution. There is not good way to obtain such a solution except for to start the model from an arbitrary state and let it run for a very long time until it achieves equilibrium. This would be an expensive thing to do except that the equilibrium state will have very little structure and so may be run at a very coarse resolution. Often for a Cartesian grid with a limited lat/lon extent 64 x 20 x 20 is sufficient. For a dipole grid one must be a bit more careful, but generally a much lower resolution can be used (see some of the dipole equilibrium examples in this repository).

Upsampling

We refer to the act of taking an equilibrium state and interpolating it onto a finer grid for simulation of some disturbance phenomena as "upsampling".

Example GEMINI simulations

Several different examples are included with the source code; although initial conditions for each must be generated by the user by running a corresponding equilibrium simulations which generates balanced initial conditions for a given date, time, etc. These equilibrium runs generally are started with a made-up initial condition so there is a lot of initial settling before a sensible ionospheric state is achieved. To account for this one usually needs to run for about 24 hours of simulation time to insure a set of state parameters that are a good representation of the ionosphere.

Each of these examples has its own initial and boundary conditions generation scripts which are stored in the appropriately named directories in the init/ directory, along with a "config.nml" file as input to the simulation. Older simulations have a "config.ini", but "config.nml" is strongly recommended for new / updated simulations as .nml has a much clearer format. The generation scripts must be run in order to produce input grids and initial conditions for each simulation.

List of examples

• 2DSTEVE - an attempt to model STEVE aurora in 2D using inputs that vaguely resemble data from the nature paper.
• ARCS - a test case that included a 3D discrete arc
• ARCS_eq - an equilibrium (eq) simulation that generates initial conditions (ICs) for the ARCS simulation described below.
• Aether - a set of example simulations of a cusp and discrete aurora. There are two sets of files for setting the boundary conditions for the cusp and discrete arc cases, respectively.
• isinglass - example from Guy's 2017 AGU talk showing our attempt to model the ionosphere during the isinglass launch using 2D PFISR vvels and Guy's inversions as input.
• RISR_eq - eq simulation for the GDI and KHI examples described below (location: Resolute Bay ISR)
• isinglass_clayton - pre isinglass event used in Rob Clayton's paper
• isinglass_clayton_flight - Rob's isinglass example
• isinglass_eq - an equilibrium simulation generating ICs for the ISINGLASS simulation
• nepal20152D_highres - A high resolution simulation in 2D for the 2015 Nepal earthquake; use by Paul Inchin in his paper
• nepal20152D_eq - eq simulation for the 2D nepal earthquake simulation
• tohoku20113D_eq - eq simulation for 2D Tohoku earthquake simulations
• tohoku20112D_highres - simulation of 2011 Tohoku earthquake ionospheric effects (require MAGIC input data)
• tohoku20113D_eq - eq simulation for 3D Tohoku earthquake simulation
• tohoku20113D_medres - A medium resolution simulation in 3D of the 2011 Tohoku earthquake.
• tohoku20113D_medres_control - a background (control) simulation for the medium resolution tohoku example.
• tohoku20113D_highres - High resolution tohoku simulation
• tohoku20113D_highres_control - A control (no perturbation) run for tohoku (needed to detrend TEC)
• tohoku20113D_highres_restart - an example showing how a simulation can be restarted (under construction)
• tohoku20113D_highres_var - the tohoku simulation on a variable spacing grid
• GDI_periodic_medres_fileinput - a simulation of gradient-drift instability illustrating the use of a periodic mesh
• GDI_periodic_highres_fileinput - a highres GDI example
• GDI_periodic_highres_fileinput_large - a highres GDI example on a larger domain. This one takes about a week to run on 256 cores.
• KHI_periodic_highres_fileinput - a simulation of Kelvin-Helmholtz instability illustration periodic meshes and use of polarization current solver

A fair bit of testing has been done on these, but there could still be problems so contact a developer if you are having issues with the examples.