Getting started#

Installation#

PyCroXe is publicly available on PyPI, so you can just:

pip install pycroxe

Required Python dependencies#

These will install automatically along with PyCroXe.

Required external dependencies#

These require manual installation.

Important

The MariaDB C Connector requirement it’s only mandatory for the current MariaDB Python Connector 1.1.14 release, or any previous one. With the shortly upcoming 2.0 release, it will be possible to install MariaDB Python Connector without any external dependency. If you are trying to install PyCroXe and MariaDB Python Connector is still in its 1.1.14 release, please install MariaDB C Connector first!

Usage#

tl;dr#

import numpy as np
from pycroxe import connect, get_species_properties
from pycroxe.beam import get_cross_sections_by_projectiles

energies = np.geomspace(10, 1e5, 200) # energies in eV

with connect() as conn:
    sigma = get_cross_sections_by_projectiles(
        conn,
        energies,
        initial_projectiles=["H3+", "H2+", "H+"],
        target="H2",
    )

    species_data = get_species_properties(
        conn,
        symbols=sigma.coords["product"].to_numpy().tolist(),
    )

But please, find some time to read the rest of the official docs!

Connecting#

PyCroXe provides a pycroxe.connect() function that can be used, as the name obviously suggests, to connect to any network-reachable instance of CroXe.

The intended usage is within a with statement; this will make pycroxe.connect(), if no argument is provided, return an instance of a pycroxe.CroXeConnection class, acting as a context manager, with an open connection pointing towards the default URL mariadb+mariadbconnector://croxe-guest@localhost/CroXe:

from pycroxe import connect

with connect() as conn:
    ...

PyCroXe URLs follow the SQLAlchemy pattern (dialect+driver://username@host:port/database) and can be provided to the pycroxe.connect() function, in order of descending precedence, by:

  1. directly passing them as argument

    with connect(
    "mariadb+mariadbconnector://user@server.institute.org/CroXe"
) as conn:
    ...

  2. setting up the environment variable CROXE_DB

    # if using bash
export CROXE_DB="mysql+pymysql://user@server.institute.org/CroXe"

  3. changing specific parts of the default URL with keyword arguments

    with connect(
    host="server.institute.org",
    user="user",
    connector="mariadb+mariadbconnector",
    database="CroXe_2_electric_boogaloo"
) as conn:
    ...

Note

pycroxe.connect() can also be used outside with statements, but notice that this will return a closed instance of a pycroxe.CroXeConnection class that must be opened and closed manually with the corresponding methods:

from pycroxe import connect

conn = connect()
conn.open()
...
conn.close()

At this point, if you really wish not to use a with statement, you can just use the pycroxe.CroXeConnection class instance builder, to which you can provide URLs in the same manner as to pycroxe.connect():

from pycroxe import CroXeConnection

conn = CroXeConnection("mysql+pymysql://user@server.institute.org/CroXe")
conn.open()
...
conn.close()

Caution

Using pycroxe.connect() and/or pycroxe.CroXeConnection outside with statements is strongly discouraged!

Retrieving species properties#

Function pycroxe.get_species_properties() will return a xarray Dataset of properties of all the species stored in CroXe. If given the symbols keyword argument, data will be limited only to the chosen species:

from pycroxe import connect, get_species_properties

with connect() as conn:
    species_data = get_species_properties(
        conn,
        symbols=["H+", "H2"],
    )

Retrieving beam-on-target processes cross-sections#

PyCroXe provides the pycroxe.beam module, which in turn provides the pycroxe.beam.get_cross_sections_by_projectiles() function. pycroxe.beam.get_cross_sections_by_projectiles() will first recursively find all processes that may derive from the given list of initial projectile species, and then return a 3D tensor of evaluated cross-sections, in the form of a xarray DataArray, with first dimension indexing energy values, the second indexing product species, and the last one indexing projectiles:

import numpy as np
from pycroxe import connect
from pycroxe.beam import get_cross_sections_by_projectiles

energies = np.geomspace(10, 1e5, 200) # energies in eV

with connect() as conn:
    sigma = get_cross_sections_by_projectiles(
        conn,
        energies,
        initial_projectiles=["H3+", "H2+", "H+"],
        target="H2",
    )