plaid.containers.sample¶

Implementation of the Sample container.

Attributes¶

`Self`
`CGNS_WORKER`
`FEATURES_METHODS`

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]¶

CGNS_WORKER[source]¶

FEATURES_METHODS = ['set_default_base', 'set_default_zone_base', 'resolve_base', 'resolve_zone',...[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 SampleFeatures and SampleFeatures instances to initialize the sample with existing data.

The default SampleFeatures instance is initialized with data=None (i.e., no mesh 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]¶

features: plaid.containers.features.SampleFeatures | 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, 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]

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.containers.feature_identifier.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.containers.feature_identifier.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_by_path(path: str, time: int | None = None) → plaid.types.Feature[source]¶

Retrieve a feature value from the sample’s CGNS mesh using a CGNS-style path.

Parameters:

path (str) – CGNS node path relative to the mesh root (for example “BaseName/ZoneName/GridCoordinates/CoordinateX” or “BaseName/ZoneName/Solution/FieldName”).
time (Optional[int], optional) – Time selection for the mesh. If an integer, it is interpreted via the SampleFeatures time-assignment logic (see SampleFeatures.resolve_time). If None, the default time assignment is used. Defaults to None.

Returns:

The value stored at the given CGNS path. This may be a numpy array, a scalar, or None if the node has no value.

Return type:

Feature

Note

This is a thin wrapper around CGNS.PAT.cgnsutils.getValueByPath and Sample.get_tree(time). Callers should handle a returned None when the path or value does not exist.
For field-like features, prefer using Sample.get_field which applies additional validation and selection logic.

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)
“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 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.containers.feature_identifier.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)
“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”, “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.containers.feature_identifier.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)
“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”, “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.containers.feature_identifier.FeatureIdentifier, feature: plaid.types.Feature) → Self[source]¶

Add a feature to current sample.

This method applies updates to scalars, 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.

del_feature(feature_identifier: plaid.containers.feature_identifier.FeatureIdentifier) → Self[source]¶

Remove a feature from current sample.

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

Parameters:: feature_identifier (dict) – A feature identifier.
Returns:: The updated sample
Return type:: Self
Raises:: AssertionError – If types are inconsistent or identifiers contain unexpected keys.

update_features_from_identifier(feature_identifiers: dict[int, plaid.containers.feature_identifier.FeatureIdentifier | list[plaid.containers.feature_identifier.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, 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 (FeatureIdentifier or list of FeatureIdentifier) – One or more feature identifiers.
features (dict of 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.containers.feature_identifier.FeatureIdentifier | list[plaid.containers.feature_identifier.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, 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.containers.feature_identifier.FeatureIdentifier | list[plaid.containers.feature_identifier.FeatureIdentifier]) → Self[source]¶: DEPRECATED: Use Dataset.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, 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, memory_safe: bool = False) → None[source]¶: DEPRECATED: use Sample.save_to_dir() instead.

save_to_dir(path: str | pathlib.Path, overwrite: bool = False, memory_safe: 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.
memory_safe (bool) – use pyCGNS save in a subprocess (requires an additional pickle of the sample) 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 Sample.load() method 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 meshes: True
Total unique fields: 8
Field names: M_iso, mach, nut, ro, roe, rou, rov, sdf