pyfracval.schemas
=================

.. py:module:: pyfracval.schemas

.. autoapi-nested-parse::

   Pydantic models for simulation configuration and results data structure.





Module Contents
---------------

.. py:class:: SimulationParameters(/, **data)



   Input parameters for a FracVAL simulation run.

   Used for validation and type hinting of the simulation configuration.

   .. attribute:: N

      Target number of primary particles.

      :type: int

   .. attribute:: Df

      Target fractal dimension.

      :type: float

   .. attribute:: kf

      Target fractal prefactor.

      :type: float

   .. attribute:: rp_g

      Geometric mean radius of primary particles.

      :type: float

   .. attribute:: rp_gstd

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

      :type: float

   .. attribute:: tol_ov

      Overlap tolerance (must be > 0.0).

      :type: float

   .. attribute:: n_subcl_percentage

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

      :type: float

   .. attribute:: ext_case

      CCA sticking ext_case (0 or 1).

      :type: int

   .. attribute:: seed

      Random seed used for generation (optional).

      :type: int | None


   .. py:attribute:: model_config

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


.. py:class:: AggregateProperties(/, **data)



   Calculated properties of the final generated aggregate.


.. py:class:: GenerationInfo(/, **data)



   Information about the generation process.


.. py:class:: Metadata(/, **data)



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

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

   .. attribute:: generation_info

      Information about the run environment and time.

      :type: GenerationInfo

   .. attribute:: simulation_parameters

      The input parameters used for this simulation run.

      :type: SimulationParameters

   .. attribute:: aggregate_properties

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

      :type: AggregateProperties | None


   .. py:attribute:: model_config

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


   .. py:method:: to_dict()

      Convert the metadata model to a dictionary.

      Suitable for YAML/JSON serialization. Uses Pydantic's `model_dump`.

      :returns: A dictionary representation of the metadata.
      :rtype: dict[str, Any]



   .. py:method:: to_yaml_header()

      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.
      :rtype: str



   .. py:method:: save_to_file(folderpath, coords, radii)

      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.

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

      :raises IOError: If writing to the file fails.



   .. py:method:: from_file(filepath)
      :classmethod:


      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.

      :param filepath: Path to the FracVAL `.dat` file.
      :type filepath: str | Path

      :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.
      :rtype: tuple[Metadata | None, np.ndarray | None]

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