spyral-utils

spyral-utils is a utility library that contains some of the core functionality of Spyral. These utilities were found to be useful not just within Spyral but also continuing analysis after using Spyral. Some key utilities include:

• Nuclear masses from the AMDC AME 2020 masses
• Some histogramming and gating/cuting tools that are plotting backend agnostic
• Energy loss analysis for gas and solid targets using pycatima
• 4-vector analysis through the vector package

See the documentation for more details.

Installation

spyral-utils can be installed using pip install spyral-utils

System requirements

spyral-utils requires Python >= 3.10 and < 3.13

spyral-utils is cross-platform and tested for MacOS 14, Windows 11, and Ubuntu 22.04.

Formats

Several parts of the utilities allow for saving and creating objects from JSON. Below is an outline of the expected formats for each of these

Targets

For a gas target:

{
    "compound": [
        [1, 1, 2]
    ],
    "pressure(Torr)": 300.0
}

For a solid target:

{
    "compound": [
        [6, 12, 1]
    ],
    "thickness(ug/cm^2)": 50.0
}

For a gas mixture:

{
    "components": [
        [
            [6, 12, 1],
            [1, 1, 4],
        ],
        [
            [18, 40, 1]
        ]
    ],
    "volume_fractions": [0.1, 0.9],
    "pressure(Torr)": 50.0
}

Compound specifications are lists of elements where each element is an array of [Z, A, S]. S is the stoichiometry of that particular element in the compound. spyral-utils does not support target layers at this time (but layered targets can be built from the building blocks provided by spyral-utils). In the above examples the gas target is for ¹H₂ gas at 300 Torr pressure and the solid target is for ¹²C₁ foil with a thickness of 50 μg/cm². The gas mixutre example is for P10 gas (10% methane in argon) at 50 Torr.

2D-Cuts

The JSON description of a 2D-Cut (or 2D-gate) on data is as follows:

{
    "name": "test_cut",
    "vertices": [
        [0.0, 0.0],
        [1.0, 0.0],
        [1.0, 1.0],
        [0.0, 1.0],
        [0.0, 0.0]
    ]
}

name is a identifier given for that particular cut. verticies is a list of [x,y] coordinates which define the polygon. Note that the polygon must be closed (the final vertex must be the same as the first vertex). You can also add the xaxis and yaxis keywords to specify the names of the axes of the cut (i.e. the column names of a dataframe).

{
    "name": "test_cut",
    "xaxis": "my_x",
    "yaxis": "my_y",
    "vertices": [
        [0.0, 0.0],
        [1.0, 0.0],
        [1.0, 1.0],
        [0.0, 1.0],
        [0.0, 0.0]
    ]
}

Particle ID

The JSON description of a particle ID gate is as follows:

{
    "name": "test_cut",
    "vertices": [
        [0.0, 0.0],
        [1.0, 0.0],
        [1.0, 1.0],
        [0.0, 1.0],
        [0.0, 0.0]
    ],
    "Z": 6,
    "A": 12
}

The name and vertices fields are the same as those used by a Cut2D. The particle ID has the additional data Z and A which are the element and mass number of the associated nucleus. Like in a Cut2D you can also specify the axis names of the cut

{
    "name": "test_cut",
    "xaxis": "my_x",
    "yaxis": "my_y",
    "vertices": [
        [0.0, 0.0],
        [1.0, 0.0],
        [1.0, 1.0],
        [0.0, 1.0],
        [0.0, 0.0]
    ],
    "Z": 6,
    "A": 12
}

References

• CAtima/pycatima
• AMDC Mass Evaluation: W.J. Huang et al 2021 Chinese Phys. C 45 030002
• scipy
• numpy
• shapely
• polars
• vector

For documentation we use

• mkdocs
• mkdocs-material
• mkdocstrings

For testing we use

• pytest

Authors

• Gordon McCann
• Nathan Turi