stagyydata

Define high level structure StagyyData and helper classes.

Note

The helper classes are not designed to be instantiated on their own, but only as attributes of StagyyData instances. Users of this module should only instantiate StagyyData.

Refstate `dataclass`

Reference state profiles.

The StagyyData.refstate attribute is an instance of this class. Reference state profiles are accessed through the attributes of this object.

systems `property`

systems: list[list[DataFrame]]

Reference state profiles of phases.

It is a list of list of :class:pandas.DataFrame containing the reference profiles associated with each phase in each system.

Example

The temperature profile of the 3rd phase in the 1st system is

sdat.refstate.systems[0][2]["T"]

adiabats `property`

adiabats: list[DataFrame]

Adiabatic reference state profiles.

It is a list of :class:pandas.DataFrame containing the reference profiles associated with each system. The last item is the combined adiabat.

Example

The adiabatic temperature profile of the 2nd system is

sdat.refstate.adiabats[1]["T"]

The combined density profile is

sdat.refstate.adiabats[-1]["rho"]

Tseries `dataclass`

Time series.

The StagyyData.tseries attribute is an instance of this class.

Tseries implements the getitem mechanism. Keys are series names defined in stagpy.phyvars.TIME[_EXTRA]. Items are stagpy.datatypes.Tseries instances.

time `property`

time: NDArray[float64]

Time vector.

isteps `property`

isteps: NDArray[float64]

Step indices.

This is such that time[istep] is at step isteps[istep].

tslice

tslice(
    name: str,
    tstart: float | None = None,
    tend: float | None = None,
) -> dt.Tseries

Return a Tseries between specified times.

Parameters:

Name	Type	Description	Default
`name`	`str`	time variable.	required
`tstart`	`float \| None`	starting time. Set to None to start at the beginning of available data.	`None`
`tend`	`float \| None`	ending time. Set to None to stop at the end of available data.	`None`

at_step

at_step(istep: int) -> Series[np.float64]

Time series output for a given step.

RprofsAveraged `dataclass`

Bases: Rprofs

Radial profiles time-averaged over a StepsView.

The StepsView.rprofs_averaged attribute is an instance of this class.

The current implementation does not take into account time-changing geometry.

Steps `dataclass`

Collections of time steps.

The StagyyData.steps attribute is an instance of this class. Time steps (which are Step instances) can be accessed with the item accessor:

sdat = StagyyData(Path("path/to/run"))
sdat.steps[istep]  # Step object of the istep-th time step

Slices or tuple of istep and slices of Steps object are StepsView instances that you can iterate and filter:

for step in steps[500:]:
    # iterate through all time steps from the 500-th one
    do_something(step)

for step in steps[-100:].filter(snap=True):
    # iterate through all snapshots present in the last 100 time steps
    do_something(step)

for step in steps[0,3,5,-2:]:
    # iterate through steps 0, 3, 5 and the last two
    do_something(step)

at_time

at_time(time: float, after: bool = False) -> Step

Return step corresponding to a given physical time.

Parameters:

Name	Type	Description	Default
`time`	`float`	the physical time requested.	required
`after`	`bool`	when False (the default), the returned step is such that its time is immediately before the requested physical time. When True, the returned step is the next one instead (if it exists, otherwise the same step is returned).	`False`

Returns:

Type	Description
`Step`	the relevant step.

filter

filter(
    snap: bool = False,
    rprofs: bool = False,
    fields: Iterable[str] | None = None,
    func: Callable[[Step], bool] | None = None,
) -> StepsView

Build a StepsView with requested filters.

Snaps `dataclass`

Collection of snapshots.

The StagyyData.snaps attribute is an instance of this class. Snapshots (which are Step instances) can be accessed with the item accessor:

sdat = StagyyData(Path("path/to/run"))
sdat.snaps[isnap]  # Step object of the isnap-th snapshot

at_time

at_time(time: float, after: bool = False) -> Step

Return snap corresponding to a given physical time.

Parameters:

Name	Type	Description	Default
`time`	`float`	the physical time requested.	required
`after`	`bool`	when False (the default), the returned snap is such that its time is immediately before the requested physical time. When True, the returned snap is the next one instead (if it exists, otherwise the same snap is returned).	`False`

Returns:

Type	Description
`Step`	the relevant `Step`.

filter

filter(
    snap: bool = False,
    rprofs: bool = False,
    fields: Iterable[str] | None = None,
    func: Callable[[Step], bool] | None = None,
) -> StepsView

Build a StepsView with requested filters.

Filters `dataclass`

Filters on a step view.

passes

passes(step: Step) -> bool

Whether a given Step passes the filters.

StepsView `dataclass`

Filtered iterator over steps or snaps.

