Internal diagnostic/telemetry data produced by pyfracval.overlap_statistics.compute_overlap_census when OrchestratorAlgorithmConfig.cca_overlap_census_enabled is set - strictly opt-in, off the default hot path. Not part of a saved aggregate’s output metadata (see AggregateProperties for that); this is per-attempt diagnostic data consumed by benchmark harnesses.

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

class pyfracval.schemas.GenerationInfo(/, **data)[source]#: Information about the generation process.

class pyfracval.schemas.Metadata(/, **data)[source]#

Complete output model including parameters, properties, and generation info.

Designed for easy serialization (e.g., to YAML in header).

generation_info[source]#

Information about the run environment and time.

Type:: GenerationInfo

simulation_parameters[source]#

The input parameters used for this simulation run.

Type:: SimulationParameters

aggregate_properties[source]#

Calculated properties of the final aggregate (None if calculation failed).

Type:: AggregateProperties | None

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

to_dict()[source]#

Convert the metadata model to a dictionary.

Suitable for YAML/JSON serialization. Uses Pydantic’s model_dump.

Returns:: A dictionary representation of the metadata.
Return type:: dict[str, Any]

to_yaml_header()[source]#

Generate a commented YAML header string for file output.

Serializes the metadata to a multi-line YAML string where each line is prefixed with ‘# ‘.

Returns:: The formatted YAML header string.
Return type:: str

save_to_file(folderpath, coords, radii)[source]#

Save metadata (as YAML header) and numerical data to a file.

Constructs a filename based on simulation parameters and timestamp. Writes the YAML header followed by the coordinate and radius data formatted as space-delimited columns.

Parameters:

folderpath (str | Path) – The directory where the output file will be saved.
coords (np.ndarray) – Nx3 NumPy array of final particle coordinates.
radii (np.ndarray) – N NumPy array of final particle radii.

Raises:

IOError – If writing to the file fails.

classmethod from_file(filepath)[source]#

Load metadata and data from a FracVAL output file.

Parses the commented YAML header to reconstruct the Metadata object and loads the subsequent numerical data into a NumPy array.

Parameters:

filepath (str | Path) – Path to the FracVAL .dat file.

Returns:

A tuple containing:

The loaded Metadata object, or None if the header is missing, invalid, or fails validation.
The loaded Nx4 NumPy data array [X, Y, Z, R], or None if data loading fails or the data is invalid.

Return type:

tuple[Metadata | None, np.ndarray | None]

Raises:

FileNotFoundError – If the specified filepath does not exist.
Exception – If YAML parsing fails or loaded data has unexpected dimensions.

class pyfracval.schemas.ClusterEntry(/, **data)[source]#: One row of a cluster_index.csv master index (see pyfracval.catalog) – the generation parameters and output path for a single generated aggregate, without loading its (potentially large) coordinate/radius data. Use Metadata.from_file(entry.filepath) when the actual geometry is needed.