pyfracval

Core package for PyFracVAL, a fractal aggregate generator.

Submodules

• pyfracval.app
• pyfracval.batch_runner
• pyfracval.catalog
• pyfracval.cca
• pyfracval.cca_agg
• pyfracval.cca_kernels
• pyfracval.correlation
• pyfracval.dask_runner
• pyfracval.densify
• pyfracval.environments
• pyfracval.event_log
• pyfracval.experimental
• pyfracval.feasibility
• pyfracval.fractal
• pyfracval.gap_scaling
• pyfracval.geometry
• pyfracval.main_runner
• pyfracval.overlap
• pyfracval.overlap_statistics
• pyfracval.particle_generation
• pyfracval.pca_agg
• pyfracval.pca_kernels
• pyfracval.pca_subclusters
• pyfracval.quality
• pyfracval.schemas
• pyfracval.utils
• pyfracval.visualization

Package Contents

pyfracval.filter_catalog(entries, *, sigma=None, Df=None, N=None, kf=None, config=None, success_only=True)

Filter catalog entries by generation parameters.

Each keyword accepts either a single value (exact match) or an iterable of allowed values; None (the default for all but success_only) means “don’t filter on this field”. success_only (default True) drops any entry with success=False before applying the other filters – a failed generation attempt has no usable geometry.

pyfracval.load_catalog(index_path, data_root=None)

Load every row of a cluster_index.csv as a list of ClusterEntry.

index_path’s filepath column holds an absolute path from wherever the data was originally generated – not portable across machines or repos that keep their own copy of the same aggregate files. When data_root is given, each entry’s filepath is re-based under it instead of trusting the stored absolute path: the last 3 path components (<config>/<sigma_..__Df_..__N_..>/<filename>.dat) are the part of the layout scripts/generate_cluster_data.py actually guarantees, so re-joining just those under data_root is reliable regardless of where the CSV says the file used to live. When data_root is None, filepath is used as-is (verbatim from the CSV).

pyfracval.compute_gap_scale(coords, radii, gap_factor, mode='average')

Return the position-only scale factor that achieves gap_factor.

Parameters:

• coords ((N, 3) array) – Particle center positions.

• radii ((N,) array) – Particle radii, same units as coords.

• gap_factor (float or None) – Target minimum surface-to-surface gap between neighboring particles, as a multiple of the mean particle radius. None or 0 means no gap requirement – returns 1.0 (the touching, as-generated case; a no-op for a caller that then does positions *= scale). Must be >= 0.

• mode ({"average", "strict"}) –

  How gap_factor becomes a scale factor:

  • "average" (default, matching YASF’s own default): a cheap closed-form estimate from the mean radius, s = max(1, 1 + gap_factor / 2). Does not guarantee every pair individually clears the target gap for irregular (non-uniform-density) aggregates.

  • "strict": exact, via a KD-tree nearest-neighbor query – finds the scale that gives the closest pair exactly the target gap, which (since scaling every position by one global factor scales every pairwise distance by that same factor) guarantees every other pair, starting further apart, clears it too.

Returns:

The scale factor s such that coords * s achieves the requested gap. Always >= 1.0.

Return type:

float

Raises:

ValueError – If gap_factor is negative, mode is not one of the values above, or the resulting scale fails to eliminate all overlaps (checked directly, not assumed from the formula/computation).

class pyfracval.ClusterEntry(/, **data)

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.