RCM package

Primary Package

kaipy.rcm.rcminit module

kaipy.rcm.rcminit.LoadDKTab(fIn='dktable')

Load the DK table from a file and return a flattened array.

Parameters:: fIn (str) – The name of the file containing the DK table. Default is ‘dktable’.
Returns:: A flattened array representing the DK table.
Return type:: numpy.ndarray

kaipy.rcm.rcminit.LoadEnchan(fIn='enchan.dat')

LoadEnchan function loads data from a file and returns two arrays.

Parameters:: fIn (str) – The name of the input file. Default is “enchan.dat”.
Returns:: Array containing the values from the first column of the input file. alamin (numpy.ndarray): Array containing the values from the second column of the input file.
Return type:: iflavin (numpy.ndarray)

kaipy.rcm.rcminit.LoadLAS1(fIn='rcmlas1')

Load LAS1 data from a file.

Parameters:: fIn (str) – The filename of the LAS1 data file. Default is “rcmlas1”.
Returns:: Array of alamc values. etac (ndarray): Array of etac values. ikflavc (ndarray): Array of ikflavc values. fudgec (ndarray): Array of fudgec values.
Return type:: alamc (ndarray)

kaipy.rcm.rcmutils module

class kaipy.rcm.rcmutils.RCMInfo(h5fname, config_fname, noSubsec=True)

Bases: H5Info

Extends H5Info to grab RCM-specific info

Additional Args:: config_fname (str): Full path to rcmconfig.h5 file. Used to get species information
Contains:: Nk: Total number of lambda channels for all species species List(RCMSpeciesInfo): Species information within provided file

class kaipy.rcm.rcmutils.RCMSpeciesInfo(N, flav, kStart, kEnd, alamc)

Bases: object

Container for RCM species

Parameters:

N (int) – Number of energy channels
flav (int) – Species “flavor e.g. 1 = electrons, 2 = protons
kStart (int) – Starting index in Nk-length arrays (e.g. eeta)
kEnd (int) – Ending index +1 in Nk-length arrays This way, array[kStart:kEnd] gives entire species
List (alamc) – List of grid-centered lambda values in units of [eV * (Rx/nT)**(2/3)]

Contains:: Args alami List(float): List of lambda grid corner values in units of [eV * (Rx/nT)**(2/3)]

kaipy.rcm.rcmutils.getClosedRegionMask(s5)

Returns a boolean mask indicating closed regions based on the given input.

Parameters:: s5 (h5py.Group) – An rcm.h5 Step#X group containing the required data for the calculation.
Returns:: A boolean mask indicating closed regions.
Return type:: bool

kaipy.rcm.rcmutils.getCumulPress(ilamc, vm, eetas, doFraction=False)

Returns a 3D array of cumulative pressures.

Parameters:

ilamc (array-like) – [Nk] lambda values (Nk NOT the full number of energy channels, can be subset)
vm (array-like) – [Nj,Ni] vm value
eetas (array-like) – [Nk,Nj,Ni] eetas corresponding to ilamc values
doFraction (bool, optional) – If True, returns cumulative pressure fraction instead of cumulative pressure. Defaults to False.

Returns:

[Nk, Nj, Ni] array of cumulative pressures or cumulative pressure fractions.

Return type:

array-like

kaipy.rcm.rcmutils.getSpecieslambdata(rcmS0, species='ions')

Generates useful lambda information for a given species in the RCM model.

Parameters:

rcmS0 (h5py.Group) – Step#X group from an rcm.h5 output file.
species (str) – Species for which to calculate lambdas. Default is ‘ions’.

Returns:

Dictionary containing the calculated lambdas and other information.

kStart (int): Start index of the lambdas.
kEnd (int): End index of the lambdas.
ilamc (ndarray): Cell centers.
ilami (ndarray): Cell interfaces.
lamscl (ndarray): Calculated lambdas.

Return type:

dict

kaipy.rcm.rcmutils.getValAtLoc_linterp(val, xData, yData, getAxis='y')

Use linear interpolation to find the desired x/y values in data.

Parameters:

val (float) – The x/y value to find the y/x location of.
xData (list) – 1D array of x-axis values.
yData (list) – 1D array of y-axis values.
getAxis (str, optional) – The desired axis. If ‘y’, assumes targets are x values, and vice versa. Defaults to ‘y’.

Returns:

The interpolated location value.

Return type:

float

kaipy.rcm.rcmutils.updateFactors(rxNew)

Update the factors used in calculations based on the given value of rx.

