Fields extraction

To simplify fields extraction and addition to the mesh, the following classes are provided.

class stagpyviz.StagField(name: str, io_utils: IOutils, mesh: YinYangMesh, scaling: Scaling | None = None)

Generic class to represent a field that can be added to the mesh. By default, this class assumes that the field is stored in a binary file output by StagYY. Different types of fields can be created by inheriting from this class and implementing their own methods to retrieve the data and add them to the mesh.

Parameters:

• name (str) – Name of the field, should correspond the the name registered in the IOutils class filelist attribute.

• io_utils (stagpyviz.IOutils) – Path and file management utilities

• mesh (stagpyviz.YinYangMesh) – Volume mesh reconstructed as an unstructured grid

• scaling (stagpyviz.Scaling|None) – Scaling factor for the field, if the field is non-dimensional and needs to be scaled to dimensional units, default: None.

add_to_mesh() → None

Add the field to the mesh using its name and the add_field method of the mesh. If the field is non-dimensional and a scaling factor is provided, the values are scaled to dimensional units before being added to the mesh.

get_data() → ndarray | None

Extract the field data from the binary file output by StagYY corresponding to the field name and the current step using the function read_stag_bin. If the file cannot be read or does not exist, the function returns None and the field will be ignored.

Returns:

A numpy array containing the field data, or None if the file could not be read.

Return type:

np.ndarray|None

get_values() → ndarray | None

Return the field values as a numpy array. If get_data returns None, the function returns None and the field will be ignored.

Returns:

Array of the shape (nx, ny, nz, nblock) where nx, ny, nz are the dimensions of the field in each direction and nblock is the number of blocks in the mesh (2 for Yin-Yang mesh).

Return type:

np.ndarray|None

reset() → None

Remove the field from the mesh and reset its values to None.

class stagpyviz.DerivedField(name: str, io_utils: IOutils, mesh: YinYangMesh, scaling: Scaling | None = None)

Class to add a field to the mesh deriving from a StagField that has already been added to the mesh.

Parameters:

• name (str) – Name of the field.

• io_utils (stagpyviz.IOutils) – Path and file management utilities

• mesh (stagpyviz.YinYangMesh) – Volume mesh.

• scaling (stagpyviz.Scaling|None) – Scaling factor for the field, if the field is non-dimensional and needs to be scaled to dimensional units, default: None.

• prefix (str) – Prefix to be added to the output file names, default: “”.

add_to_mesh() → None

Add the field to the mesh using its name. If the field is non-dimensional and a scaling factor is provided, the values are scaled to dimensional units before being added to the mesh.

class stagpyviz.Velocity(name: str, io_utils: IOutils, mesh: YinYangMesh, scaling: Scaling | None = None)

Class to extract the velocity field from the StagYY binary output.

Parameters:

• name (str) – Name of the field.

• io_utils (stagpyviz.IOutils) – Path and file management utilities

• mesh (stagpyviz.YinYangMesh) – Volume mesh.

• scaling (stagpyviz.Scaling|None) – Scaling factor for the field, if the field is non-dimensional and needs to be scaled to dimensional units, default: None.

get_values() → ndarray | None

Return the velocity field values as a numpy array. If it cannot be retrieve the function returns None and the field will be ignored.

Returns:

Array of the shape (3, nx, ny, nz, nblock), where the first dimension corresponds to the three velocity components in Cartesian coordinates.

Return type:

np.ndarray|None

class stagpyviz.Pressure(name: str, io_utils: IOutils, mesh: YinYangMesh, scaling: Scaling | None = None)

Class to extract the pressure field from the StagYY binary output.

Parameters:

• name (str) – Name of the field.

• io_utils (stagpyviz.IOutils) – Path and file management utilities

• mesh (stagpyviz.YinYangMesh) – Volume mesh.

• scaling (stagpyviz.Scaling|None) – Scaling factor for the field, if the field is non-dimensional and needs to be scaled to dimensional units, default: None.

get_values() → ndarray | None

Return the pressure field values as a numpy array. If it cannot be retrieve the function returns None and the field will be ignored.

Returns:

Array of the shape (nx, ny, nz, nblock)

Return type:

np.ndarray|None

class stagpyviz.SphericalField(name: str, io_utils: IOutils, mesh: YinYangMesh, cartesian_field: StagField)

Class to add to the mesh a spherical field transformed from a Cartesian field that has already been added to the mesh.

Note

Spherical fields are derived from Cartesian fields that have already been added to the mesh. Therefore, they are automatically scaled if the Cartesian field is scaled.

Parameters:

• name (str) – Name of the field.

