rizer.io.bolsig#

A BolsigSession class to run Bolsig from the command line.

Also contains is_bolsig_proof function that makes sure a Bolsig database can be read AND USED by Bolsig with no damage (for instance, as of 30/06/2016 Bolsig doesn’t notify if duplicate reactions are found in the database… and this changes the results)

TODO:

  • test nreac with multiple gas composition

  • allow parameters chosen by 1, 2, 3 to be chosen by letters

  • fix get_log parsing only the first species

  • fix identification problem when different collisions with same threshold

Attributes#

bg

Classes#

BolsigSession

Run a Bolsig+ [Bolsig] case.

Functions#

is_bolsig_proof(→ bool)

Make sure a bolsigdb file can be read AND USED by Bolsig with no damage.

Module Contents#

rizer.io.bolsig.is_bolsig_proof(bolsigdb: str | pathlib.Path) → bool#

Make sure a bolsigdb file can be read AND USED by Bolsig with no damage.

For instance, as of 30/06/2016 Bolsig doesn’t notify if duplicate reactions are found in the database… and this changes the results.

Parameters:

bolsigdb (str | Path) – Path to a Bolsig database (downloaded from LXCat, or generated).

Returns:

True if the database is Bolsig-proof, False otherwise.

Return type:

bool

class rizer.io.bolsig.BolsigSession(bolsigdir: pathlib.Path | None = None, overwrite: bool = False, verbose: bool = True)#

Run a Bolsig+ [Bolsig] case.

Parameters:

  • bolsigdir (str | Path | None, optional) – Path of the bolsigminus executable. If None, then bolsigminus is called from bolsig.py folder. Defaults to None.

  • overwrite (bool, optional) – If True, instruction files and output files are overwritten without raising an error. Defaults to False.

  • verbose (bool, optional) – If True, print information on the ongoing processus. Defaults to True.

Examples

Run a full session with N2:

>>> from rizer.misc.utils import get_path_to_data
>>> from rizer.io.bolsig import BolsigSession
>>> bg = BolsigSession(overwrite=True, verbose=False)
>>> bg.read_collisions(
...     species="N2",
...     cross_sections_database_path=get_path_to_data(
...         "kin", "bolsigdb", "LXCat-default.txt"
...     ),
... )
>>> bg.set_conditions()
>>> bg.set_series("E/N", m=0.1, M=100, n=30, typ="linear")
>>> bg.set_outputs()
>>> bg.run(show_log=False)
>>> bg.plot()
>>> energy = bg.output["energy"]  # for the energy losses fraction

Notes

The principles of BOLSIG+ can be summarized as follows:

The electric field and all collision probabilities are assumed to be uniform. The angular dependence of the electron distribution is approximated by the classical two-term expansion. The change in the electron number density due to ionization or attachment is accounted for by an exponential growth model using the above assumptions. The Boltzmann equation then reduces to a convection-diffusion continuity-equation with a non-local source term in energy space, which is discretized by an exponential scheme and solved for the electron energy distribution function by a standard matrix inversion technique.

