rizer.io.lxcat

Read and write [LXCat] database.

Exceptions

DuplicateError

Common base class for all non-exit exceptions.

Classes

Collision	Dataclass to store collision information.
Species	Dataclass to contain species collisions information.
LXCat	Class to read or write a LXCat database.

Module Contents

class rizer.io.lxcat.Collision

Dataclass to store collision information.

Cross sections and reaction rate constant for the ionisation of CH₄ by electrons.

Cross sections and reaction rate constant for the ionisation of CH₄ by electrons.

energy_eV: numpy.ndarray

Energy in eV.

cross_section_cm2: numpy.ndarray

Cross section in cm^2.

species_name: str

Species name.

reaction: str

Reaction name.

type: str

Collision type.

details: str

Details.

threshold: float

Threshold energy.

mass_ratio: float

Mass ratio.

comment: str

Comments.

updated: str

Update date.

class rizer.io.lxcat.Species

Dataclass to contain species collisions information.

name: str

Species name.

comment: str = ''

Comments.

collisions: dict[str, Collision]

Dictionary of collisions for this species.

Key: Reaction name Value: Collision data

exception rizer.io.lxcat.DuplicateError

Bases: Exception

Common base class for all non-exit exceptions.

class rizer.io.lxcat.LXCat(verbose: bool = True, replace_duplicates: bool = False)

Class to read or write a LXCat database.

Parameters:

• verbose (bool, optional) – If True, show text messages. Default to True.

• replace_duplicates (bool, optional) – If True, replace duplicate reactions with the newest one (dangerous!). If False, raises an error if a duplicate is detected. Default to False.

Examples

>>> from rizer.misc.utils import get_path_to_data
>>> from rizer.io.lxcat import LXCat
>>> bolsigdb = get_path_to_data("kin", "bolsigdb", "LXCat-default.txt")
>>> LX = LXCat(verbose=False)
>>> LX.read(bolsigdb)
['Ar', 'CH4', 'CF4', 'Cl2', 'CO2', 'Cu', 'F2', 'H2', 'HCl', 'He', 'Hg', 'Kr', 'N2', 'Ne', 'O2',    'SF6', 'SiH4', 'Xe']
>>> LX.add_species("CO2(v1)", "Vibrationaly excited N2")
>>> LX.clone_collision(
...     "CO2",
...     "CO2 -> CO2*(7.0eV)",
...     "CO2(v1)",
...     "CO2(v1) -> CO2*(7.0eV)",
...     shift_ev=-0.291,
... )
        eV           cm2
0   6.709  0.000000e+00
1   7.709  6.000000e-17
2   8.209  6.000000e-17
3  10.709  0.000000e+00
>>> LX.export("LXCat-updated.txt", species_names="CO2", overwrite=True)

Cross sections and reaction rate constant for the ionisation of CH₄ by electrons.

Cross sections and reaction rate constant for the ionisation of CH₄ by electrons.

collision = ['elastic', 'effective', 'rotation', 'excitation', 'ionization', 'attachment']

verbose = True

duplicate = False

header: str

species: dict[str, Species]

Dictionary of species for each species.

Key: Species name Value: Species data

read(file: str | pathlib.Path, clear: bool = False) → list[str]

Read a LXCat database file.

Call several times to read multiple files. Call clear to erase the former databases.

Fills the LX object as a dictionary with:

LX.species[species1] –> Species

.collisions[reaction1] –> Collision .collisions[reaction2] .collisions… .collisions[reactionN]

And each element contains a Collision object.

Parameters:

• file (Path | str) – LXCat filename. See below for more details on accepted format.

• clear (bool, optional) – If True, former collisions are removed. Default False.

Returns:

List of species in the database

Return type:

list[str]

Notes