• io_utils (stagpyviz.IOutils) – Path and file management utilities

• mesh (stagpyviz.YinYangMesh) – Volume mesh.

• cartesian_field (stagpyviz.StagField) – Cartesian field to be transformed into a spherical field.

get_data() → ndarray | None

Get the Cartesian field values from the mesh and return them as a numpy array. If the Cartesian field values are not already in the mesh, they are added to the mesh using the add_to_mesh method of the Cartesian field. If the Cartesian field values cannot be retrieved, the function returns None and the spherical field will be ignored.

Returns:

Array containing the Cartesian field values of the shape (mesh.number_of_points, components) for point fields or (mesh.number_of_cells, components) for cell fields, where components is the number of components of the Cartesian field (e.g. 3 for velocity).

Return type:

np.ndarray|None

get_values() → ndarray | None

Transform the field from Cartesian to spherical coordinates using the vector_cartesian_to_spherical method of the mesh.

Returns:

Array containing the spherical field values of the shape (mesh.number_of_points, components) for point fields or (mesh.number_of_cells, components) for cell fields, where components is the number of components of the Cartesian field (e.g. 3 for velocity).

Return type:

np.ndarray|None

class stagpyviz.CartesianGradient(name: str, io_utils: IOutils, mesh: YinYangMesh, field: StagField)

Class to compute and add to the mesh the gradient of a Cartesian field.

Note

The gradient of a Cartesian field is derived from the original Cartesian field that has already been added to the mesh. Therefore, it is automatically scaled if the original Cartesian field is scaled.

Parameters:

• name (str) – Name of the field.

• io_utils (stagpyviz.IOutils) – Path and file management utilities

• mesh (stagpyviz.YinYangMesh) – Volume mesh.

• field (stagpyviz.StagField) – Cartesian field for which the gradient is computed.

get_data() → ndarray | None

Get the values of the field to differentiate from the mesh.

Note

The gradient can only be computed for a point field.

Returns:

Array containing the field values of the shape (mesh.number_of_points).

Return type:

np.ndarray|None

get_values() → ndarray | None

Compute the gradient of the field using the compute_gradient method of the mesh.

Returns:

Array containing the gradient values of the shape (mesh.number_of_cells, components)

Return type:

np.ndarray|None

class stagpyviz.SphericalVectorGradient(name: str, io_utils: IOutils, mesh: YinYangMesh, field: StagField)

Class to compute and add to the mesh the gradient of a vector field in spherical coordinates with respect to spherical coordinates i.e.:

\[\begin{split}\nabla_{\mathbf r} \mathbf u = \begin{bmatrix} \partial_r u_r & \partial_r u_{\theta} & \partial_r u_{\phi} \\ \partial_{\theta} u_r & \partial_{\theta} u_{\theta} & \partial_{\theta} u_{\phi} \\ \partial_{\phi} u_r & \partial_{\phi} u_{\theta} & \partial_{\phi} u_{\phi} \\ \end{bmatrix}\end{split}\]

It proceeds in three steps:

1. It transforms the vector field from Cartesian to spherical coordinates using the vector_cartesian_to_spherical method of the mesh.

2. It computes the gradient of the spherical vector field in Cartesian coordinates using the compute_gradient method of the mesh.

3. It transforms the gradient of the vector field from Cartesian to spherical coordinates using the vector_cartesian_to_spherical method of the mesh.

get_data() → ndarray | None

Get the values of the vector field to differentiate with respect to the spherical coordinates. The vector field must be in Cartesian coordinates because the transformation to spherical is done internally.

Returns:

Vector field of the shape (number_of_cells, components)

Return type:

numpy.ndarray

get_values() → ndarray | None

Compute the gradient of a vector field in spherical coordinates with respect to the spherical coordinates.

class stagpyviz.StagSurfaceField(name: str, io_utils: IOutils, volume_mesh: YinYangMesh, surface_mesh: YinYangMesh, scaling: Scaling | None = None)

Special class to process StagYY fields defined only at the surface and at the CMB. These fields have the same structure than regular YinYang fields but they are only defined on 2 radial layers.

To properly process them we make use of an intermediate YinYangMesh that is reconstructed only with the surface and CMB layers, and then we transfer the field to the volume mesh.

Parameters:

• name (str) – Name of the field.

• io_utils (stagpyviz.IOutils) – Path and file management utilities

• volume_mesh (stagpyviz.YinYangMesh) – Volume mesh.

• surface_mesh (stagpyviz.YinYangMesh) – Surface mesh reconstructed as an unstructured grid with only the surface and CMB layers.

