Utility functions

Timeseries

stagpyviz.timeseries_process(pvdfname: str | Path, start_line: int | None = None) → dict

Reads a .pvd file and extracts the time series information. It uses the specific regular expression r'(?:^(step\d+)/)?.*0(\d+)(.*)' to extract the step directory and step number from the file name. The time series information is stored in a dictionary with the following keys:

"time": list of time values as strings
"step_dir": list of step directories (e.g., “step0001/”) or empty string if not present
"step": list of step numbers as strings
"fname": list of file names as strings
"line": list of line numbers in the .pvd file where the time series information was found

Parameters:

pvdfname (str|Path) – pvd file name to process
start_line (int|None) – Line number to start processing from (default is None, which means to start from the beginning of the file)

Returns:

Dictionary containing the time series information

Return type:

dict

stagpyviz.timeseries_compare(pvdfname1: str | Path, pvdfname2: str | Path) → tuple[dict, dict | None, dict | None]

Compare two timeseries from .pvd files. If they have different number of lines, it will process the one with more lines starting from the line where they differ, and return the new timeseries along with the previous timeseries and the full timeseries. If they have the same number of lines, it will simply return the timeseries for the first file and None for the others.

Parameters:

pvdfname1 (str|Path) – pvd file name for the first timeseries
pvdfname2 (str|Path) – pvd file name for the second timeseries

Returns:

A tuple containing the new timeseries (if they differ), the previous timeseries, and the full timeseries.

Return type:

tuple[dict, dict | None, dict | None]

stagpyviz.timeseries_write_step(time: str, step: str, extension: str, prefix: str | None = None, stepdir: str = '') → str

Write a single step entry for a .pvd file. The entry is formatted as follows:

<DataSet timestep="{time}" file="{stepdir}step{step}{prefix}.{extension}"/>

where {time} is the time value, {stepdir} is the step directory (if any), {step} is the step number, {prefix} is an optional prefix for the file name, and {extension} is the file extension (e.g., “vts”).

Parameters:

time (str) – Time value for the step
step (str) – Step number for the step
extension (str) – File extension for the step file (default is “vts”)
prefix (str|None) – Optional prefix for the step file name (default is None)
stepdir (str) – Optional step directory for the step file (default is “”)

Returns:

Formatted string for the step entry in the .pvd file

Return type:

str

stagpyviz.timeseries_write_new(timeseries: dict, prefix: str | None = None, extension: str = 'vts') → str

Write a new .pvd file content for a given timeseries.

Parameters:

timeseries (dict) – Dictionary containing the time series information (as returned by timeseries_process)
prefix (str|None) – Optional prefix for the step file names (default is None)
extension (str) – File extension for the step files (default is "vts")

Returns:

Formatted string for the entire .pvd file content

Return type:

str

stagpyviz.timeseries_append(content: str, timeseries: dict, prefix: str | None = None, extension: str = 'vts') → str

Append new steps to an existing .pvd file content for a given timeseries. The function takes the existing content of the .pvd file as a list of lines, and appends new step entries for the given timeseries until it reaches the closing </Collection> tag.

Parameters:

content (list[str]) – List of lines representing the existing content of the .pvd file
timeseries (dict) – Dictionary containing the time series information (as returned by timeseries_process)
prefix (str|None) – Optional prefix for the step file names (default is None)
extension (str) – File extension for the step files (default is "vts")

Returns:

Formatted string for the entire .pvd file content with the new steps appended

Return type:

str

stagpyviz.timeseries_write(fname: str, timeseries: dict, prefix: str | None = None, extension: str = 'vts', erase: bool = False) → None

Write or append a timeseries to a .pvd file. If the file already exists and erase is False, it will append the new timeseries to the existing file content calling timeseries_append. Otherwise, it will create a new file with the given timeseries as the content calling timeseries_write_new.

Parameters:

fname (str) – File name for the .pvd file to write to
timeseries (dict) – Dictionary containing the time series information (as returned by timeseries_process)
prefix (str|None) – Optional prefix for the step file names (default is None)
extension (str) – File extension for the step files (default is "vts")
erase (bool) – Whether to erase the existing file content if the file already exists (default is False)

I/O

class stagpyviz.IOutils(model_name: str, model_dir: str, basedir: str, pvd: str, output_dir: str, output_fields: list[str], **kwargs)

Class to manage the paths and file management for the postprocessing of StagYY 3D YinYang models. This class is used to store the paths to the model directory and output directory, as well as the list of fields to be added to the output mesh. This class also contains the stepping parameters for time series processing and the time series information to be written in the pvd file.

Parameters:

model_name (str) – Name of the model.
model_dir (str) – Name of the model directory.
basedir (str) – Absolute path to the base model directory.
pvd (str) – Name of the output pvd file.
output_dir (str) – Absolute path to the output directory.
output_fields (list[str]) – List of fields that can be retrieved from binary files output by StagYY.
regions (list[str]) – List of region fields to be merged into a single regions field in the output mesh, default: [“composition”].
is_surface (bool) – Boolean indicating whether to output the surface (True) or the volume (False), default: False.
step (int) – Step number to process, if None, the entire directory will be processed, default: None.
step_start (int) – Step number to start processing, default: 0.
step_end (int) – Step number to end processing, if None, the entire directory will be processed, default: None.
dstep (int) – Step increment for processing, default: 1.
reset_fields (bool) – Boolean indicating whether to reset the timeseries, default: False.
prefix (str) – Prefix to be added to the output file names, default: “”.

