plaid.containers.sample¶

Implementation of the Sample container.

Attributes¶

Self

Classes¶

Sample

Represents a single sample. It contains data and information related to a single observation or measurement within a dataset.

Module Contents¶

Self[source]¶

class Sample(/, **data: Any)[source]¶

Bases: pydantic.BaseModel

Represents a single sample. It contains data and information related to a single observation or measurement within a dataset.

By default, the sample is empty but:

You can provide a path to a folder containing the sample data, and it will be loaded during initialization.
You can provide SampleMeshes and SampleScalars instances to initialize the sample with existing data.
You can also provide a dictionary of time series data.

The default SampleMeshes instance is initialized with:

meshes=None, links=None, and paths=None (i.e., no mesh data).
mesh_base_name=”Base” and mesh_zone_name=”Zone”.

The default SampleScalars instance is initialized with:

scalars=None (i.e., no scalar data).

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

model_config[source]¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

path: str | pathlib.Path | None = None[source]¶

meshes: plaid.containers.features.SampleMeshes | None = None[source]¶

scalars: plaid.containers.features.SampleScalars | None = None[source]¶

time_series: dict[str, plaid.types.TimeSeries] | None = None[source]¶

_extra_data: dict | None = None[source]¶

model_post_init(_context: Any) → None[source]¶: Post-initialization processing for the Sample model.

copy() → Self[source]¶

Create a deep copy of the current Sample instance.

Usage of model_copy(deep=True) from Pydantic to ensure all internal data is deeply copied.

Returns:: A new Sample instance with all internal data (scalars, time series, fields, meshes, etc.) deeply copied to ensure full isolation from the original.

Note

This operation may be memory-intensive for large samples.

get_scalar(name: str) → plaid.types.Scalar | None[source]¶

Retrieve a scalar value associated with the given name.

Parameters:: name (str) – The name of the scalar value to retrieve.
Returns:: The scalar value associated with the given name, or None if the name is not found.
Return type:: Scalar or None

add_scalar(name: str, value: plaid.types.Scalar) → None[source]¶

Add a scalar value to a dictionary.

Parameters:

name (str) – The name of the scalar value.
value (Scalar) – The scalar value to add or update in the dictionary.

del_scalar(name: str) → plaid.types.Scalar[source]¶

Delete a scalar value from the dictionary.

Parameters:: name (str) – The name of the scalar value to be deleted.
Raises:: KeyError – Raised when there is no scalar / there is no scalar with the provided name.
Returns:: The value of the deleted scalar.
Return type:: Scalar

get_scalar_names() → list[str][source]¶

Get a set of scalar names available in the object.

Returns:: A set containing the names of the available scalars.
Return type:: list[str]

get_mesh(time: float | None = None, apply_links: bool = False, in_memory=False) → plaid.types.CGNSTree | None[source]¶

Retrieve the CGNS tree structure for a specified time step, if available.

Parameters:

time (float, optional) – The time step for which to retrieve the CGNS tree structure. If a specific time is not provided, the method will display the tree structure for the default time step.
apply_links (bool, optional) – Activates the following of the CGNS links to reconstruct the complete CGNS tree - in this case, a deepcopy of the tree is made to prevent from modifying the existing tree.
in_memory (bool, optional) – Active if apply_links == True, ONLY WORKING if linked mesh is in the current sample. This option follows the link in memory from current sample.

Returns:

The CGNS tree structure for the specified time step if available; otherwise, returns None.

Return type:

CGNSTree

set_default_base(base_name: str, time: float | None = None) → None[source]¶

Set the default base for the specified time (that will also be set as default if provided).

The default base is a reference point for various operations in the system.

Parameters:

base_name (str) – The name of the base to be set as the default.
time (float, optional) – The time at which the base should be set as default. If not provided, the default base and active zone will be set with the default time.

Raises:

ValueError – If the specified base does not exist at the given time.

Note

Setting the default base and is important for synchronizing operations with a specific base in the system’s data.
The available mesh base can be obtained using the get_base_names method.

Example

from plaid import Sample
sample = Sample("path_to_plaid_sample")
print(sample)
>>> Sample(2 scalars, 1 timestamp, 5 fields)
print(sample.get_physical_dim("BaseA", 0.5))
>>> 3

