From dependency graph to auditable RiskPack.

60-second start

Install and produce a verified demo pack

pip install "cascadelens @ git+https://github.com/limingrui679-design/CascadeLens.git@v0.5.0"
cascadelens demo --out demo-riskpack

The demo writes a checksummed RiskPack and verifies it before exiting. It is a reproducibility example, not empirical validation.

Bring your own graph

Analyze CSV, JSON, or GraphML

cascadelens run \
  --graph examples/data/simple_edges.csv \
  --out my-analysis.json

With no ShockScript, the CLI creates an explicit synthetic starter shock on the first node. Imported topology is conservatively labelled MODEL_INFERRED. Add explicit evidence metadata when you can support a stronger claim.

Follow the graph-import tutorial ↗

Evidence envelope

Recompute an exported RiskPack

cascadelens verify my-riskpack

Verification checks file digests, reloads the packaged graph and scenario, and recomputes cascade bounds, intervention rankings, and benchmark status. A valid pack proves internal consistency—not real-world accuracy.

Python API

Use the engine in analysis code

from cascadelens import analyze, default_scenario, load_graph

graph = load_graph("examples/data/simple_graph.graphml")
scenario = default_scenario(graph, magnitude=0.6)
result = analyze(graph, scenario)

print(result.bounds["central"]["totalWeightedImpact"])
print(result.benchmark["status"])

NetworkX adapters are available through cascadelens[networkx]. The public Python engine is parity-tested against all 12 published reference cases.

Jupyter

Inspect each step interactively

pip install "cascadelens[notebook] @ git+https://github.com/limingrui679-design/CascadeLens.git@v0.5.0"
jupyter lab examples/notebooks/bring_your_own_graph.ipynb

The notebook keeps graph import, shock definition, uncertainty bounds, and intervention comparison visible as separate steps.

Formal specification

Know what the model does—and where it fails

The methods note defines the daily cascade equations, evidence grades, baseline relationships, intervention objective, and failure conditions.

Read Methods and Model Boundaries ↗
View the visual methodology →

Browser compatibility layer

Run all 12 cases without installation

The hosted TypeScript workbench mirrors the reference engine for local, browser-only exploration. Uploads stay in the browser and are not sent to a server.

Open the Workbench →

Maintainers can verify the hosted layer with:

npm ci
npm run ci

Untrusted input

Bounded parsers and fail-closed packs

Graph and scenario inputs have size and structure limits. RiskPack verification rejects missing files, checksum mismatches, unsupported versions, and paths that escape the pack directory.

Read the security policy ↗