pyfracval.feasibility

Predict whether a (Df, kf, sigma, N) request is generable.

Moran et al. (2019) note only that FracVAL works “as long as the pair of Df and kf falls in the valid range where it is possible to generate such fractal aggregates”, without characterizing that range. This module turns the measured range into a predictive one, so the tool can say up front that a request is unlikely to succeed instead of discovering it after twenty retries.

The model is a logistic fit to benchmark_results/boundary_sweep_v2/ - 4200 trials over Df in [1.8, 2.5], kf in [0.8, 1.4], sigma in {1.0, 1.5, 1.9}, N in {64…1024}, against the current defaults. Coefficients are baked in below rather than refitted at import; refresh them with benchmarks/fit_feasibility_boundary.py after any change that moves the boundary.

Scope and honesty about it

This is a semi-empirical fit over the grid actually measured, not a theory. It is interpolation inside that box and extrapolation outside it, and it says nothing about why the boundary sits where it does. Treat a low predicted probability as “expect this to be slow and often fail”, not as proof of impossibility - the sweep itself found non-zero success at points the earlier implementation could not reach at all.

Module Contents

pyfracval.feasibility.set_coefficients(coeffs)

Install fitted coefficients (used by the fitting script).

pyfracval.feasibility.estimate_success_probability(df, kf, sigma, n)

Predicted per-trial success probability, or None if unfitted.

“Per trial” means one run_simulation call including its internal retries - the same quantity the stability sweep reports.

pyfracval.feasibility.max_feasible_df(kf, sigma, n, threshold=0.5, step=0.01)

Largest Df whose predicted success probability still exceeds threshold, scanned over the fitted range.

pyfracval.feasibility.out_of_fitted_range(df, kf, sigma, n)

Which requested parameters sit outside the fitted grid.

pyfracval.feasibility.warn_if_difficult(df, kf, sigma, n, threshold=0.5)

Emit a warning when a request looks unlikely to succeed.

Returns the warning text (also logged), or None when the request looks fine or no fit is available. Deliberately advisory: the fit is empirical, so this never blocks a run.