Gemini Matlab scripts

These scripts form the basic core needed to work with Gemini3D ionospheric model to:

• generate a new simulation from scratch
• read simulation output
• plot simulation

Matlab R2020a Update 5 and newer have better plot quality due to new Matlab graphics backend.

Quick Start

We assume you already have a Fortran compiler and MPI library installed.

git clone --recurse-submodules https://github.com/gemini3d/mat_gemini

To enable mat_gemini functions, from the "mat_gemini/" directory in Matlab:

setup

Self-check (optional, but recommended)

Run the self-tests from Matlab in the mat_gemini/ directory:

runtests('gemini3d')

---

We use .zst ZSTD files for the reference test data. If you don't have "zstd" on your system, you can install this from the mat_gemini/ directory by:

cmake -P cmake/build_zstd.cmake

---

If there are failures with SSL certificate errors, you may need to tell Git the location of your system SSL certificates. This can be an issue in general on HPC. If this is an issue, and assuming your SSL certificates are at "/etc/ssl/certs/ca-bundle.crt", do these two steps from Terminal (not Matlab), one time.

1. edit ~/.bashrc to have

   export SSL_CERT_FILE=/etc/ssl/certs/ca-bundle.crt

2. issue Terminal command:

   git config --global http.sslCAInfo /etc/ssl/certs/ca-bundle.crt

Usage

Generally, one sets up a simulation, runs, then plots the outputs of that simulation. Once that works, one perhaps changes simulation parameters, perhaps by perturbing the plasma or inputs with custom functions.

The model setup creates a neutral atmosphere using MSIS. The default is to use MSISE00, but MSIS 2.0 is also available. This is user selectable in the simulation config.nml file like:

&neutral_BG
msis_version = 20
/

where 0 is MSISE00 (default) and 20 is MSIS 2.0.

Run Simulation

The Matlab Live Scripts Examples/ns_fang.mlx interactively demonstrates running a 2D simulation. Open and run this script, or simply run from Matlab:

gemini3d.run(out_dir, 'Examples/init/2dns_fang.nml')

Load a data frame

The data writes out to a file each time step it's commanded to by the config.nml "dtout" parameter. You can load these by filename, or by directory + time:

dat = gemini3d.read.frame(filename);

dat = gemini3d.read.frame(directory, 'time', datetime(2012,1,20,12,5,3));

Plot all simulation outputs

gemini3d.plot(out_dir, "png")

generates plots under out_dir + "/plots" Will save all plots under the mysim/plots/ directory. Omitting 'png' just displays the plots without saving.

Plot simulation grid

Plots of the simulation grid can be made:

gemini3d.plot.grid(sim_path)

This can help show if something unintended happened.

Advanced usage

Custom functions

Often users will desire to perturb the quiescent equilibrium data with custom Matlab functions. Assuming these functions have an interface like

myfunc(cfg, xg)

then they can be specified in the config.nml file under setup/setup_functions. For examples see GDI_periodic_lowres and KHI_periodic_lowres.

compare data directories

It can be useful to compare a simulation output and/or input with a "known good" reference case. We provide this facility within the Matlab unittest framework for robustness and clarity.

gemini3d.compare(new_dir, reference_dir)

That compares simulation inputs and outputs.

---

To only compare simulation input:

gemini3d.compare(new_dir, reference_dir, 'in')

---

To only compare simulation output:

gemini3d.compare(new_dir, reference_dir, 'out')

Regenerate self-test reference datasets

This is intended for use by developers working with the internals of Gemini3D, the average user doesn't need this. When a significant change is made to internal Gemini3D code, this may change the reference data and cause the self-tests to fail. If determined that new reference datasets are needed:

gemini3d.tests.generate_reference_data('../gemini-examples/init', '~/sim', 'test2d')

That makes all tests with subdirectory names containing "test2d". A cell array or string array of names can also be specified.