Configuration

Configuration for micropurc estimation runs (JSON and TOML).

JSON is the canonical format: human-readable and loadable straight into a RunConfig. TOML loading is kept for backward compatibility with existing configuration files.

class micropurc.config.ActiveSetConfig(threshold_factor=1e-08, threshold_min=1e-10, slack_tol=0.0)[source]

Bases: object

Active-set determination parameters.

A link is active when its dual slack (the KKT sign test) is negative:

\[s_j = c_j + (A^{\top}\lambda)_j < 0 .\]
Variables:

  • threshold_factor (float) – Multiplier in the flow-magnitude threshold max(threshold_min, threshold_factor * x.max()) that route sampling uses to clean numerically negligible flows.

  • threshold_min (float) – Floor of that same threshold.

  • slack_tol (float) – A positive value tightens the cutoff above to \(-\texttt{slack\_tol}\). At the default 0.0 a link is active when its slack is strictly negative.

Parameters:
threshold_factor: float = 1e-08
threshold_min: float = 1e-10
slack_tol: float = 0.0
class micropurc.config.SolverConfig(backend='piqp', eps_abs=1e-12, eps_duality_gap_abs=1e-12, eps_rel=1e-09, eps_duality_gap_rel=1e-09, max_iter=1000, verbose=False)[source]

Bases: object

Inner quadratic-program solver parameters.

backend selects the forward solver; "piqp" is the only backend shipped with the package. Additional backends can be added by implementing the ForwardSolver protocol.

Parameters:
backend: str = 'piqp'
eps_abs: float = 1e-12
eps_duality_gap_abs: float = 1e-12
eps_rel: float = 1e-09
eps_duality_gap_rel: float = 1e-09
max_iter: int = 1000
verbose: bool = False
class micropurc.config.ProjectionConfig(mode='robust_pinv')[source]

Bases: object

Projection computation parameters.

robust_pinv is the only mode: one node row is grounded per connected component of the active subnetwork, which is the grounding under which the projection agrees with the pseudoinverse of the active incidence.

Parameters:

mode (str)

mode: str = 'robust_pinv'
class micropurc.config.EstimationConfig(max_iterations=500, fp_tol=0.0001, scale_fp_tol_by_sqrt_k=False, max_cond_H=10000.0, ls_max_tries=5, ls_tau=0.5, nm_window=3)[source]

Bases: object

Krasnoselskii-Mann fixed-point iteration parameters.

Variables:

  • max_iterations (int) – Cap on the number of fixed-point iterations.

  • fp_tol (float) – Tolerance on the residual \(\lVert \Phi_N(\beta) - \beta \rVert\).

  • scale_fp_tol_by_sqrt_k (bool) – Scale fp_tol by \(\sqrt{K}\), which holds the per-coordinate tolerance fixed as \(K\) grows.

  • max_cond_H (float) – Largest condition number of the accumulated Hessian that still counts as convergence; inf waives the check. A run can meet fp_tol at a degenerate fixed point: from an extreme start \(\beta\) explodes, the forward-QP flows saturate at their box bounds, and \(H\) turns ill-conditioned while the residual test passes because \(\Phi_N\) has flattened. Healthy fits sit at \(\mathrm{cond}(H) \approx 10^1\) to \(10^2\) and degenerate ones near \(10^6\), so the default separates the two by orders of magnitude.

  • ls_max_tries (int) – Backtracking steps allowed per iteration.

  • ls_tau (float) – Backtracking factor; trial \(m\) takes the step \(\tau^m\).

  • nm_window (int) – Number of recent merit values; an accepted trial step lands at or below their maximum.

Parameters:
max_iterations: int = 500
fp_tol: float = 0.0001
scale_fp_tol_by_sqrt_k: bool = False
max_cond_H: float = 10000.0
ls_max_tries: int = 5
ls_tau: float = 0.5
nm_window: int = 3
class micropurc.config.SpecConfig(attributes=<factory>)[source]

Bases: object

Model specification: the link attributes entering the utility.

Parameters:

attributes (list[str])

attributes: list[str]
class micropurc.config.RunConfig(name='unnamed', data_path='', network_path='', output_dir='.', num_od_pairs_to_use='all', init_beta=<factory>, seed=42, active_set=<factory>, solver=<factory>, projection=<factory>, estimation=<factory>, spec=<factory>)[source]

Bases: object

Top-level configuration for a micropurc run.

Variables:
Parameters:
name: str = 'unnamed'
data_path: str = ''
network_path: str = ''
output_dir: str = '.'
num_od_pairs_to_use: str | int = 'all'
init_beta: list[float]
seed: int = 42
active_set: ActiveSetConfig
solver: SolverConfig
projection: ProjectionConfig
estimation: EstimationConfig
spec: SpecConfig
to_dict()[source]

Convert to a plain dict suitable for JSON serialization.

Return type:

dict[str, Any]

to_json(indent=2)[source]

Serialize to a JSON string, unwrapping numpy scalars, arrays, and paths.

Parameters:

indent (int)

Return type:

str

save_json(path)[source]

Write the config to path as JSON, creating parent directories.

Returns the path written.

Parameters:

path (str | Path)

Return type:

Path

classmethod from_dict(raw)[source]

Build a RunConfig from a flat or nested dict.

Top-level scalars are read by name and each section key updates its dataclass in place; keys with no matching field are ignored, so a config carrying extra entries still loads.

Parameters:

raw (dict[str, Any])

Return type:

RunConfig

classmethod from_json(path)[source]

Load RunConfig from a JSON file.

Parameters:

path (str | Path)

Return type:

RunConfig

micropurc.config.load_config(path)[source]

Load a RunConfig from a TOML or JSON file.

Format is detected by extension: .json → JSON, anything else → TOML.

Parameters:

path (str | Path)

Return type:

RunConfig

micropurc.config.load_sim_config(path)[source]

Load a simulation experiment config from TOML or JSON.

Returns the raw dict; simulation experiments have heterogeneous structure that doesn’t warrant a fixed dataclass yet.

Parameters:

path (str | Path)

Return type:

dict[str, Any]