Parameters: rxNew (float): The new value of rx in meters.

Returns: None

kaipy.rcm.rcmxdmf module

RCM-specific tools to include h5 data in xmf files

kaipy.rcm.rcmxdmf.addRCMGeom(Geom, dimInfo, rcmInfo, sID)

Add RCM geometry to Geom xdmf object.

Parameters:

Geom (object) – The Geom xdmf object to add the RCM geometry to.
dimInfo (dict) – A dictionary containing dimension information.
rcmInfo (dict) – A dictionary containing RCM information.
sID (int) – The step ID.

Returns:

None

kaipy.rcm.rcmxdmf.addRCMVars(Grid, dimInfo, rcmInfo, sID)

Used with the mhdrcm presets to add links to given RCM variables onto provided Geom xdmf object.

Parameters:

Grid – The grid xdmf object.
dimInfo – A dictionary containing dimension information.
rcmInfo – A dictionary containing RCM information.
sID – The step ID.

Returns:

None

Lambdautils Package

kaipy.rcm.lambdautils.AlamData module

class kaipy.rcm.lambdautils.AlamData.AlamData(doUsePsphere: bool, specs: List[Species], params: AlamParams | None = None)

Bases: object

Main class that most things will interact with.

doUsePsphere

Whether or not this dataset includes a zero-energy plasmasphere channel.

Type:: bool

specs

List of Species objects.

Type:: List[Species]

params

Parameters used to generate this instance of AlamData.

Type:: Optional[aP.AlamParams], optional

doUsePsphere: bool

params: AlamParams | None = None

specs: List[Species]

class kaipy.rcm.lambdautils.AlamData.Species(n: int, alams: List[float], amins: List[float], amaxs: List[float], flav: int, fudge: float | None = 0, params: SpecParams | None = None, name: str | None = None)

Bases: object

Represents a species in the RCM model.

n

Number of channels.

Type:: int

alams

Lambda channel values.

Type:: List[float]

amins

Lower lambda bounds for species.

Type:: List[float]

amaxs

Upper lambda bound for species.

Type:: List[float]

flav

“Flavor”, used to distinguish species types in RCM. 1 = electrons, 2 = protons.

Type:: int

fudge

“Fudge factor” loss ratio.

Type:: Optional[float], optional

params

Parameters used to generate this instance of Species.

Type:: Optional[aP.SpecParams], optional

name

Name of the species.

Type:: Optional[str], optional

alams: List[float]

amaxs: List[float]

amins: List[float]

flav: int

fudge: float | None = 0

n: int

name: str | None = None

params: SpecParams | None = None

kaipy.rcm.lambdautils.AlamData.conditional_decorator(dec, dataclasses_json_module_imported)

A decorator that conditionally applies another decorator based on the availability of the dataclasses_json module.

Parameters:

dec – The decorator to be applied.
dataclasses_json_module_imported – A boolean value indicating whether the dataclasses_json module is imported.

Returns:

The decorated function if the dataclasses_json module is imported, otherwise returns the function unchanged.

kaipy.rcm.lambdautils.AlamParams module

Bases: object

Class representing the parameters for Alam dataset generation.

doUsePsphere

Whether or not the resulting dataset will include a zero-energy plasmasphere channel.

Type:: bool

specParams

List of all specParams to be included in the dataset.

Type:: List[SpecParams]

emine

Electron min energy in eV.

Type:: Optional[float]

eminp

Proton min energy in eV.

Type:: Optional[float]

emaxe

Electron max energy in eV.

Type:: Optional[float]

emaxp

Proton max energy in eV.

Type:: Optional[float]

L_kt

L value that e/p min/maxes correspond to.

Type:: Optional[float]

L_kt: float | None = None

doUsePsphere: bool

emaxe: float | None = None

emaxp: float | None = None

emine: float | None = None

eminp: float | None = None

specParams: List[SpecParams]

class kaipy.rcm.lambdautils.AlamParams.SpecParams(n: int, amin: float, amax: float, distType: DistType, flav: int, fudge: float | None = 0, name: str | None = None)

Bases: object

Defines a single species.

A full species parameter set is defined by both the params listed here AND the ones in whatever DistType is chosen.

n

Number of channels.

Type:: int

amin

Lower lambda bound for species.

Type:: float

amax

Upper lambda bound for species.

Type:: float

distType

DistType params used to generate final lambda distribution.

Type:: dT.DistType

flav

“Flavor”, used to distinguish species types in RCM. 1 = electrons, 2 = protons.