Instances of this class are returned when taking slices of StagyyData.steps or StagyyData.snaps attributes.

Parameters:

Name	Type	Description	Default
`over`	`Steps \| Snaps`	steps collection, i.e. `StagyyData.steps` or `StagyyData.snaps` attributes.	required
`items`	`Sequence[StepIndex]`	iterable of isteps/isnaps or slices.	required

rprofs_averaged `cached` `property`

rprofs_averaged: RprofsAveraged

Time-averaged radial profiles.

stepstr `cached` `property`

stepstr: str

String representation of the requested set of steps.

filter

filter(
    snap: bool = False,
    rprofs: bool = False,
    fields: Iterable[str] | None = None,
    func: Callable[[Step], bool] | None = None,
) -> StepsView

Add filters to the view.

Note that filters are only resolved when the view is iterated. Successive calls to :meth:filter compose. For example, with this code:

view = sdat.steps[500:].filter(rprofs=True, fields=["T"])
view.filter(fields=["eta"])

the produced view, when iterated, will generate the steps after the 500-th that have radial profiles, and both the temperature and viscosity fields.

Parameters:

Name	Type	Description	Default
`snap`	`bool`	if true, the step must be a snapshot to pass.	`False`
`rprofs`	`bool`	if true, the step must have rprofs data to pass.	`False`
`fields`	`Iterable[str] \| None`	list of fields that must be present to pass.	`None`
`func`	`Callable[[Step], bool] \| None`	arbitrary function returning whether a step should pass the filter.	`None`

Returns:

Type	Description
`StepsView`	self.

StagyyData `dataclass`

Generic lazy interface to StagYY output data.

Parameters:

Name	Type	Description	Default
`path_hint`	`PathLike[str] \| str`	path of the StagYY run. It can either be the path of the directory containing the par file, or the path of the par file. If the path given is a directory, the path of the par file is assumed to be path/par.	required
`read_parameters_dat`	`bool`	read `parameters.dat` file produced by StagYY. This flag can be switched off to ignore this file. This is intended for runs of StagYY that predate version 1.2.6 for which the `parameters.dat` file contained some values affected by internal logic.	`True`

path `property`

path: Path

Path of StagYY run directory.

parpath `cached` `property`

parpath: Path

Path of par file.

hdf5 `cached` `property`

hdf5: Path | None

Path of output hdf5 folder if relevant, None otherwise.

steps `cached` `property`

steps: Steps

Collection of time steps.

snaps `cached` `property`

snaps: Snaps

Collection of snapshots.

tseries `cached` `property`

tseries: Tseries

Time series data.

refstate `cached` `property`

refstate: Refstate

Reference state profiles.

par `cached` `property`

par: StagyyPar

Content of par file.

rtimes `property`

rtimes: DataFrame | None

Radial profiles times.

set_nfields_max

set_nfields_max(nfields: int | None) -> None

Adjust maximum number of scalar fields kept in memory.

Setting this to a value lower or equal to 5 raises a stagpy.error.InvalidNfieldsError. Set this to None if you do not want any limit on the number of scalar fields kept in memory. Defaults to 50.

filename

filename(
    fname: str,
    timestep: int | None = None,
    suffix: str = "",
    force_legacy: bool = False,
) -> Path

Return name of StagYY output file.

Parameters:

Name	Type	Description	Default
`fname`	`str`	name stem.	required
`timestep`	`int \| None`	snapshot number if relevant.	`None`
`suffix`	`str`	optional suffix of file name.	`''`
`force_legacy`	`bool`	force returning the legacy output path.	`False`

Returns:

Type	Description
`Path`	the path of the output file constructed with the provided segments.

stagyydata

Refstate dataclass

systems property

adiabats property

Tseries dataclass

time property

isteps property

tslice

at_step

RprofsAveraged dataclass

Steps dataclass

at_time

filter

Snaps dataclass

at_time

filter

Filters dataclass

passes

StepsView dataclass

rprofs_averaged cached property

stepstr cached property

filter

StagyyData dataclass

path property

parpath cached property

hdf5 cached property

steps cached property

snaps cached property

tseries cached property

refstate cached property

par cached property

rtimes property

set_nfields_max

filename

Refstate `dataclass`

systems `property`

adiabats `property`

Tseries `dataclass`

time `property`

isteps `property`

RprofsAveraged `dataclass`

Steps `dataclass`

Snaps `dataclass`

Filters `dataclass`

StepsView `dataclass`

rprofs_averaged `cached` `property`

stepstr `cached` `property`

StagyyData `dataclass`

path `property`

parpath `cached` `property`

hdf5 `cached` `property`

steps `cached` `property`

snaps `cached` `property`

tseries `cached` `property`

refstate `cached` `property`

par `cached` `property`

rtimes `property`