ebtel_parallel

This package is a wrapper around ebtelplusplus designed to quickly run a large number of coronal loop models to generate a grid of solutions used by GX Simulator.

Installation

To use this package, follow the ebtelplusplus installation instructions. Be sure to install the rsp_toolkit submodule from within the ebtelplusplus directory with:

git submodule init
git submodule update

If you get difficult to interprete errors about variables not being of the right type when compiling with scons, check your GNU compiler.

Then, download this package in the desired directory with:

git clone https://github.com/schonfsj/ebtel_parallel.git

To create a compatible anaconda environment, from inside the ebtel_parallel directory run:

conda env create -f environment.yml

You can also install the package locally (so that it can be imported from any working directory) with anaconda:

conda develop .

or pip:

pip install -e .

Finally, line 19 of ebtel_parallel.py should be changed to point to the top directory of ebtelplusplus in the local installation. This is necessary to call the ebtelplusplus c++ program as a subprocess. It is also possible although less convenient to provide this directory as a keyword argument every time one of the main routines is run.

Contents

Directories:

• /runs contains configuration files for running ebtelplusplus and all the aggregated output files.
• /tmp will contain temporary files from each individual model generated from running ebtelplusplus using runs/demo_grid.cfg.xml
• /gx_sav will contain IDL save files holding grids for GX simulator generated by ebtelplusplus_read.pro

Jupyter notebooks:

• ebtel_grid.ipynb demonstrates how to call ebtel_parallel.py to generate grids of solutions for use with GX Simulator

Python files:

• ebtel_parallel.py is the main module that contains all the routines for working with ebtelplusplus.
• power_functions.py module contains functions for working with power law distributions. Used by ebtel_parallel.py to generate random distributions of heating events.
• setup.py contains the module definition that enables installation as an anaconda or pip package.

IDL files:

• ebtelplusplus_read.pro reads in the runs/*.txt files generated with ebtel_parallel.epp_grid() and creates the save files used by GX Simulator.

Demo model run

A sample GX Simulator grid can be computed by running (from within this directory) the following commands in a python script, jupyter notebook, or in a python environemnt:

import ebtel_parallel
ebtel_parallel.epp_grid(file='runs/demo_grid', heating='power', stable=0.1)

Then run the IDL program ebtelplusplus_read.pro to generate the necessary save file for GX Simulator with:

ebtelplusplus_read, 'ebtel'

Further notes

ebtel_parallel.py is mainly a wrapper around ebtelplusplus to facilitate the parallel computation of many ebtel simulations simultaneously. It contains two primary routines:

• epp_grid() computes a grid of solutions for use in GX Simulator. These grids cover a different, smaller parameter space than the original grids generated by Nicki Viall. This is because this program does not gracefully handle failed simulations, and further extending the parameter space leads to instability, depending on the random realization of heating events.
• epp_repeat() computes repeated heating realizations using the same heating parameters. In principle, this could be combined with epp_grid() in order to emulate extremely long simulations and produce grids with more stable DEMs, but this has not been implemented.

This file also contains a number of utility routines used to generate a series of heating events (either regular repeating trains or random samples from power laws), a routine to generate the radiative loss function used in ebtelplusplus, routines to calculate the characteristic loop cooling time, and a routine for calculating the differential dispersion measure (DDM) from standard output files.

In addition to running the simulations in parallel and properly handling the outputs from these batch runs, the main modifications are around the generation of heating events to apply to the individual runs. This is done by applying tags included in the runs/demo_repeat.cfg.xml configuration file that define properties of the heating events that are automatically generated and would otherwise need to be manually included in the configuration file. These automatic heating events can either be 'constant' regular trains of identical heating events or randomly generated events drawn from a defined 'power' law distribution.

For epp_grid(), the loop length and heating rate parameter space is predefined, so the only additional tags that need to be defined are:

• duration: The duration of individual heating events [s]
• alpha: The power law slope (y~x^alpha) of the distribution from which random heating events are drawn
• frequency_scale: a multiplicative scale factor applied to the characteristic cooling time to determine the average time between heating events. frequency_scale=1 means that the average time between heating events is the average cooling time.
• max_factor: Designates the maximum delay between heating events tau_max as a multiplicative factor of the cooling time, defaults to 3. If frequency_scale is set, tau_max = max_factor * frequency_scale * 'loop cooling time'
• cooling_times: Overrides total_time = cooling_times * frequency_scale * 'loop cooling time'
• random_seed: An optional integer that determines the random seed used for each model in ebtel_parallel.epp_grid(). Useful to ensure that each model experiences identical heating event characteristics.

For epp_repeat(), the loop_length must be set just as with the default ebtelplusplus configuration file format. In addition, it is necessary to set the heating rate using:

• energy: The heating rate [erg cm^-2 s^-1] applied to the simulated strand. This is converted into a volumetric heating rate (when calculating heating events) by dividing by the loop_length

And, while it is possible to define the heating with the same parameters used by epp_grid(), it is also possible to define the heating function more manually with the following tags:

• delay: The median (or exact) delay between heating events [s]
• delay_minimum: The minimum delay between consecutive heating events [s]. Defers to delay if applying the minimum would change the median time between events.
• delay_maximum: The maximum delay between consecutive heating events [s]. Defers to delay if applying the maximum would change the median time between events.

The tags alpha, delay_minimum, and delay_maximum are ignored (and can be omitted) if using 'constant' heating.

Note: If you want to output the ebtelplusplus working files to a subdirectory (recommended, because there are many), you need to create that directory before the run, as it will not be generated automatically. This has already been done in the sample directory \tmp. The same is true of the directory for IDL save files \gx_sav.

Citation

If using this code in any published work, please cite the GX Simulator paper:

• Nita et al. (2022)

and the relevant ebtelplusplus papers:

• Klimchuk et al. (2008)
• Cargill et al. (2012a)
• Cargill et al. (2012b)
• Barnes et al. (2016)