Type:: int

fudge

“Fudge factor” loss ratio. Defaults to 0.

Type:: Optional[float], optional

name

Name of the species. Defaults to None.

Type:: Optional[str], optional

amax: float

amin: float

distType: DistType

flav: int

fudge: float | None = 0

genAlams()

Generate alams based on the given DistType’s rules.

Returns:: Data generated by the DistType’s ‘genAlamsFromSpecies’ function.
Return type:: specData

n: int

name: str | None = None

kaipy.rcm.lambdautils.AlamParams.conditional_decorator(dec, dataclasses_json_module_imported)

A decorator that conditionally applies another decorator based on the availability of the dataclasses_json module.

Parameters:

dec – The decorator to be applied.
dataclasses_json_module_imported – A boolean value indicating whether the dataclasses_json module is imported.

Returns:

The decorated function if the dataclasses_json module is imported, otherwise returns the function unchanged.

kaipy.rcm.lambdautils.DistTypes module

class kaipy.rcm.lambdautils.DistTypes.DT_Manual(name: str = 'Empty')

Bases: DistType

Represents a manual distribution type.

This class can be used to allow users to add any additional information they want to save for a manual distribution type.

name

The name of the distribution type.

Type:: str

class kaipy.rcm.lambdautils.DistTypes.DT_ValueSpec(name: str = 'Empty', specList: List[ValueSpec] = None)

Bases: DistType

Lambda channel spacing based on a series of slope specifications.

specList

List of ValueSpec objects representing the slope specifications.

Type:: List[ValueSpec]

__post_init__(): Post-initialization method to check if all slopes are contiguous.

genAlamsFromSpecies(): Generates alams from species parameters, adjusting the endpoints if necessary.

genAlams(): Generates alams based on the slope specifications.

genAlams(n, amin, amax)

Generates alams based on the Value specifications.

Parameters:

n (int) – Number of alams to generate.
amin (float) – Minimum value for alams.
amax (float) – Maximum value for alams.

Returns:

List of alams.

Return type:

List[float]

genAlamsFromSpecies(sP)

Generates alams from species parameters, adjusting the endpoints if necessary.

Parameters:: sP – SpecParams object.
Returns:: List of alam values in eV.
Return type:: List[float]

specList: List[ValueSpec] = None

class kaipy.rcm.lambdautils.DistTypes.DT_Wolf(name: str = 'Empty', p1: float = None, p2: float = None)

Bases: DistType

Lambda channel spacing based on Wolf’s notes. Ask Anthony Sciola or Frank Toffoletto for a copy With the addition that there can be 2 p values for the start and end, and pStar transitions between them

p1

The p value for the start.

Type:: float

p2

The p value for the end.

Type:: float

genAlams(n, amin, amax, kmin=0, kmax=-1)

Generate a list of ‘n’ lambda values based on the given parameters.

Parameters:

n (int) – The number of lambda values to generate.
amin (float) – The minimum lambda value.
amax (float) – The maximum lambda value.
kmin (int, optional) – The minimum channel range. Defaults to 0.
kmax (int, optional) – The maximum channel range. Defaults to -1.

Returns:

A list of ‘n’ lambda values.

Return type:

list

genAlamsFromSpecies(sP)

Generate Alams from SpecParams object.

This method generates Alams based on the given SpecParams object.

Parameters: - sP: The SpecParams object containing the necessary information.

Returns: - The generated Alams.

p1: float = None

p2: float = None

class kaipy.rcm.lambdautils.DistTypes.DistType(name: str = 'Empty')

Bases: object

Represents a distribution type.

name

The name of the distribution type.

Type:: str

name: str = 'Empty'

class kaipy.rcm.lambdautils.DistTypes.ValueSpec(start: float, end: float, scaleType: str, n: int | None = None, c: float | None = None)

Bases: object

Represents a value specification with start, end, scale type, and optional parameters.

start

The starting value.

Type:: float

end

The ending value.

Type:: float

scaleType

The scale type. Must be one of [‘lin’, ‘log’, ‘spacing_lin’].

Type:: str

n

The number of channels. Default is None.

Type:: Optional[int]

c

The spacing parameter. Default is None.

Type:: Optional[float]

__post_init__(): Initializes the ValueSpec object and performs validation.

eval(doEnd): Performs the appropriate operation based on the scale type and returns a list of values.

