pylbo.gimli

Submodules

Classes

`Variables`	Defines a set of variables and constants to be used in defining an Equilibrium
`Equilibrium`	Class containing all equilibrium expressions and initialisation functions.
`NumericalEquilibrium`	Class to convert numerical arrays to a Legolas-readable format.
`Legolas`	Class for generating user-defined Legolas modules and parfiles.
`Amrvac`	Class to prepare Legolas data for use in MPI-AMRVAC (https://amrvac.org).

Package Contents

class pylbo.gimli.Variables

Defines a set of variables and constants to be used in defining an Equilibrium object.

x, y, z

Coordinates.

Type:: sympy symbols

rho0, T0, B0sq

Density, temperature, and magnetic field squared for use in expressions depending on these quantities.

Type:: sympy symbols

k2, k3

Wavenumbers.

Type:: sympy symbols

gamma

Adiabatic index.

Type:: sympy symbol

rhoc, Tc, B2c, B3c, v2c, v3c, pc

Constants typically used for amplitudes or uniform terms in their corresponding equilibrium quantities. The corresponding Legolas variable names are cte_rho0, cte_T0, cte_B02, cte_B03, cte_v02, cte_v03, and cte_p0.

Type:: sympy symbols

p1, p2, p3, p4, p5, p6, p7, p8

Additional free-use constants.

Type:: sympy symbols

alpha, beta, delta, theta, tau, lam, nu

Additional free-use constants. (Note that ‘lam’ is used instead of ‘lambda’ to avoid conflict with the reserved keyword. The corresponding Legolas variable name is ‘lambda’.)

Type:: sympy symbols

r0, rc, rj, Bth0, Bz0, V, j0, g

Additional constants, originally used in cylindrical coordinates.

Type:: sympy symbols

fkey

Dictionary translating LaTeX notation to Legolas variable names.

Type:: dict

Examples

>>> from pylbo.gimli import Variables
>>> var = Variables()

gamma

fkey

class pylbo.gimli.Equilibrium(var, rho0, v02, v03, T0, B02=None, B03=None, resistivity=None, gravity=None, condpara=None, condperp=None, cooling=None, heating=None, legolas_grid_spacing=None, heatcool=None)

Class containing all equilibrium expressions and initialisation functions. This object is a required argument when generating user files with the Legolas and Amrvac classes.

Parameters:

var (Variables) – The Variables object containing the symbols to be used in the equilibrium expressions.
rho0 (sympy expression) – The equilibrium density expression.
v02 (sympy expressions) – The equilibrium velocity expressions.
v03 (sympy expressions) – The equilibrium velocity expressions.
T0 (sympy expression) – The equilibrium temperature expression.
B02 (sympy expressions) – The equilibrium magnetic field expressions.
B03 (sympy expressions) – The equilibrium magnetic field expressions.
resistivity (sympy expression) – The resistivity expression.
gravity (constant) – The gravitational acceleration.
condpara (sympy expression) – The parallel conduction prescription.
condperp (sympy expression) – The perpendicular conduction prescription.
cooling (sympy expression) – The cooling prescription.
heating (sympy expression) – The heating prescription.
heatcool (dict) – Parameters for cooling and heating, including ‘force_thermal_balance’.

variables

Variables object from which all expressions are constructed.

Type:: Variables object

rho0

The equilibrium density expression.

Type:: sympy expression

v02, v03

The equilibrium velocity expressions.

Type:: sympy expressions

T0

The equilibrium temperature expression.

Type:: sympy expression

B02, B03

The equilibrium magnetic field expressions.

Type:: sympy expressions

Examples

The example below defines a homogeneous hydrodynamic equilibrium with constant density and temperature. Their values can be set later when passing this equilibrium to the Legolas or Amrvac class along with a dictionary.

>>> from pylbo.gimli import Equilibrium, Variables
>>> var = Variables()
>>> eq = Equilibrium(var, rho0=var.rhoc, v02=0, v03=0, T0=var.Tc)

variables

rho0

T0

heatcool = None

grid_spacing

_dict_phys

_validate_equil()

get_physics(): Returns a dictionary containing the physics expressions and the dependencies to check for.

get_dependencies(): Checks for dependencies on other equilibrium quantities. Returns a dictionary with the replacement expressions for use in Fortran files.

get_current(geometry, dim=3): Determines the current density of the equilibrium magnetic field. :param geometry: Either ‘Cartesian’ or ‘cylindrical’. :type geometry: str :param dim: Dimension of the desired setup (currently 2 or 3). :type dim: int

add_current(geometry, dim=3): Adds the current density of the equilibrium magnetic field to the Equilibrium object as attributes J02 and J03. :param geometry: Either ‘Cartesian’ or ‘cylindrical’. :type geometry: str :param dim: Dimension of the desired setup (currently 2 or 3). :type dim: int

Bfield_forcefree(geometry, dim=3): Determines whether the equilibrium magnetic field is force-free. :param geometry: Either ‘Cartesian’ or ‘cylindrical’. :type geometry: str :param dim: Dimension of the desired setup (currently 2 or 3). :type dim: int

class pylbo.gimli.NumericalEquilibrium(arrays)

Class to convert numerical arrays to a Legolas-readable format.

Parameters:: arrays (dict) – A dictionary linking key/header to a numerical array. Must contain “rho0” and “T0” and one of (“u1”, “x”, “r”). Optional arrays are “v01”, “v02”, “v03”, “B01”, “B02”, “B03”, and “grav”.

arrays

Dictionary with specified arrays.

Type:: dict

Examples

The example below defines a homogeneous hydrodynamic equilibrium with constant density and temperature.

>>> import numpy as np
>>> from pylbo.gimli import NumericalEquilibrium
>>> dictionary = {
>>>     "x" : np.linspace(0, 1, 100),
>>>     "rho0": 2 * np.ones(100),
>>>     "T0" : 0.5 * np.ones(100)
>>> }
>>> equil = NumericalEquilibrium(dictionary)
>>> equil.to_legolas_arrays(filename="homogeneous")

arrays

_validate()

to_legolas_arrays(filename='arrays', loc='./')

Prepares a numerical arrays file (.lar) for use with Legolas.

Parameters:

filename (str, optional) – Name of the .lar file. Default is ‘arrays’.
loc (str, optional) – The location to save the .lar file. Default is the current directory.

class pylbo.gimli.Legolas(equilibrium, config)

Class for generating user-defined Legolas modules and parfiles.

Parameters:

equilibrium (Equilibrium) – The equilibrium object containing the user-defined equilibrium and physics functions.
config (dict) – A dictionary containing the configuration for the Legolas run (both equilibrium parameter values and technical settings).

equilibrium

config

_validate_config()

Validates the validity of the configuration dictionary.

Raises:

KeyError – If the configuration dictionary is missing the physics_type key.
ValueError – If physics_type is not “hd” or “mhd”.

_compare_heatcool(): Compares the presence of ‘heatcool’ in the equilibrium with the radiative cooling settings in the config. ‘heatcool’ overrides config settings, but if ‘heatcool’ is not present, config settings are added to the equilibrium.

_check_resistivity(): Makes sure that resistivity is enabled if needed.

user_module(filename='smod_user_defined', loc=None)

Writes the user module for the Legolas run.

Parameters:

filename (str) – The name of the user module file.
loc (str, PathLike) – Path to the directory where the user module will be stored. Default is the current directory.

Examples

The example below defines a homogeneous hydrodynamic equilibrium with constant density and temperature. The values of the equilibrium parameters are set in the configuration dictionary.

>>> from pylbo.gimli import Variables, Equilibrium, Legolas
>>> var = Variables()
>>> eq = Equilibrium(var, rho0=var.rhoc, v02=0, v03=0, T0=var.Tc)
>>> config = {
>>>     "geometry": "Cartesian",
>>>     "x_start": 0,
>>>     "x_end": 1,
>>>     "gridpoints": 51,
>>>     "parameters": {
>>>         "k2": 0.5,
>>>         "k3": 0,
>>>         "cte_rho0": 1,
>>>         "cte_T0": 1
>>>     },
>>>     "equilibrium_type": "user_defined",
>>>     "boundary_type": "wall_weak",
>>>     "physics_type": "mhd"
>>> }
>>> legolas = Legolas(eq, config)
>>> legolas.user_module()

parfile(filename='legolas_config', loc=None)

Writes the parameter file for the Legolas run.

Parameters:

filename (str) – The name of the parameter file.
make_dir (bool) – If True, creates a directory for the parameter file.

Returns:

parfiles – A list containing the paths to the parameter files.

Return type:

list

Examples

The example below defines a homogeneous hydrodynamic equilibrium with constant density and temperature. The values of the equilibrium parameters are set in the configuration dictionary and written to the parameter file.

>>> from pylbo.gimli import Variables, Equilibrium, Legolas
>>> var = Variables()
>>> eq = Equilibrium(var, rho0=var.rhoc, v02=0, v03=0, T0=var.Tc)
>>> config = {
>>>     "geometry": "Cartesian",
>>>     "x_start": 0,
>>>     "x_end": 1,
>>>     "gridpoints": 51,
>>>     "parameters": {
>>>         "k2": 0.5,
>>>         "k3": 0,
>>>         "cte_rho0": 1,
>>>         "cte_T0": 1
>>>     },
>>>     "equilibrium_type": "user_defined",
>>>     "boundary_type": "wall_weak",
>>>     "physics_type": "mhd"
>>> }
>>> legolas = Legolas(eq, config)
>>> legolas.parfile()

class pylbo.gimli.Amrvac(config)

Class to prepare Legolas data for use in MPI-AMRVAC (https://amrvac.org).

Parameters:: config (dict) – The configuration dictionary detailing everything needed for the desired functionalities.

config

_validate_config()

Validates the presence and value of physics_type in the configuration dictionary.

Raises:

KeyError – If physics_type is missing.
ValueError – If physics_type is invalid.

_validate_datfile()

Validates whether a valid Legolas data file was specified in the configuration. Further checks whether all necessary parameters are present in the configuration to prepare Legolas data for use with MPI-AMRVAC.

Raises:

AssertionError – If the length of weights is not equal to the number of eigenvalues or if the elements of the weights do not add up to 1; if ef_factor does not have modulus 1; if norm_range does not have length 2; if norm_range’s first element is larger than the second.
KeyError – If no datfile is specified; if no initial guess for the eigenvalue is specified.
TypeError – If ev_guess is not a single float/complex number or a list/NumPy array of float/complex numbers; if weights is not a list or NumPy array; if ef_factor is not a list with length equal to the number of eigenvalues, or an integer, float, or complex number; if quantity is not a string; if percentage is not a float; if norm_range is not a NumPy array.
ValueError – If quantity is not in the list of equilibrium quantities.
Exception – If the datfile is invalid.

_validate_config_for_mod_usr(): Validates whether the configuration dictionary contains all the arguments to generate a mod_usr.t file for use with MPI-AMRVAC.

_validate_simulation_dict()

_get_combined_perturbation(ef, clean=True)

Takes Legolas’s perturbations of different eigenvalues and adds them up to a single perturbation.

Parameters:: ef (str) – The eigenfunction to combine.
Returns:: The combined perturbation.
Return type:: np.ndarray

_get_total_perturbation(ef_type, clean=True)

Combines the perturbations of different eigenvalues into a single perturbation. Derives the pressure perturbation from the density and temperature perturbations.

Parameters:: ef_type (str) – The eigenfunction to calculate.
Returns:: The total perturbation.
Return type:: np.ndarray

_integrate_energy_term(array, order)

_get_ef_normalisation(clean=True)

Normalises the perturbation of the specified quantity by the maximum background value.

Returns:: The normalisation factor.
Return type:: float

_get_energy_normalisation(clean=True)

Normalises the perturbation eigenfunctions by the energy.

Returns:: The normalisation factor.
Return type:: float

_get_normalisation(clean=True)

Selects which procedure to follow for the normalisation.

Returns:: The normalisation factor.
Return type:: float

_check_physical_perturbation(ef_name, pert)

prepare_legolas_data(name=None, loc=None, clean=True)

Prepares a file (.ldat) from the Legolas data for use with MPI-AMRVAC.

Parameters:

name (str) – Name of the .ldat file
loc (str, PathLike) – Path to the directory where the .ldat file will be stored. Default is the current directory.

Raises:

ValueError – If the datfile is invalid.

Examples

>>> from pylbo.gimli import Amrvac
>>> amrvac_config = {
>>>     "datfile": "./datfile.dat",
>>>     "physics_type": "mhd",
>>>     "ev_guess": [-0.1, 0.1],
>>>     "percentage": 0.01,
>>>     "quantity": "rho0"
>>> }
>>> amrvac = gimli.Amrvac(amrvac_config)
>>> amrvac.prepare_legolas_data()

user_module(filename='mod_usr', loc=None)

Writes the user module for MPI-AMRVAC.

Parameters:

filename (str) – Name of the user module file, defaults to mod_usr
loc (str, PathLike) – Path to the directory where the user module will be stored. Default is the current directory.

parfile(basename='amrvac_config', loc=None, subdir=True, prefix_numbers=False, nb_prefix_digits=4)

Generates parfiles based on the parfile dictionary. The separate namelists do not have to be taken into account, and a normal dictionary should be supplied where the keys correspond to the namelist items that are required. Typechecking is done automatically during parfile generation.

Parameters:

basename (str) – The basename for the parfile, the .par suffix is added automatically and is not needed. If multiple parfiles are generated, these will be prepended by a 4-digit number (e.g. 0003myparfile.par). If not provided, the basename will default to amrvac_config.
output_dir (str, PathLike) – Output directory where the parfiles are saved, defaults to the current working directory if not specified. A subdirectory called parfiles will be created in which the parfiles will be saved.
subdir (boolean) – If True (default), creates a subdirectory parfiles in the output folder.
prefix_numbers (boolean) – If True prepends the basename by a n-digit number (e.g. xxxxmyparfile.par). The number of digits is specified by nb_prefix_digits.
nb_prefix_digits (int) – Number of digits to prepend to the basename if prefix_numbers is True. Defaults to 4.

Returns:

parfiles – A list with the paths to the parfiles that were generated.

Return type:

list