tardis.io.model.artis.readers module

tardis.io.model.artis.readers.parse_artis_structure_to_dataclass(fname: str | Path) → ArtisData[source]

Parse an ARTIS structure file into an ArtisData object.

The first two lines of an ARTIS structure file specify the number of model cells and the model time in days. Subsequent rows provide cell indices, velocities, logarithmic densities, and the explicit mass fractions of Ni56, Co56, Fe52, and Cr48.

Parameters:

fnamestr or pathlib.Path: Path to the ARTIS structure file.

Returns:

ArtisData: Parsed structure data. time_of_model is expressed in seconds, velocity in cm/s, and mean_density in g/cm**3. isotope_mass_fractions contains rows indexed by atomic and mass number and columns indexed by ARTIS cell number. The mass_fractions field remains empty because elemental abundances are stored in a separate ARTIS file.

Raises:

AssertionError: If the number of data rows does not match the shell count declared in the file header.

Notes

The first ARTIS row represents the unused central model point. It is retained in velocity as the first shell boundary but removed from mean_density and isotope_mass_fractions. Consequently, the returned velocity array has one more entry than the shell-based arrays.

tardis.io.model.artis.readers.read_artis_composition(density_fname: str | Path, abundance_fname: str | Path) → tuple[Index, DataFrame, DataFrame][source]

Read ARTIS elemental and isotopic mass fractions.

ARTIS stores total elemental mass fractions in the abundance file and selected radioactive isotope mass fractions in the density file. This reader removes those explicit isotopes from their elemental totals so that each nuclide is represented exactly once downstream.

Parameters:

density_fnamestr or pathlib.Path: Path to the ARTIS density file.
abundance_fnamestr or pathlib.Path: Path to the ARTIS abundance file.

Returns:

indexpandas.Index: Atomic numbers for elemental mass fractions.
mass_fractionspandas.DataFrame: Elemental mass fractions indexed by atomic number.
isotope_mass_fractionspandas.DataFrame: Isotopic mass fractions indexed by atomic and mass number.

tardis.io.model.artis.readers.read_artis_density(fname: str | Path) → tuple[Quantity, Quantity, Quantity][source]

Read an ARTIS density file. Returns the time of model, velocity, and density.

Parameters:

fnamestr or pathlib.Path: Path to the ARTIS density file.

Returns:

time_of_modelastropy.units.Quantity: The time at which the model is valid, in seconds.
velocityastropy.units.Quantity: The velocity array in cm/s.
mean_densityastropy.units.Quantity: The array of mean densities in g/cm^3, excluding the first (central) value.

tardis.io.model.artis.readers.read_artis_mass_fractions(fname: str | Path, normalize: bool = True) → DataFrame[source]

Reads mass fractions from an ARTIS abundance file.

The file must have shell indices in the first column, followed by columns for each element. Each row generally corresponds to one shell.

Parameters:

fnamestr or pathlib.Path: Path to the ARTIS abundance file.
normalizebool, optional: If True, normalizes each row so the sum of mass fractions is 1. Default is True.

Returns:

pandas.DataFrame: A DataFrame with ‘atomic_number’ as its index and ‘cell_index’ as columns, holding the mass fractions for each element and shell.

tardis.io.model.artis.readers.read_artis_model(density_fname: str | Path, abundance_fname: str | Path) → ArtisData[source]

Read density and abundance files, combine them, and return a single model dataset.

Parameters:

density_fnamestr or pathlib.Path: Path to the ARTIS density file.
abundance_fnamestr or pathlib.Path: Path to the ARTIS abundance file.

Returns:

ArtisData: Combined data with time_of_model, velocity, mean_density, and mass_fractions.

tardis.io.model.artis.readers.remove_explicit_isotopes_from_elemental_mass_fractions(elemental_mass_fractions: DataFrame, isotope_mass_fractions: DataFrame) → DataFrame[source]

Remove explicitly tracked ARTIS isotopes from elemental totals.

ARTIS abundance files contain total elemental mass fractions, while the corresponding structure files separately identify selected isotopes. This function subtracts those isotope fractions from their elemental totals so that each nuclide is represented exactly once in the TARDIS composition.

Parameters:

elemental_mass_fractionspandas.DataFrame: Total elemental mass fractions. Rows are indexed by atomic number and columns correspond to model cells.
isotope_mass_fractionspandas.DataFrame: Explicit isotope mass fractions. Rows use a (atomic_number, mass_number) MultiIndex and columns correspond to model cells.

Returns:

pandas.DataFrame: Residual elemental mass fractions with explicit isotope contributions removed. The index and columns follow elemental_mass_fractions.

Notes

Isotope fractions are summed by atomic number before subtraction. Negative residuals no larger than machine precision are treated as floating-point roundoff and replaced with zero. Larger negative values are preserved for downstream composition validation.