pyfracval.main_runner
=====================

.. py:module:: pyfracval.main_runner

.. autoapi-nested-parse::

   Core function to run the FracVAL simulation.





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

.. py:function:: run_simulation(iteration, sim_config_dict, output_base_dir = 'RESULTS', seed = None)

   Run one full FracVAL aggregate generation (PCA + CCA).

   Orchestrates the simulation pipeline:
   1. Validates input parameters using `SimulationParameters`.
   2. Sets random seed.
   3. Generates initial particle radii (lognormal distribution).
   4. Shuffles radii.
   5. Performs PCA subclustering using `Subclusterer`.
   6. Performs CCA aggregation using `CCAggregator` on the PCA results.
   7. Calculates final aggregate properties (Rg, CM).
   8. Saves results (metadata + data) using `Metadata.save_to_file`.
   9. Provides enhanced error messages and suggestions on failure.

   :param iteration: The iteration number (e.g., for generating multiple aggregates),
                     used mainly for output filenames and metadata.
   :type iteration: int
   :param sim_config_dict: Dictionary containing simulation parameters conforming to
                           `SimulationParameters` schema (N, Df, kf, rp_g, rp_gstd, etc.).
   :type sim_config_dict: dict[str, Any]
   :param output_base_dir: Base directory to save the output `.dat` file, by default "RESULTS".
   :type output_base_dir: str, optional
   :param seed: Random seed for reproducibility, by default None (time-based).
   :type seed: int | None, optional

   :returns:

             A tuple containing:
                 - success_flag (bool): True if the simulation completed successfully,
                   False otherwise.
                 - final_coords (np.ndarray | None): Nx3 array of coordinates if
                   successful, None otherwise.
                 - final_radii (np.ndarray | None): N array of radii if successful,
                   None otherwise.
   :rtype: tuple[bool, np.ndarray | None, np.ndarray | None]