pyfracval.main_runner#

Core function to run the FracVAL simulation.

Module Contents#

pyfracval.main_runner.run_simulation(iteration, sim_config_dict, output_base_dir='RESULTS', seed=None, max_runtime_seconds=None, diagnostics=None, densities=None)[source]#

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.

Parameters:

  • iteration (int) – The iteration number (e.g., for generating multiple aggregates), used mainly for output filenames and metadata.

  • sim_config_dict (dict[str, Any]) – Dictionary containing simulation parameters conforming to SimulationParameters schema (N, Df, kf, rp_g, rp_gstd, etc.).

  • output_base_dir (str, optional) – Base directory to save the output .dat file, by default “RESULTS”.

  • seed (int | None, optional) – Random seed for reproducibility, by default None (time-based).

  • max_runtime_seconds (float | None, optional) – If set, abort and return (False, None, None) if the total elapsed wall-clock time exceeds this value between retry attempts. This allows callers to bound the worst-case runtime for parameter regions that are difficult or impossible to aggregate.

  • diagnostics (dict[str, Any] | None, optional) – If given, populated in-place with attribution for the last attempt made: failure_stage (one of “PARAMS”, “RADII_GEN”, “PCA”, “CCA”, “TIMEOUT”, or None on success), failure_reason (short human string), and attempts_used. Purely additive - callers that don’t pass this see no behavior change, which keeps this a non-breaking instrumentation hook rather than a change to the function’s return contract.

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.

Return type:

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