biogeme.monte_carlo_diagnostic module

Post-estimation Monte Carlo draw-stability diagnostics.

The diagnostic evaluates a model criterion and its gradient at a fixed estimated parameter vector using fresh draw designs. It never optimizes and constructs its JAX evaluators with second derivatives disabled.

class biogeme.monte_carlo_diagnostic.MonteCarloDiagnosticConfiguration(draw_factors, replications, time_budget_seconds, max_draws, safety_factor, objective_tolerance, gradient_tolerance, minimum_level_factor)[source]

Bases: object

Validated configuration for a diagnostic run.

Parameters:

  • draw_factors (tuple[float, ...])

  • replications (int)

  • time_budget_seconds (float)

  • max_draws (int)

  • safety_factor (float)

  • objective_tolerance (float)

  • gradient_tolerance (float)

  • minimum_level_factor (float)

as_dict()[source]

Return a YAML-safe representation.

Return type:

dict[str, Any]

classmethod from_parameters(parameters)[source]

Read and validate diagnostic settings from Biogeme parameters.

Return type:

MonteCarloDiagnosticConfiguration

Parameters:

parameters (Parameters)

validate()[source]

Validate relationships not covered by the scalar parameter system.

Return type:

None

class biogeme.monte_carlo_diagnostic.MonteCarloDiagnosticResult(data, yaml_file, markdown_file)[source]

Bases: object

Result returned by BIOGEME.check_monte_carlo_stability().

Parameters:

  • data (dict[str, Any])

  • yaml_file (Path)

  • markdown_file (Path)

property diagnostic_conclusion: str
property execution_status: str
property recommendation: str
class biogeme.monte_carlo_diagnostic.MonteCarloDiagnosticRunner(baseline, configuration, planned_tasks, evaluate_task, yaml_file, markdown_file, base_seed, limitations=None, resume=True)[source]

Bases: object

Checkpointed, interruptible execution of diagnostic tasks.

Parameters:

  • baseline (dict[str, Any])

  • configuration (MonteCarloDiagnosticConfiguration)

  • planned_tasks (list[dict[str, Any]])

  • evaluate_task (Callable[[dict[str, Any]], dict[str, Any]])

  • yaml_file (Path)

  • markdown_file (Path)

  • base_seed (int)

  • limitations (list[str] | None)

  • resume (bool)

request_stop()[source]

Request a graceful stop after the current evaluation.

Return type:

None

run()[source]

Run or resume the diagnostic and return its checkpointed result.

Return type:

MonteCarloDiagnosticResult

biogeme.monte_carlo_diagnostic.atomic_write_text(path, text)[source]

Atomically replace a UTF-8 text file.

Return type:

None

Parameters:

  • path (Path)

  • text (str)

biogeme.monte_carlo_diagnostic.atomic_write_yaml(path, data)[source]

Write a structured diagnostic checkpoint atomically.

Return type:

None

Parameters:

  • path (Path)

  • data (dict[str, Any])

biogeme.monte_carlo_diagnostic.build_draw_schedule(original_draws, configuration, draw_types)[source]

Build a unique, fast-first draw schedule.

Return type:

list[int]

Parameters:
biogeme.monte_carlo_diagnostic.build_tasks(schedule, replications, original_draws, draw_types, base_seed)[source]

Build deterministic task records sorted by expected runtime.

Return type:

list[dict[str, Any]]

Parameters:

  • schedule (list[int])

  • replications (int)

  • original_draws (int)

  • draw_types (dict[str, str])

  • base_seed (int)

biogeme.monte_carlo_diagnostic.diagnostic_conclusion(completed, original_draws, configuration)[source]

Calculate conclusion, recommendation, and machine-readable motivation.

Return type:

tuple[str, str, list[str]]

Parameters:
biogeme.monte_carlo_diagnostic.diagnostic_task_seed(base_seed, draw_count, replication)[source]

Derive a deterministic, task-specific 32-bit seed.

Return type:

int

Parameters:

  • base_seed (int)

  • draw_count (int)

  • replication (int)

biogeme.monte_carlo_diagnostic.forecast_remaining_seconds(completed, pending, safety_factor)[source]

Forecast pending runtime using median seconds per effective draw.

Return type:

float | None

Parameters:

  • completed (list[dict[str, Any]])

  • pending (list[dict[str, Any]])

  • safety_factor (float)

biogeme.monte_carlo_diagnostic.generate_diagnostic_draws(draw_types, variable_names, sample_size, number_of_draws, seed, user_generators=None)[source]

Generate one fresh, reproducible diagnostic draw design.

The global NumPy RNG state is restored afterward because Biogeme’s native generators currently use that RNG. Ordinary estimation draw behavior is therefore unaffected by diagnostic generation.

Return type:

tuple[ndarray, dict[str, str], list[str]]

Parameters:

  • draw_types (dict[str, str])

  • variable_names (list[str])

  • sample_size (int)

  • number_of_draws (int)

  • seed (int)

  • user_generators (dict[str, Any] | None)

biogeme.monte_carlo_diagnostic.generate_markdown_report(data)[source]

Generate the separate American-English diagnostic report.

Return type:

str

Parameters:

data (dict[str, Any])

biogeme.monte_carlo_diagnostic.has_antithetic_draws(draw_types)[source]

Return whether any requested draw type requires complete pairs.

Return type:

bool

Parameters:

draw_types (dict[str, str])

biogeme.monte_carlo_diagnostic.make_diagnostic_evaluator(model_elements, draw_types, variable_names, estimated_parameters, numerically_safe, user_generators)[source]

Create a task evaluator that caches JAX evaluators by draw shape.

Return type:

Callable[[dict[str, Any]], dict[str, Any]]

Parameters:

  • model_elements (ModelElements)

  • draw_types (dict[str, str])

  • variable_names (list[str])

  • estimated_parameters (dict[str, float])

  • numerically_safe (bool)

  • user_generators (dict[str, Any] | None)

biogeme.monte_carlo_diagnostic.normalize_draw_count(requested, max_draws, antithetic)[source]

Normalize a requested count while preserving antithetic pairs.

Return type:

int | None

Parameters:

  • requested (float)

  • max_draws (int)

  • antithetic (bool)

biogeme.monte_carlo_diagnostic.run_monte_carlo_diagnostic(estimation_results, model_elements, configuration, yaml_file, markdown_file, numerically_safe, user_generators, configured_seed, resume=True)[source]

Run the diagnostic using a fixed existing estimation result.

Return type:

MonteCarloDiagnosticResult

Parameters:
biogeme.monte_carlo_diagnostic.task_identity(task)[source]

Return the persistent identity of a planned or completed task.

Return type:

tuple[Any, ...]

Parameters:

task (dict[str, Any])

biogeme.monte_carlo_diagnostic.utc_now()[source]

Return a timezone-aware timestamp suitable for YAML output.

Return type:

str