(from http://www.laplace.univ-tlse.fr/)

Run Bolsig to compute energy fraction loss in CH₄.

Run Bolsig to compute energy fraction loss in CH₄.
bolsigdir: pathlib.Path = None#
overwrite: bool = False#
verbose: bool = True#
instruction_file: pathlib.Path#
log_file: pathlib.Path#
output_file: pathlib.Path#
species: list[str] = []#
database: list[str] = []#
LX_collisions: dict[str, dict[str, rizer.io.lxcat.Collision]]#
transport_conditions#
reactions: dict[str, rizer.io.lxcat.Collision]#
nb_reactions: int#
output_properties#
output: dict[str, pandas.DataFrame]#
nb_runs: int#
plot_style: dict[str, str]#
read_collisions(species: str, cross_sections_database_path: pathlib.Path = get_path_to_data('kin', 'bolsigdb', 'LXCat-default.txt'), extrapolate: bool = True) → None#

Tell Bolsig which species in which database to use.

You can call this function several times to add several species. Also parse the database with the LXCat module to retrieve information and comments on the collisions used.

Parameters:

  • species (str) – Species to load from the database

  • cross_sections_database_path (Path, optional) – Path to the cross sections database. By default will look for a database in ./data/kin/bolsigdb.

  • extrapolate (bool, optional) – Extrapolate cross-sections. Defaults to True.

Examples

Read collisions from N2:

>>> from rizer.io.bolsig import BolsigSession
>>> bg = BolsigSession()
>>> bg.read_collisions(species="N2")
set_conditions(E_N: float = 100, ω_N: float = 0, cos: float = 0, T_gas: float = 300, T_exc: float = 300, U_tr: float = 0, ionization_deg: float = 0, n_gas: float = 1e+21, Z: float = 1, ion_neutral_mass_ratio: float = 1, coulomb_model: bool = True, energy_sharing: int | str = 1, growth: int | str = 1, mean_energy: float = 0, nb_grid: int = 200, manual_grid: int = 0, max_energy: float = 200, eps: float = 1e-10, convergence: float = 0.0001, nb_iterations: int = 1000, gas_fraction: list[float] | None = None, norm: bool = True) → None#

Set conditions for calculation.

Refer to Bolsig Manual [Bolsig] for more details.

Parameters:

  • E_N (float, optional) – Reduced Electric field [Td]. Will be overriden anyway if using set_series() afterwards. Defaults to 100.

  • ω_N (float, optional) – Reduced angular field frequency [m^3.rad/s]. Defaults to 0. Set to 0 for DC E-field.

  • cos (float, optional) – Cosine of E-B field angle. Defaults to 0.

  • T_gas (float, optional) – Gas temperature [K]. Defaults to 300.

  • T_exc (float, optional) – Excitation temperature [K]. Defaults to 300. Set to 0 to skip superelastic collisions.

  • U_tr (float, optional) – Transition energy [eV]. Defaults to 0.

  • ionization_deg (float, optional) – Ionization degree. Defaults to 0. Set to 0 for standard usage (=no Coulomb collisions).

  • n_gas (float, optional) – Gas particle density [1/m^3]. Defaults to 1e21. Warning: Before 2020, this was the plasma density (1/m^3).

  • Z (float, optional) – Ion charge parameter. Defaults to 1.

  • ion_neutral_mass_ratio (float, optional) – Ion/neutral mass ratio. Defaults to 1.

  • coulomb_model (bool, optional) – e-e momentum effects. Defaults to True.

  • energy_sharing (int | str, optional) – Energy sharing. 1 means ‘Equal’, 2 means ‘One takes all’. Defaults to 1.

  • growth (int | str, optional) – Growth: 1=Temporal*, 2=Spatial, 3=Not included, 4=Grad-n expansion. Defaults to 1.

  • mean_energy (float, optional) – Maxwellian mean energy [eV]. Defaults to 0. Set to 0 to solve Boltzmann equation.

  • nb_grid (int, optional) – Number of grid points. Defaults to 200.

  • manual_grid (int, optional) – Manual grid: 0=No, 1=Linear, 2=Parabolic. Defaults to 0.

  • max_energy (float, optional) – Manual maximum energy (eV). Defaults to 200.

  • eps (float, optional) – Precision. Defaults to 1e-10.

  • convergence (float, optional) – Convergence. Defaults to 1e-4.

  • nb_iterations (int, optional) – Maximum number of iterations. Defaults to 1000.

  • gas_fraction (list[float] | None, optional) –

    Gas composition mole fractions. Defaults to None. If None, then, the following is done:

    • If there is only one species in self.species, set it to 1.0.

    • If the species are [‘O2’, ‘N2’], assume it is air and use 0.2 / 0.8

    • Else, assume equipartition of all species.

  • norm (bool, optional) – Normalize composition to unity. Defaults to True.

Raises:

ValueError – If one of the arguments is not correct

See also

set_series()

run(show_log: bool = True)#

Compute everything needed.

  • Build the instruction file,

  • Copy it to the Bolsig folder,

  • Run the program,

  • Then, move back the output.

set_series(variable: str | int = 'E/N', m: float = 0.1, M: float = 100, n: int = 30, typ: str | int = 'linear') → None#

Set a range of variable to calculate from m to M.

Parameters:

  • variable (str | int, optional) – One of [‘E/N’, ‘mean’, ‘maxwellian’] or [1, 2, 3]. Variable: - 1=E/N: Td - 2=Mean energy: eV - 3=Maxwellian energy: eV Defaults to ‘E/N’.

  • m (float, optional) – Minimum. Defaults to 0.1.

  • M (float, optional) – Maximum. Defaults to 100.

  • n (int, optional) – Number of runs. Defaults to 30.

  • typ (str | int, optional) – One of [‘linear’, ‘quadratic’, ‘exponential’] or [1, 2, 3]. Defaults to ‘linear’.

Raises:

ValueError – If variable or typ is not correct

See also

set_conditions()

get_log(show_log: bool = True)#

Read and print log_file.

Add reactions.

set_outputs(format: int = 2, conditions: bool = True, transport: bool = True, rate: bool = True, reverse_rate: bool = True, energy_losses_coef: bool = True, distribution: bool = True, skip_failed: bool = False) → None#

Choose where to write the output.

Parameters:

  • file (Path, optional) – Output file. Defaults to ‘bolsig_output.txt’.

  • format (int, optional) –

    Format:

    • 1=Run by run

    • 2=Combined

    • 3=Separate

    • 4=E/N

    • 5=Energy

    • 7=PLASIMO

    Defaults to 2.

  • conditions (bool, optional) – Return conditions. Defaults to True.

  • transport (bool, optional) – Return transport coefficients. Defaults to True.

  • rate (bool, optional) – Return rate coefficients. Defaults to True.

  • reverse_rate (bool, optional) – Return reverse_rate rate coefficients. Defaults to True.

  • energy_losses_coef (bool, optional) – Return energy loss coefficients. Defaults to True.

  • distribution (bool, optional) – Return distribution function. Defaults to True.

  • skip_failed (bool, optional) – Skip failed runs. Defaults to False.

parse_output() → None#

Parse the output file of the BolsigMinus simulation.

plot(properties_to_plot: str | list[str] | None = None, plot_x: str = 'E/N', log_scale: bool = False) → None#

Plot the output of the calculation.

Parameters:

  • properties_to_plot (str | list[str] | None, optional) – List of properties to plot. If None, plot everything. Defaults to None.

  • plot_x (str, optional) – Plot electric field (‘E/N’) or energy (‘eV’). Defaults to ‘E/N’ (Td). #TODO: if ‘eV’, I don’t know if it’s the mean energy or Maxwellian energy. Look up Bolsig+ doc and correct here :)

  • log_scale (bool, optional) – If True, plot energies on log_scale. Defaults to False.

Examples

>>> from rizer.misc.utils import get_path_to_data
>>> from rizer.io.bolsig import BolsigSession
>>> bg = BolsigSession(verbose=False)
>>> bg.read_collisions(
...     species="N2",
...     cross_sections_database_path=get_path_to_data(
...         "kin", "bolsigdb", "LXCat-default.txt"
...     ),
... )
>>> bg.set_conditions()
>>> bg.set_series("E/N", m=0.1, M=100, n=30, typ="linear")
>>> bg.set_outputs()
>>> bg.run(show_log=False)
>>> bg.plot()
>>> bg.plot("energy")

See also

plot_fraction_losses()

plot_fraction_losses(log_scale: bool = False) → tuple[matplotlib.pyplot.Figure, matplotlib.pyplot.Axes]#

Calculate and plot fraction.

Parameters:

log_scale (bool, optional) – If True, log scale for x & y-axis. Defaults to False.

Examples

>>> from rizer.io.bolsig import BolsigSession
>>> from rizer.misc.utils import get_path_to_data
>>> bolsigdb = get_path_to_data("kin", "bolsigdb", "bolsigdb.dat")
>>> bg = BolsigSession(overwrite=True, verbose=False)
>>> bg.read_collisions(
...     species="CH4", cross_sections_database_path=bolsigdb, extrapolate=False
... )
>>> bg.set_conditions()
>>> bg.set_series("E/N", m=0.1, M=100, n=30, typ="linear")
>>> bg.set_outputs()
>>> bg.run(show_log=False)
>>> fig, ax = bg.plot_fraction_losses(log_scale=True)

See also

plot(),

get(parameter: str)#

Get parameters.

Warning

only few parameters defined yet

Parameters:

parameter (str) – Parameter to get. For now, only ‘alpha’ (or ‘α’, first Townsend coefficient) is defined.

rizer.io.bolsig.bg#