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

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

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

Time vector.

isteps `property`

isteps: NDArray

Step indices.

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

tslice

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

Return a Tseries between specified times.

Parameters:

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

at_step

at_step(istep: int) -> Series

Time series output for a given step.

RprofsAveraged

Bases: Rprofs

Radial profiles time-averaged over a StepsView.

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

It implements the same interface as Rprofs but returns time-averaged profiles instead.

stepstr `property`

stepstr: str

String representation of steps indices.

Steps

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: Optional[Iterable[str]] = None,
    func: Optional[Callable[[Step], bool]] = None,
) -> StepsView

Build a StepsView with requested filters.

Snaps

Bases: Steps

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`.

StepsView

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
`steps_col`	`Union[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 `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: Optional[Iterable[str]] = None,
    func: Optional[Callable[[Step], bool]] = 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`	`Optional[Iterable[str]]`	list of fields that must be present to pass.	`None`
`func`	`Optional[Callable[[Step], bool]]`	arbitrary function returning whether a step should pass the filter.	`None`

Returns:

Type	Description
`StepsView`	self.

StagyyData

Generic lazy interface to StagYY output data.

Parameters:

Name	Type	Description	Default
`path`	`PathLike`	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`

Attributes:

Name	Type	Description
`steps`	`Steps`	collection of time steps.
`snaps`	`Snaps`	collection of snapshots.
`refstate`	`Refstate`	reference state profiles.

path `property`

path: Path

Path of StagYY run directory.

parpath `property`

parpath: Path

Path of par file.

hdf5 `cached` `property`

hdf5: Optional[Path]

Path of output hdf5 folder if relevant, None otherwise.

par `cached` `property`

par: StagyyPar

Content of par file.

rtimes `property`

rtimes: Optional[DataFrame]

Radial profiles times.

nfields_max `property` `writable`

nfields_max: Optional[int]

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: Optional[int] = 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`	`Optional[int]`	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

systems property

adiabats property

Tseries

time property

isteps property

tslice

at_step

RprofsAveraged

stepstr property

Steps

at_time

filter

Snaps

at_time

StepsView

rprofs_averaged property

stepstr cached property

filter

StagyyData

path property

parpath property

hdf5 cached property

par cached property

rtimes property

nfields_max property writable

filename

systems `property`

adiabats `property`

time `property`

isteps `property`

stepstr `property`

rprofs_averaged `property`

stepstr `cached` `property`

path `property`

parpath `property`

hdf5 `cached` `property`

par `cached` `property`

rtimes `property`

nfields_max `property` `writable`