c: float | None = None: c has different meanings depending on scaleType lin: If given, will use set spacing c log: If given, will use log of base c spacing_lin: If given, will use as Sum_{k=1}^{N} c*k, where N is calculated based on start, end, and c

end: float

eval(doEnd)

Performs the appropriate operation given self’s attributes and returns a list of values.

Parameters:: doEnd (bool) – Indicates whether to include the end value in the output.
Returns:: A list of values based on the scale type and other attributes of the ValueSpec object.
Return type:: list

n: int | None = None

scaleType: str

start: float

kaipy.rcm.lambdautils.DistTypes.conditional_decorator(dec, dataclasses_json_module_imported)

A decorator that conditionally applies another decorator based on the availability of the dataclasses_json module.

Parameters:

dec – The decorator to be applied if the dataclasses_json module is imported.
dataclasses_json_module_imported – A boolean indicating whether the dataclasses_json module is imported.

Returns:

The decorated function if the dataclasses_json module is imported, otherwise returns the function unchanged.

kaipy.rcm.lambdautils.DistTypes.getDistTypeFromKwargs(**kwargs)

This function takes a set of keyword arguments and determines which DistType implementation they belong to based on the ‘name’ key.

Parameters:: **kwargs – A set of keyword arguments.
Returns:: An object of the corresponding DistType implementation based on the ‘name’ key.

kaipy.rcm.lambdautils.fileIO module

kaipy.rcm.lambdautils.fileIO.loadParams(f5)

Load parameters from a file.

Parameters:: f5 – The file object containing the parameters.
Returns:: The loaded parameters as an AlamParams object.
Return type:: aPObj
Raises:: AttributeError – If the dictionary cannot be converted into an object.

Notes

This function assumes that the file object f5 has an attribute ‘AlamParams’ which contains a JSON string.
If the ‘AlamParams’ attribute cannot be converted into an object, the function will return the parameters as a dictionary.
The ‘distType’ attribute of each ‘specParams’ object is instantiated separately due to the use of inherited classes.

kaipy.rcm.lambdautils.fileIO.saveData(f5, alamData, doPrint=False)

Takes an AlamData object, formats it to rcmconfig.h5 style, and saves it.

Parameters:

f5 (h5py.File) – The HDF5 file object to save the data to.
alamData (AlamData) – The AlamData object containing the data to be saved.
doPrint (bool, optional) – Whether to print the intermediate arrays. Defaults to False.

kaipy.rcm.lambdautils.fileIO.saveParams(f5, alamParams)

Save the alamParams to the given f5 object.

Parameters:

f5 – The f5 object to save the parameters to.
alamParams – The alamParams to be saved.

Returns:

None

kaipy.rcm.lambdautils.fileIO.saveRCMConfig(alamData, params=None, fname='rcmconfig.h5')

Save the RCM configuration data to an HDF5 file.

Parameters:

alamData – The RCM configuration data to be saved.
params – The parameters used to generate the lambda data (optional).
fname – The filename of the HDF5 file (default: ‘rcmconfig.h5’).

kaipy.rcm.lambdautils.genAlam module

This script is responsible for taking AlamParam objects and turning it into lambdas and associated attributes for AlamData objects

kaipy.rcm.lambdautils.genAlam.genAlamDataFromParams(alamParams)

Generate AlamData object from the given alamParams.

Parameters:: alamParams – The alamParams object containing the parameters for generating AlamData.
Returns:: The generated AlamData object.
Return type:: AlamData

kaipy.rcm.lambdautils.genAlam.genPsphereSpecies()

Generate a species object for the Plasmasphere.

Returns:: The Species object for the Plasmasphere.
Return type:: aD.Species

kaipy.rcm.lambdautils.genAlam.genSpeciesFromParams(specParams)

Takes a SpecParams object and generates a new Species object.

Parameters:: specParams (SpecParams) – The SpecParams object containing the parameters for generating the Species.
Returns:: The generated Species object.
Return type:: Species

kaipy.rcm.lambdautils.genAlam.getAlamMinMax(alams)

Given the ‘cell-center’ alam values, calculate the min and max bounds for each channel

Parameters:: alams (list) – A list of cell-centered alam values.
Returns:: A tuple containing two lists - the minimum values (amin) and the maximum values (amax) for each channel.
Return type:: tuple

kaipy.rcm.lambdautils.plotter module

kaipy.rcm.lambdautils.plotter.plotEnergyRange(specDataList, rInner=1.5, rOuter=15, rRes=100)

Plot energy range of each species as a function of L shell.

Parameters:

