pyfracval.schemas#

Pydantic models for simulation configuration and results data structure.

Module Contents#

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

Input parameters for a FracVAL simulation run.

Used for validation and type hinting of the simulation configuration.

N[source]#

Target number of primary particles.

Type:

int

Df[source]#

Target fractal dimension.

Type:

float

kf[source]#

Target fractal prefactor.

Type:

float

rp_g[source]#

Geometric mean radius of primary particles.

Type:

float

rp_gstd[source]#

Geometric standard deviation of radii (must be >= 1.0).

Type:

float

tol_ov[source]#

Overlap tolerance (must be > 0.0).

Type:

float

n_subcl_percentage[source]#

Target fraction for PCA subcluster size (0.0 < perc <= 0.5).

Type:

float

ext_case[source]#

CCA sticking ext_case (0 or 1).

Type:

int

seed[source]#

Random seed used for generation (optional).

Type:

int | None

model_config[source]#

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

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

Calculated properties of the final generated aggregate.

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.