LXCat format (see documentation at http://www.bolsig.laplace.univ-tlse.fr/manual.html, section ‘Main input: collision cross section data’)

Each collision process is defined by separate block of data, consisting of

1st line: Keyword in capitals indicating the type of the collision. ‘elastic’, ‘effective’,’ionization’, ‘attachment’, ‘excitation’ or ‘rotation’

2nd line: Name of the target particle species, consisting of a single word without spaces, freely chosen by the user, used by BOLSIG+ to identify the target species when loading the data and defining the gas composition.

3rd line (Optional): One or more parameter values, depending on the collision type as described below (see doc), e.g.threshold energy for inelastic collisions.

4th line (Optional): User comments and reference information, maximum 100 lines. The only constraint on format is that these comment lines must not start with a number.

Finally: Table of the cross section as a function of energy. The table starts and ends by a line of dashes ‘-’ (at least 5), and has otherwise two numbers per line: the energy in eV and the cross section in m2.

get_all_species_names() → list[str]

Return all species names that have been loaded.

get_species_names(species_names: str | list[str] | None = None) → list[str]

Get every species given.

Accept * as character completion.

Parameters:

species (str | list[str] | None, optional) – If None, return every species present in database. If str, return it as a list. If * is present, search every species beginning with what is before *. Defaults to None.

Raises:

AssertionError: – if one of the species given is not in the database.

Returns:

List of species.

Return type:

list[str]

get_collisions(species_name: str | list[str] | None = None) → list[list[Collision]]

Get collisions in database.

Parameters:

species_name (str | list[str] | None, optional) – The specie(s) from which get collisions. If set to None, get every collisions.

Returns:

Collisions for given species

Return type:

list[list[Collision]]

get_collisions_names(species_name: str | list[str] | None = None) → list[list[str]]

Get collisions in database.

Parameters:

species_name (str | list[str] | None, optional) – The specie(s) from which get collisions. If set to None, get every collisions.

Returns:

Collisions for given species

Return type:

list[list[str]]

get_number_of_collisions() → int

Get the total number of collisions in the database.

check_valid() → bool

Raise errors if the database is not valid.

export(file_name: pathlib.Path | str = 'bolsigdb.dat', species_names: str | list[str] | None = None, format_: str = 'bolsigdb', overwrite: bool = False) → None

Export database in a bolsigdb or LXCat format.

Parameters:

• file_name (Path | str) – File name to export the database.

• species_names (str | list[str] | None, optional) – Export only given species. If None, everything is exported. Also accepts * as a completion character (e.g.: CO2* will export all species starting with CO2). Default to None.

• format (str, optional) – One amongst ‘bolsigdb’ / ‘b’, ‘lxcat’ / ‘l’ file format. Minor changes only (bolsigdb has more detailed comments). Default to ‘bolsigdb’.

• overwrite (bool, optional) – Default to False. If False, overwriting an existing file will trigger an error.

add_species(species_name: str, comment: str = '') → None

Add a new species to the database.

add_collision(species_name: str, reaction: str, rtype: str, eV: numpy.ndarray, cm2: numpy.ndarray, details: str, threshold: float = 0.0, mass_ratio: float = 0.0, comment: str = '', updated: str = '') → Collision

Add a new collision in the database.

Parameters:

• species_name (str) – New species. E.g. ‘Ar’.

• reaction (str) – Collision name. E.g: ‘Ar -> Ar^+’

• rtype (str) – Collision type. E.g: IONIZATION

• threshold (float) – Threshold energy as defined in the details line (0 for elastic collisions). Used to match Bolsig collisions (defined by the threshold energy) and collisions from LXCat.

• mass_ratio (float) – m/M as defined in the details line. (only for effective/elastic collisions)

• eV (np.ndarray) – Energy in eV.

• cm2 (np.ndarray) – Cross-sections in cm^2.

• details (str) – Details. E.g: threshold energy.

• comment (str, optional) – Comments. E.g: update date, etc.

• updated (str, optional) – Update date.

Returns:

The created collision.

Return type:

Collision

clone_collision(old_species_name: str, old_reaction: str, new_species_name: str, new_reaction: str, new_type: str = '', new_details: str = '', new_comment: str = '', new_threshold: float | None = None, shift_ev: float = 0.0, shift_cm2: float = 0.0, write_info: bool = True, positive_ev: bool = True, zero_in_zero: bool = False, ev_factor=1.0) → Collision

Create a new collision from a previous one.

Useful to add an offset in an existing collision. See the scaling model of Fridman used in [Kozak2014] to derive the cross section of vibrational excited states from the cross section of the vibrational ground state.

Parameters:

• old_species (str) – Old species.

• old_reaction (str) – Old reaction. eg: ‘Ar -> Ar^+’

• new_species_name (str) – New species

• new_reaction (str) – New reaction. eg: ‘Ar -> Ar^+’

• new_type (str, optional) – Update information of the new transition. If ‘’, the previous one will be kept. Defaults to ‘’.

• new_details (str, optional) – Update information of the new transition. If ‘’, the previous one will be kept. Defaults to ‘’.

• new_comment (str, optional) – Update information of the new transition. If ‘’, the previous one will be kept. Defaults to ‘’.

• new_threshold (float, optional) – If None, the previous threshold is taken and increased by the shift energy. Defaults to None.

• shift_ev (float, optional) – Shift the energy. Negative number will reduce the energy (eV). Defaults to 0.0.

• shift_cm2 (float, optional) – Shift the cross-sections. Defaults to 0.0.

• write_info (bool, optional) – If True, add cloning information to the comment (date, source, shift…). Defaults to True.

• positive_ev (bool, optional) – If True, negative eV are discarded. Defaults to True.

• zero_in_zero (bool, optional) – If True, forces cross section to be 0 cm^2 for 0 eV. Defaults to False.

Raises:

• ValueError – new reaction should start with new specie

• KeyError – If the old specie is not in the database

• KeyError – If a reaction in not in the database for old specie

Returns:

the cloned collision

Return type:

Collision

References

[Kozak2014]

doi/10.1088/0963-0252/23/4/045004

add_reverse_reaction(data_blocks: Collision, Ab=None, gf: int = 1, gb: int = 1, delta_e=None, warnings: bool = True) → Collision

Compute reverse reaction cross-section for reaction.

Parameters:

• data_blocks (Collision) – Collision to reverse

• Ab (str, optional) – Product specie name (new reactant). If None, read it from data_blocks. Defaults to None.

• gf (int, optional) – Degenerescence of first state. Defaults to 1.

• gb (int, optional) – Degenerescence of second state. Defaults to 1.

• delta_e (float, optional) – Energy threshold of transition (in eV). If None, infer from the minimum energy of the input transition. Defaults to None.

• warnings (bool, optional) – Check if Ab in datablocks. Defaults to True.

Examples

>>> from rizer.misc.utils import get_path_to_data
>>> from rizer.io.bolsig import LXCat
>>> bolsigdb = get_path_to_data(
...     "kin",
...     "cross_section",
...     "CO",
...     "CO_LXCat2013.txt",
... )
>>> LX = LXCat(replace_duplicates=False)
>>> LX.read(bolsigdb)
>>> LX.add_species("CO(V1)(0.266eV)", "Vibrationaly excited CO")
>>> d = LX.species["CO"].collisions["CO -> CO(V1)(0.266eV)"]
>>> LX.add_reverse_reaction(d, gf=1, gb=1)

Notes

Adapted from [Pierrot1999] Eqn. (1.11)

\[A_f + e \rightarrow A_b + e\]

Hypothesis: Af and Ab have same mass

According to the detailed balance principle, for a ‘A + B -> C + D’ reaction, we can write for the inverse reaction:

\[\sigma'(\epsilon') = \frac{m_Am_B}{m_Cm_D} \frac{g_Ag_B}{g_Cg_D} \frac{\epsilon}{\epsilon'} \sigma(\epsilon)\]

with m the mass, g the degenerence, σ the cross section and ϵ the energy

delete_reaction(species_name: str, reaction: str, ignore_if_error: bool = False)

Delete a reaction.

rename_reaction(species_name: str, reaction: str, new_reaction: str) → None

Rename a reaction.

rename_specie(old_species_name: str, new_species_name: str) → None

Rename specie and the reactions where it is a reactant.

print_all(species_names: str | list[str] | None = None) → str

Print all species and reactions in database.

plot(species_name: str, xmin: float = 0.1, xmax: float = 100, ymin: float = 0.01, ymax: float = 1000.0, replace_0_with=0, nfig=None, color='k', legend=False, show=False)

Plot all cross sections in database for species species_name.

Parameters:

• species_name (str) – Specie to plot.

• xmin (float, optional) – Minimum energy in eV. Defaults to 0.1.

• xmax (float, optional) – Maximum energy in eV. Defaults to 100.

• ymin (float, optional) – Minimum cross section in cm^2. Defaults to 1e-2.

• ymax (float, optional) – Maximum cross section in cm^2. Defaults to 1e3.

• replace_0_with (float, optional) – Because we plot in logscale, zero won’t be plotted. As a result, a triangular cross-section defined as x=(1,2,3), y=(0,1,0) will be plotted as a Dirac. replace_0_with should be used and set to exactly your ymin so that the cross-section appear correctly in log scale. Defaults to 0.

• nfig (int, optional) – Number of the figure. If None, a new figure is created. Defaults to None.

• color (str, optional) – Color of the plot. Defaults to ‘k’.

• legend (bool, optional) – If True, add legend. Defaults to False.

• show (bool, optional) – If True, show the plot. Defaults to False.

Return type:

fig, ax