specDataList (list) – List of species data.
rInner (float, optional) – Inner radius of the L shell. Defaults to 1.5.
rOuter (float, optional) – Outer radius of the L shell. Defaults to 15.
rRes (int, optional) – Number of points to sample between rInner and rOuter. Defaults to 100.

Returns:

None

kaipy.rcm.lambdautils.plotter.plotLambdasBySpec(specDataList, yscale='log', L=None)

Plot lambdas by species individually.

Parameters:

specDataList (list) – A list of Species objects (ideally from an initialized alamData.specs).
yscale (str, optional) – The scale of the y-axis. Defaults to ‘log’.
L (float, optional) – The L-shell value. Defaults to None.

Returns:

None

kaipy.rcm.lambdautils.plotter.plotLambdas_Val_Spac(specDataList, yscale='log', L=None)

Plot the values and spacing of lambda data.

Parameters:

specDataList (list) – A list of Species objects (ideally from an initialized alamData.specs).
yscale (str, optional) – The scale of the y-axis. Defaults to ‘log’.
L (float, optional) – The value of L. If provided, energy calculations will be performed. Defaults to None.

Wmutils Package

kaipy.rcm.wmutils.genWM module

kaipy.rcm.wmutils.genWM.ChorusPoly(Li, Eki, polyArray)

Calculate the electron lifetime caused by interaction with Chorus Waves using polynomial fit coefficients.

Parameters: Li (array-like): Array of L values. Eki (array-like): Array of Ek values. polyArray (ndarray): Array of polynomial fit coefficients.

Returns: ndarray: Array of electron lifetimes.

Notes: - The polynomial fit coefficients are obtained from a research paper by Dedong Wang et al. (in preparation). - The function calculates the electron lifetime for each Kp and MLT value based on the given Li and Eki values.

References: - [Research Paper](https://doi.org/will be provided)

kaipy.rcm.wmutils.genWM.ReSample(L, MLT, Qp, xMLT)

Resamples the input data based on the given parameters.

Parameters:

L (array-like) – Array of L-shell values.
MLT (array-like) – Array of magnetic local time values.
Qp (array-like) – Array of input data.
xMLT (float) – Magnetic local time value to resample at.

Returns:

2D (L,MLT) smoothed inupt data resampled in the MLT dimension.

Return type:

array-like

Raises:

None –

Notes

This function adds ghosts in MLT to handle periodic boundary.
The resampling is performed by setting the center and then left/right strips.
Equality at the overlap point is enforced.

kaipy.rcm.wmutils.genWM.genChorus(params, fInChorus)

Generate chorus wave model parameters.

Parameters:

params (object) – Object containing the parameters for the chorus wave model.
fInChorus (str) – File path to the input file.

Returns:

A tuple containing the following arrays:

Kpi (numpy.ndarray): Array of Kp indices.
xMLTi (numpy.ndarray): Array of MLT indices.
Li (numpy.ndarray): Array of L indices.
Eki (numpy.ndarray): Array of E indices.
tauX (numpy.ndarray): Array of tau values.

Return type:

tuple

kaipy.rcm.wmutils.genWM.genWM(params)

Generate WM (Wave Model: Chorus wave) using the given parameters.

Parameters:: params (dict) – A dictionary containing the parameters for generating the WM.
Returns:: The returns from genChorus function.
Return type:: object
Raises:: None –

Example

params = {: ‘param1’: value1, ‘param2’: value2, …

} genWM(params)

kaipy.rcm.wmutils.genWM.genh5(fIn, fOut, inputParams)

Write the wave model to an HDF5 file (rcmconfig.h5) with data and attributes based on the input parameters.

Parameters:

fIn (str) – The input HDF5 file path.
fOut (str) – The output HDF5 file path.
inputParams (dict) – A dictionary containing input parameters.

Returns:

None

kaipy.rcm.wmutils.genWM.readPoly(fIn)

Read a polynomial fit parameters of chorus wave from an input file.

Parameters:: fIn (str) – The path to the input file.
Returns:: A tuple containing the length of each row and a numpy array of the parameter table.
Return type:: tuple

kaipy.rcm.wmutils.wmData module

class kaipy.rcm.wmutils.wmData.wmParams(dim=4, nKp=6, nMLT=97, nL=41, nEk=155)

Bases: object

Class representing the dimension of the parameters for the chorus wave model

dim: number of parameters in the electron lifetime

nKp, nMLT,nL,nEk: Dimension of Kp, MLT, L and Ek as the parameter of the model.

getAttrs()