Attributes:

model

Name of the model.

Type:: str
Canonical:: stagpyviz.IOutils.model

mdir

Name of the model directory.

Type:: str
Canonical:: stagpyviz.IOutils.mdir

basedir

Absolute path to the directory containing the model directory.

Type:: str
Canonical:: stagpyviz.IOutils.basedir

model_dir

Absolute path to the model directory. Constructed from basedir and mdir.

Type:: str
Canonical:: stagpyviz.IOutils.model_dir

output_dir

Absolute path to the output directory.

Type:: str
Canonical:: stagpyviz.IOutils.output_dir

output_fields

List of fields that can be retrieved from binary files output by StagYY.

Type:: list[str]
Canonical:: stagpyviz.IOutils.output_fields

pvd

Name of the output pvd file.

Type:: str
Canonical:: stagpyviz.IOutils.pvd

prefix

Prefix to be added to the output file names.

Type:: str
Canonical:: stagpyviz.IOutils.prefix

time

Time value for the current step. Initialized to None, filled when processing the binary files.

Type:: float|None
Canonical:: stagpyviz.IOutils.time

timeseries

Dictionary to store the time series information to be written in the pvd file. Initialized with empty lists for “time” and “step”.

Type:: dict[str, list]
Canonical:: stagpyviz.IOutils.timeseries

regions

List of region fields to be merged into a single regions field in the output mesh.

Type:: list[str]
Canonical:: stagpyviz.IOutils.regions

is_surface

Boolean indicating whether to output the surface (True) or the volume (False).

Type:: bool
Canonical:: stagpyviz.IOutils.is_surface

step

Step number. Initialized to provided step argument, or None if not provided.

Type:: int|None
Canonical:: stagpyviz.IOutils.step

step_start

Step number from which to start processing. Initialized to provided step_start argument, or 0 if not provided.

Type:: int
Canonical:: stagpyviz.IOutils.step_start

step_end

Step number at which to end processing. Initialized to provided step_end argument, or None if not provided.

Type:: int|None
Canonical:: stagpyviz.IOutils.step_end

steps_idx

Numpy array of step numbers to process, generated from step_start, step_end and dstep. Initialized to None if step_end is not provided.

Type:: np.ndarray|None
Canonical:: stagpyviz.IOutils.steps_idx

volume_fields

Dictionary mapping the names of the volume fields that can be retrieved from binary files output by StagYY to their raw names in the binary files.

Type:: dict[str, str|tuple[str]]
Canonical:: stagpyviz.IOutils.volume_fields

surface_fields

Dictionary mapping the names of the surface fields that can be retrieved from binary files output by StagYY to their raw names in the binary files.

Type:: dict[str, str|tuple[str]]
Canonical:: stagpyviz.IOutils.surface_fields

filelist

Dictionary mapping the names of all the fields that can be retrieved from binary files output by StagYY (both volume and surface fields) to their raw names in the binary files.

Type:: dict[str, str|tuple[str]]
Canonical:: stagpyviz.IOutils.filelist

Currently the supported fields that can be retrieved from binary files output by StagYY are:

volume_fields = {
  "basalt":      "bs",
  "composition": "c",
  "density":     "rho",
  "divergence":  "div",
  "e2" :         "ed",
  "harzburgite": "hz",
  "nrc":         "nrc", # ??
  "pressure":    "vp", # pressure is stored in the 4th component of the velocity file
  "primordial":  "prm",
  "proterozoic": "prot",
  "stress" :     "str",
  "temperature": ("t", "T"),
  "tracer":      "tra",
  "velocity":    "vp",
  "viscosity":   "eta",
  "vorticity":   "vor"
}

surface_fields = {
  "topography":  "cs",
  "heatflux":    "hf",
}

filelist = {
  **volume_fields,
  **surface_fields
}

compose_filename(field: str, step: int) → str | None

Return the path to the binary file corresponding to the given field and step number, if it exists, otherwise return None. The filename is reconstructed such that:

fname = f"{model_name}_{field}{step:05d}"
fpath = os.path.join(basedir, model_dir, fname)

Parameters:

field (str) – StagYY name of the field to retrieve.
step (int) – Step number to retrieve.

Return str|None:

Path to the binary file corresponding to the given field and step number, if it exists, otherwise None.

get_field_filename(field: str, step: int) → str | None

Return the path to the binary file corresponding to the given field and step number, if it exists, otherwise return None. This function uses the filelist dictionary to find the raw name of the field, and then uses the compose_filename method to reconstruct the filename and check if it exists. If the field is not found in the filelist, or if the file does not exist, None is returned.

Parameters:

field (str) – Name from the filelist of the field to retrieve.
step (int) – Step number to retrieve.

Return str|None:

Path to the binary file corresponding to the given field and step number, if it exists, otherwise None.