• scaling (stagpyviz.Scaling|None) – Scaling factor for the field, if the field is non-dimensional and needs to be scaled to dimensional units, default: None.

add_to_mesh()

Add the field to the volume mesh by transferring it from the 2 layers mesh.

stagpyviz.fields_instances(io_utils: IOutils, mesh: YinYangMesh, scalings: dict[str, Scaling] = {}) → dict[str, StagField]

Function to create and return a dictionary of field instances for the volume fields that can be added to the mesh.

Parameters:

• io_utils (stagpyviz.IOutils) – Path and file management utilities

• mesh (stagpyviz.YinYangMesh) – Volume mesh.

• scalings (dict[str, stagpyviz.Scaling]) – Dictionary of scaling factors for the fields, where the keys are the field names and the values are the corresponding Scaling instances. Default: empty dictionary, which means that all fields will be added to the mesh without scaling.

Returns:

Dictionary of field instances, where the keys are the field names and the values are the corresponding field classes instances.

Return type:

dict[str, StagField]

Current implementation:

field_classes = {}
field_classes["composition"] = StagField("composition", io_utils, mesh)
field_classes["divergence"]  = StagField("divergence", io_utils, mesh, scalings.get("strain_rate", None))
field_classes["density"]     = StagField("density", io_utils, mesh, scalings.get("density", None))
field_classes["e2"]          = StagField("e2", io_utils, mesh, scalings.get("strain_rate", None))
field_classes["nrc"]         = StagField("nrc", io_utils, mesh) # don't know what is this field
field_classes["primordial"]  = StagField("primordial", io_utils, mesh)
field_classes["proterozoic"] = StagField("proterozoic", io_utils, mesh)
field_classes["stress"]      = StagField("stress", io_utils, mesh, scalings.get("pressure", None))
field_classes["temperature"] = StagField("temperature", io_utils, mesh, scalings.get("temperature", None))
field_classes["viscosity"]   = StagField("viscosity", io_utils, mesh, scalings.get("viscosity", None))
field_classes["vorticity"]   = StagField("vorticity", io_utils, mesh, scalings.get("strain_rate", None)) # check units of this field
field_classes["basalt"]      = StagField("basalt", io_utils, mesh)
field_classes["harzburgite"] = StagField("harzburgite", io_utils, mesh)

field_classes["pressure"]    = Pressure("pressure", io_utils, mesh, scalings.get("pressure", None))
field_classes["velocity"]    = Velocity("velocity", io_utils, mesh, scalings.get("velocity", None))
field_classes["velocity_r"]  = SphericalField("velocity_r", io_utils, mesh, field_classes["velocity"])

field_classes["grad_T"]      = CartesianGradient("grad_T", io_utils, mesh, field_classes["temperature"])
field_classes["grad_T_r"]    = SphericalField("grad_T_r", io_utils, mesh, field_classes["grad_T"])
field_classes["grad_P"]      = CartesianGradient("grad_P", io_utils, mesh, field_classes["pressure"])
field_classes["grad_P_r"]    = SphericalField("grad_P_r", io_utils, mesh, field_classes["grad_P"])
field_classes["grad_v"]      = CartesianGradient("grad_v", io_utils, mesh, field_classes["velocity"])
field_classes["grad_v_r"]    = SphericalVectorGradient("grad_v_r", io_utils, mesh, field_classes["velocity"])

stagpyviz.surface_fields_instances(io_utils: IOutils, volume_mesh: YinYangMesh, surface_mesh: YinYangMesh, scalings: dict[str, Scaling] = {}) → dict[str, StagSurfaceField]

Function to create and return a dictionary of field instances for the surface fields that can be added to the mesh.

Parameters:

• io_utils (stagpyviz.IOutils) – Path and file management utilities

• volume_mesh (stagpyviz.YinYangMesh) – Volume mesh.

• surface_mesh (stagpyviz.YinYangMesh) – Surface mesh with only the surface and CMB layers.

• scalings (dict[str, stagpyviz.Scaling]) – Dictionary of scaling factors for the fields. The keys are the field names and the values are the corresponding Scaling instances. Default: empty dictionary, which means that all fields will be added to the mesh without scaling.

Returns:

Dictionary of field instances, where the keys are the field names and the values are the corresponding field classes instances.

Return type:

dict[str, StagSurfaceField]

Current implementation:

field_classes = {}
field_classes["topography"] = StagSurfaceField("topography", io_utils, volume_mesh, surface_mesh, scalings.get("length", None))
field_classes["heatflux"]   = StagSurfaceField("heatflux",   io_utils, volume_mesh, surface_mesh, scalings.get("heat_flux", None))