# Set "BaseA" as the default base for the default time
sample.set_default_base("BaseA")

# You can now use class functions with "BaseA" as default base
print(sample.get_physical_dim(0.5))
>>> 3

# Set "BaseB" as the default base for a specific time
sample.set_default_base("BaseB", 0.5)

# You can now use class functions with "BaseB" as default base and 0.5 as default time
print(sample.get_physical_dim()) # Physical dim of the base "BaseB"
>>> 3

set_default_zone_base(zone_name: str, base_name: str, time: float | None = None) → None[source]¶

Set the default base and active zone for the specified time (that will also be set as default if provided).

The default base and active zone serve as reference points for various operations in the system.

Parameters:

zone_name (str) – The name of the zone to be set as the active zone.
base_name (str) – The name of the base to be set as the default.
time (float, optional) – The time at which the base and zone should be set as default. If not provided, the default base and active zone will be set with the default time.

Raises:

ValueError – If the specified base or zone does not exist at the given time

Note

Setting the default base and zone are important for synchronizing operations with a specific base/zone in the system’s data.
The available mesh bases and zones can be obtained using the get_base_names and get_base_zones methods, respectively.

Example

from plaid import Sample
sample = Sample("path_to_plaid_sample")
print(sample)
>>> Sample(2 scalars, 1 timestamp, 5 fields)
print(sample.get_zone_type("ZoneX", "BaseA", 0.5))
>>> Structured

# Set "BaseA" as the default base and "ZoneX" as the active zone for the default time
sample.set_default_zone_base("ZoneX", "BaseA")

# You can now use class functions with "BaseA" as default base with "ZoneX" as default zone
print(sample.get_zone_type(0.5)) # type of the zone "ZoneX" of base "BaseA"
>>> Structured

# Set "BaseB" as the default base and "ZoneY" as the active zone for a specific time
sample.set_default_zone_base("ZoneY", "BaseB", 0.5)

# You can now use class functions with "BaseB" as default base with "ZoneY" as default zone and 0.5 as default time
print(sample.get_zone_type()) # type of the zone "ZoneY" of base "BaseB" at 0.5
>>> Unstructured

init_base(topological_dim: int, physical_dim: int, base_name: str | None = None, time: float | None = None) → plaid.types.CGNSNode[source]¶

Create a Base node named base_name if it doesn’t already exists.

Parameters:

