Supported Surface

Use this page to understand which Scenario Planner entry points Abacus supports for beta evaluation.

The planner has two primary surfaces:

  • a Python comparison API for scripted planning workflows
  • a workspace-based Dash app for interactive scenario editing and review

Recommended entry points

Use these entry points in preference order.

Entry point Use it when you want to Notes
ScenarioPlanner evaluate or compare scenarios from Python Best fit for notebooks, scripts, and testable planning flows
python -m abacus.scenario_planner launch the supported interactive app from a fitted run directory Starts the workspace UI with file-backed persistence
create_app_from_results_dir(...) embed the supported app in your own Python launcher Returns app, run_context, workspace_service, and workspace
load_workspace_bundle(...) load the fitted run and active workspace without starting Dash Useful for custom wrappers around the supported app
WorkspaceService work with saved workspaces programmatically Advanced surface for cloning, saving, evaluating, sweeping, and exporting

Advanced integration surfaces

Abacus also exposes lower-level objects such as:

  • create_scenario_planner_dash_app(...)
  • ThreadedScenarioPlannerJobRunner
  • SynchronousScenarioPlannerJobRunner
  • WorkspaceStore

These are public, but they are more implementation-shaped than the recommended entry points above. Use them when you need to embed the planner into a custom application or override the default job runner or storage behaviour.

Results directory contract

The supported launcher and load_workspace_bundle(...) expect a fitted run directory, not raw modelling inputs.

The run directory must include:

Requirement Why it matters
run_manifest.json Abacus uses it to locate the config and saved artefacts
a fit-stage idata artefact Abacus attaches the saved posterior to the rebuilt model

When metadata-stage config artifacts are present, Abacus prefers those in-run files when rebuilding the saved PanelMMM:

  • 00_run_metadata/config.resolved.yaml
  • 00_run_metadata/config.original.yaml
  • the copied config file under 00_run_metadata/

Only when those in-run config artifacts are absent does the planner fall back to run_manifest.json["config_path"].

That makes the supported loader more portable when the original config path is no longer available, but it does not guarantee full relocation across machines. The chosen config can still reference dataset files outside the run directory.

The planner can also load these optional optimisation artefacts when they are present:

  • 70_optimisation/budget_response_curves.csv
  • 70_optimisation/budget_bounds_audit.csv

When these files are available, the app can show saved saturation-reference response-curve and bounds-audit views.

What the app persists

The workspace app stores its own planning state under the fitted run directory:

Path Contents
scenario_planner/workspaces/<workspace_id>.json full persisted workspace state
scenario_planner/workspaces/<workspace_id>.manifest.json compact workspace manifest
scenario_planner/cache/cache_index.json evaluation cache index
scenario_planner/cache/evaluations/ cached evaluated scenarios
scenario_planner/exports/<workspace_id>/<export_id>/ export bundle contents
scenario_planner/exports/<workspace_id>/<export_id>.zip zipped export bundle

Workspaces persist:

  • workspace metadata such as name, owner, tags, and notes
  • draft metadata such as scenario owner, workflow status, approvals, pinning, notes, and tags
  • evaluated scenarios
  • sensitivity runs
  • revision history
  • job history
  • cache metadata

Background jobs in the supported app

The supported app launches with ThreadedScenarioPlannerJobRunner.

In the current beta:

  • draft evaluation runs as a queued background job
  • sensitivity sweeps run as queued background jobs
  • export remains synchronous, but Abacus still records it in job history

The UI currently tracks one active planner job at a time. Wait for the current evaluation or sweep to finish before starting another one from the app.

Beta scope and current limits

The current supported beta scope is:

  • local use against fitted run directories
  • file-backed workspace persistence inside the run directory
  • interactive drafting, evaluation, comparison, sensitivity sweeps, and export

Current limits to keep in mind:

  • the app does not fit or refit PanelMMM
  • the launcher starts Dash’s built-in server for local evaluation
  • the UI does not yet manage multiple active planner jobs at the same time

Next pages