topological_dim (int) – Cell dimension, see [CGNS standard](https://pycgns.github.io/PAT/lib.html#CGNS.PAT.cgnslib.newCGNSBase).
physical_dim (int) – Ambient space dimension, see [CGNS standard](https://pycgns.github.io/PAT/lib.html#CGNS.PAT.cgnslib.newCGNSBase).
base_name (str) – If not specified, uses mesh_base_name specified in Sample initialization. Defaults to None.
time (float, optional) – The time at which to initialize the base. If a specific time is not provided, the method will display the tree structure for the default time step.

Returns:

The created Base node.

Return type:

CGNSNode

init_zone(zone_shape: numpy.ndarray, zone_type: str = CGK.Unstructured_s, zone_name: str | None = None, base_name: str | None = None, time: float | None = None) → plaid.types.CGNSNode[source]¶

Initialize a new zone within a CGNS base.

Parameters:

zone_shape (np.ndarray) – An array specifying the shape or dimensions of the zone.
zone_type (str, optional) – The type of the zone. Defaults to CGK.Unstructured_s.
zone_name (str, optional) – The name of the zone to initialize. If not provided, uses mesh_zone_name specified in Sample initialization. Defaults to None.
base_name (str, optional) – The name of the base to which the zone will be added. If not provided, the zone will be added to the currently active base. Defaults to None.
time (float, optional) – The time at which to initialize the zone. If a specific time is not provided, the method will display the tree structure for the default time step.

Raises:

KeyError – If the specified base does not exist. You can create a base using Sample.init_base(base_name).

Returns:

The newly initialized zone node within the CGNS tree.

Return type:

CGLNode

set_default_time(time: float) → None[source]¶

Set the default time for the system.

This function sets the default time to be used for various operations in the system.

Parameters:: time (float) – The time value to be set as the default.
Raises:: ValueError – If the specified time does not exist in the available mesh times.

Note

Setting the default time is important for synchronizing operations with a specific time point in the system’s data.
The available mesh times can be obtained using the get_all_mesh_times method.

Example

from plaid import Sample
sample = Sample("path_to_plaid_sample")
print(sample)
>>> Sample(2 scalars, 1 timestamp, 5 fields)
print(sample.show_tree(0.5))
>>> ...

# Set the default time to 0.5 seconds
sample.set_default_time(0.5)

# You can now use class functions with 0.5 as default time
print(sample.show_tree()) # show the cgns tree at the time 0.5
>>> ...

get_field_names(location: str = None, zone_name: str | None = None, base_name: str | None = None, time: float | None = None) → list[str][source]¶

Get a set of field names associated with a specified zone, base, location, and time.

Parameters:

location (str, optional) – The desired grid location where the field is defined. Defaults to None. Possible values : plaid.constants.CGNS_FIELD_LOCATIONS
zone_name (str, optional) – The name of the zone to search for. Defaults to None.
base_name (str, optional) – The name of the base to search for. Defaults to None.
time (float, optional) – The specific time at which to retrieve field names. If a specific time is not provided, the method will display the tree structure for the default time step.

Returns:

A set containing the names of the fields that match the specified criteria.

Return type:

set[str]

link_tree(path_linked_sample: str | pathlib.Path, linked_sample: Sample, linked_time: float, time: float) → plaid.types.CGNSTree[source]¶

Link the geometrical features of the CGNS tree of the current sample at a given time, to the ones of another sample.

Parameters:

path_linked_sample (Union[str,Path]) – The absolute path of the folder containing the linked CGNS
linked_sample (Sample) – The linked sample
linked_time (float) – The time step of the linked CGNS in the linked sample
time (float) – The time step the current sample to which the CGNS tree is linked.

Returns:

The deleted CGNS tree.

Return type:

CGNSTree

show_tree(time: float | None = None) → None[source]¶

Display the structure of the CGNS tree for a specified time.

Parameters:: time (float, optional) – The time step for which you want to display the CGNS tree structure. Defaults to None. If a specific time is not provided, the method will display the tree structure for the default time step.

Examples

# To display the CGNS tree structure for the default time step:
sample.show_tree()

# To display the CGNS tree structure for a specific time step:
sample.show_tree(0.5)

add_field(name: str, field: plaid.types.Field, location: str = 'Vertex', zone_name: str | None = None, base_name: str | None = None, time: float | None = None, warning_overwrite=True) → None[source]¶

Add a field to a specified zone in the grid.

Parameters:

name (str) – The name of the field to be added.
field (Field) – The field data to be added.
zone_name (str, optional) – The name of the zone where the field will be added. Defaults to None.
base_name (str, optional) – The name of the base where the zone is located. Defaults to None.
location (str, optional) – The grid location where the field will be stored. Defaults to ‘Vertex’. Possible values : plaid.constants.CGNS_FIELD_LOCATIONS
time (float, optional) – The time associated with the field. Defaults to 0.
warning_overwrite (bool, optional) – Show warning if an preexisting field is being overwritten

Raises:

KeyError – Raised if the specified zone does not exist in the given base.

get_field(name: str, location: str = 'Vertex', zone_name: str | None = None, base_name: str | None = None, time: float | None = None) → plaid.types.Field[source]¶

Retrieve a field with a specified name from a given zone, base, location, and time.

Parameters:

name (str) – The name of the field to retrieve.
location (str, optional) – The location at which to retrieve the field. Defaults to ‘Vertex’. Possible values : plaid.constants.CGNS_FIELD_LOCATIONS
zone_name (str, optional) – The name of the zone to search for. Defaults to None.
base_name (str, optional) – The name of the base to search for. Defaults to None.
time (float, optional) – The time value to consider when searching for the field. If a specific time is not provided, the method will display the tree structure for the default time step.

Returns:

A set containing the names of the fields that match the specified criteria.

Return type:

Field

del_field(name: str, location: str = 'Vertex', zone_name: str | None = None, base_name: str | None = None, time: float | None = None) → plaid.types.CGNSTree[source]¶

Delete a field from a specified zone in the grid.

Parameters:

name (str) – The name of the field to be deleted.
location (str, optional) – The grid location where the field is stored. Defaults to ‘Vertex’. Possible values : plaid.constants.CGNS_FIELD_LOCATIONS
zone_name (str, optional) – The name of the zone from which the field will be deleted. Defaults to None.
base_name (str, optional) – The name of the base where the zone is located. Defaults to None.
time (float, optional) – The time associated with the field. Defaults to 0.

Raises:

KeyError – Raised if the specified zone or field does not exist in the given base.

Returns:

The tree at the provided time (without the deleted node)

Return type:

CGNSTree

get_nodes(zone_name: str | None = None, base_name: str | None = None, time: float | None = None) → numpy.ndarray | None[source]¶

Get grid node coordinates from a specified base, zone, and time.

Parameters:

zone_name (str, optional) – The name of the zone to search for. Defaults to None.
base_name (str, optional) – The name of the base to search for. Defaults to None.
time (float, optional) – The time value to consider when searching for the zone. If a specific time is not provided, the method will display the tree structure for the default time step.

Raises:

TypeError – Raised if multiple <GridCoordinates> nodes are found. Only one is expected.

Returns:

A NumPy array containing the grid node coordinates. If no matching zone or grid coordinates are found, None is returned.

Return type:

Optional[np.ndarray]

Seealso:: This function can also be called using get_points() or get_vertices().

set_nodes(nodes: numpy.ndarray, zone_name: str | None = None, base_name: str | None = None, time: float | None = None) → None[source]¶

Set the coordinates of nodes for a specified base and zone at a given time.

Parameters:

nodes (np.ndarray) – A numpy array containing the new node coordinates.
zone_name (str, optional) – The name of the zone where the nodes should be updated. Defaults to None.
base_name (str, optional) – The name of the base where the nodes should be updated. Defaults to None.
time (float, optional) – The time at which the node coordinates should be updated. If a specific time is not provided, the method will display the tree structure for the default time step.

Raises:

KeyError – Raised if the specified base or zone do not exist. You should first
create the base and zone using the Sample.init_zone(zone_name,base_name) method. –

Seealso:: This function can also be called using set_points() or set_vertices()

get_time_series_names() → set[str][source]¶

Get the names of time series associated with the object.

Returns:: A set of strings containing the names of the time series.
Return type:: set[str]

get_time_series(name: str) → plaid.types.TimeSeries | None[source]¶

Retrieve a time series by name.

Parameters:: name (str) – The name of the time series to retrieve.
Returns:: If a time series with the given name exists, it returns the corresponding time series, or None otherwise.
Return type:: TimeSeries or None

add_time_series(name: str, time_sequence: plaid.types.TimeSequence, values: plaid.types.Field) → None[source]¶

Add a time series to the sample.

Parameters:

name (str) – A descriptive name for the time series.
time_sequence (TimeSequence) – The time sequence, array of time points.
values (Field) – The values corresponding to the time sequence.

Example

from plaid import Sample
sample.add_time_series('stuff', np.arange(2), np.random.randn(2))
print(sample.get_time_series('stuff'))
>>> (array([0, 1]), array([-0.59630135, -1.15572306]))

Raises:: TypeError – Raised if the length of time_sequence is not equal to the length of values.

del_time_series(name: str) → tuple[plaid.types.TimeSequence, plaid.types.Field][source]¶

Delete a time series from the sample.

Parameters:: name (str) – The name of the time series to be deleted.
Raises:: KeyError – Raised when there is no time series / there is no time series with the provided name.
Returns:: A tuple containing the time sequence and values of the deleted time series.
Return type:: tuple[TimeSequence, Field]

del_all_fields() → Self[source]¶

Delete alls field from sample, while keeping geometrical info.

Returns:: The sample with deleted fields
Return type:: Sample

get_all_features_identifiers() → list[plaid.types.FeatureIdentifier][source]¶

Get all features identifiers from the sample.

Returns:: A list of dictionaries containing the identifiers of all features in the sample.
Return type:: list[FeatureIdentifier]

get_all_features_identifiers_by_type(feature_type: str) → list[plaid.types.FeatureIdentifier][source]¶

Get all features identifiers of a given type from the sample.

Parameters:: feature_type (str) – Type of features to return
Returns:: A list of dictionaries containing the identifiers of a given type of all features in the sample.
Return type:: list[FeatureIdentifier]

get_feature_from_string_identifier(feature_string_identifier: str) → plaid.types.Feature[source]¶

Retrieve a specific feature from its encoded string identifier.

The feature_string_identifier must follow the format:

“<feature_type>::<detail1>/<detail2>/…/<detailN>”

Supported feature types:

“scalar”: expects 1 detail → scalars.get(name)
“time_series”: expects 1 detail → get_time_series(name)
“field”: up to 5 details → get_field(name, base_name, zone_name, location, time)
“nodes”: up to 3 details → get_nodes(base_name, zone_name, time)

Parameters:: feature_string_identifier (str) – Structured identifier of the feature.
Returns:: The retrieved feature object.
Return type:: Feature
Raises:: AssertionError – If feature_type is unknown.

Warning

If “time” is present in a field/nodes identifier, it is cast to float.
name is required for scalar, time_series and field features.
The order of the details must be respected. One cannot specify a detail in the feature_string_identifier string without specified the previous ones.

get_feature_from_identifier(feature_identifier: plaid.types.FeatureIdentifier) → plaid.types.Feature[source]¶

Retrieve a feature object based on a structured identifier dictionary.

The feature_identifier must include a “type” key specifying the feature kind:

“scalar” → calls scalars.get(name)
“time_series” → calls get_time_series(name)
“field” → calls get_field(name, base_name, zone_name, location, time)
“nodes” → calls get_nodes(base_name, zone_name, time)

Required keys:

“type”: one of “scalar”, “time_series”, “field”, or “nodes”
“name”: required for all types except “nodes”

Optional keys depending on type:

“base_name”, “zone_name”, “location”, “time”: used in “field” and “nodes”

Any omitted optional keys will rely on the default values mechanics of the class.

Parameters:: dict[str (feature_identifier () – Union[str, float]]): A dictionary encoding the feature type and its relevant parameters.
Returns:: The corresponding feature instance retrieved via the appropriate accessor.
Return type:: Feature

get_features_from_identifiers(feature_identifiers: list[plaid.types.FeatureIdentifier]) → list[plaid.types.Feature][source]¶

Retrieve features based on a list of structured identifier dictionaries.

Elements of feature_identifiers must include a “type” key specifying the feature kind:

“scalar” → calls scalars.get(name)
“time_series” → calls get_time_series(name)
“field” → calls get_field(name, base_name, zone_name, location, time)
“nodes” → calls get_nodes(base_name, zone_name, time)

Required keys:

“type”: one of “scalar”, “time_series”, “field”, or “nodes”
“name”: required for all types except “nodes”

Optional keys depending on type:

“base_name”, “zone_name”, “location”, “time”: used in “field” and “nodes”

Any omitted optional keys will rely on the default values mechanics of the class.

Parameters:: feature_identifiers (list[FeatureIdentifier]) – A dictionary encoding the feature type and its relevant parameters.
Returns:: List of corresponding feature instance retrieved via the appropriate accessor.
Return type:: list[Feature]

_add_feature(feature_identifier: plaid.types.FeatureIdentifier, feature: plaid.types.Feature) → Self[source]¶

Add a feature to current sample.

This method applies updates to scalars, time series, fields, or nodes using feature identifiers, and corresponding feature data.

Parameters:

feature_identifier (dict) – A feature identifier.
feature (Feature) – A feature corresponding to the identifiers.

Returns:

The updated sample

Return type:

Self

Raises:

AssertionError – If types are inconsistent or identifiers contain unexpected keys.

update_features_from_identifier(feature_identifiers: plaid.types.FeatureIdentifier | list[plaid.types.FeatureIdentifier], features: plaid.types.Feature | list[plaid.types.Feature], in_place: bool = False) → Self[source]¶

Update one or several features of the sample by their identifier(s).

This method applies updates to scalars, time series, fields, or nodes using feature identifiers, and corresponding feature data. When in_place=False, a deep copy of the sample is created before applying updates, ensuring full isolation from the original.

Parameters:

feature_identifiers (dict or list of dict) – One or more feature identifiers.
features (Feature or list of Feature) – One or more features corresponding to the identifiers.
in_place (bool, optional) – If True, modifies the current sample in place. If False, returns a deep copy with updated features.

Returns:

The updated sample (either the current instance or a new copy).

Return type:

Self

Raises:

AssertionError – If types are inconsistent or identifiers contain unexpected keys.

extract_sample_from_identifier(feature_identifiers: plaid.types.FeatureIdentifier | list[plaid.types.FeatureIdentifier]) → Self[source]¶

Extract features of the sample by their identifier(s) and return a new sample containing these features.

This method applies updates to scalars, time series, fields, or nodes using feature identifiers

Parameters:: feature_identifiers (dict or list of dict) – One or more feature identifiers.
Returns:: New sample containing the provided feature identifiers
Return type:: Self
Raises:: AssertionError – If types are inconsistent or identifiers contain unexpected keys.

from_features_identifier(feature_identifiers: plaid.types.FeatureIdentifier | list[plaid.types.FeatureIdentifier]) → Self[source]¶: DEPRECATED: Use extract_sample_from_identifier() instead.

merge_features(sample: Self, in_place: bool = False) → Self[source]¶

Merge features from another sample into the current sample.

This method applies updates to scalars, time series, fields, or nodes using features from another sample. When in_place=False, a deep copy of the sample is created before applying updates, ensuring full isolation from the original.

Parameters:

sample (Sample) – The sample from which features will be merged.
in_place (bool, optional) – If True, modifies the current sample in place. If False, returns a deep copy with updated features.

Returns:

The updated sample (either the current instance or a new copy).

Return type:

Self

save(path: str | pathlib.Path, overwrite: bool = False) → None[source]¶

Save the Sample in directory path.

Parameters:

path (Union[str,Path]) – relative or absolute directory path.
overwrite (bool) – target directory overwritten if True.

classmethod load_from_dir(path: str | pathlib.Path) → Self[source]¶

Load the Sample from directory path.

This is a class method, you don’t need to instantiate a Sample first.

Parameters:: path (Union[str,Path]) – Relative or absolute directory path.
Returns:: Sample

Example

from plaid import Sample
sample = Sample.load_from_dir(dir_path)
print(sample)
>>> Sample(2 scalars, 1 timestamp, 5 fields)

Note

It calls ‘load’ function during execution.

load(path: str | pathlib.Path) → None[source]¶

Load the Sample from directory path.

Parameters:

path (Union[str,Path]) – Relative or absolute directory path.

Raises:

FileNotFoundError – Triggered if the provided directory does not exist.
FileExistsError – Triggered if the provided path is a file instead of a directory.

Example

from plaid import Sample
sample = Sample()
sample.load(path)
print(sample)
>>> Sample(3 scalars, 1 timestamp, 3 fields)

summarize() → str[source]¶

Provide detailed summary of the Sample content, showing feature names and mesh information.

This provides more detailed information than the __repr__ method, including the name of each feature.

Returns:: A detailed string representation of the sample content.
Return type:: str

Example

Sample Summary:
==================================================
Scalars (8):
- Pr: 0.9729006564945664
- Q: 0.2671142611487964
- Tr: 0.9983394202616822
- angle_in: 45.5066666666667
- angle_out: 61.89519547386746
- eth_is: 0.21238326882538008
- mach_out: 0.81003
- power: 0.0019118127462776008

Meshes (1 timestamps):
Time: 0.0
    Base: Base_2_2
        Nodes (36421)
        Tags (6): Intrado (122), Extrado (122), Inflow (121), Outflow (121), Periodic_1 (120), Periodic_2 (238)
        Fields (7): ro, sdf, rou, nut, mach, roe, rov
        Elements (36000)
        QUAD_4 (36000)
    Base: Base_1_2
        Nodes (244)
        Fields (1): M_iso
        Elements (242)
        BAR_2 (242)

check_completeness() → str[source]¶

Check the completeness of features in this sample.

Returns:: A report on feature completeness.
Return type:: str

Example

Sample Completeness Check:
==============================
Has scalars: True
Has time series: False
Has meshes: True
Total unique fields: 8
Field names: M_iso, mach, nut, ro, roe, rou, rov, sdf