Skip to content

Exploration 06 — OpenQuake integration scoping spike

Status: drafted 2026-08-05, timeboxed desk-research spike (Phase 9, Stream C3 — issue #605). Commissioned by ratified decision 3 in phase-9-data-foundation.md (2026-07-30): ship earthquake v1 now as screening-grade EAI (ESHM20 RP rasters × ESRM20 curves through the existing engine) and produce this spike as the anti-indefinite-deferral anchor for the OpenQuake wave. Two commissioned deliverables, both below: (a) integration scoping as a Phase 10 entry condition for wave 2/#366; (b) a verdict on whether the shipped screening-grade posture is defensible or earthquake should go indicator-only until OpenQuake lands. This is desk research, not a decision to build — the recommendation below is a draft for owner ratification, same as the other exploration docs in this directory; no OpenQuake code is proposed or written here (out of scope per the issue).

No new facts contradict what 01-market-scan.md and 02-personas.md already established (AGPL, sidecar isolation mandatory, "quarter-plus" integration effort, ESRM20 as the Greek seismic risk model) — this doc grounds those claims against primary sources and adds the packaging/API/hardware detail neither prior doc covered, then converges on the entry-condition checklist and the v1-posture verdict.

Why this spike exists

Greece's dominant peril is earthquake (~€22bn residential loss at 1-in-200, 01-market-scan.md), and Law 5116/2024's mandated fire/flood/earthquake trio makes seismic capability a hard gate for the P1 insurer wedge (#366). climate-lama-engine has no seismic model; the roster answer is OpenQuake (GEM Foundation) as a second, independent compute engine — engine plurality is a product commitment (CLAUDE.md), not a stopgap. But OpenQuake is AGPL-3.0 (verified below), which changes the integration shape from "another ModelInterface implementation" to something that must never enter the backbone or worker Python process at all — a materially different, and materially bigger, lift than the climate-lama-engine port of CLIMADA's GPL-3.0 code (ADR-016/ADR-024). This spike scopes that lift honestly, timeboxed to what public documentation and the primary sources below actually say — no benchmark was run, no code was written.

(a) Integration scoping

Licensing — verified against the primary source, not summarized secondhand

The gem/oq-engine repository's LICENSE file, fetched directly, opens:

"GNU AFFERO GENERAL PUBLIC LICENSE, Version 3, 19 November 2007" — raw.githubusercontent.com/gem/oq-engine/master/LICENSE

Confirmed independently by the engine manual's introduction ("OpenQuake Engine is freely distributed under an Affero GPL license", docs.openquake.org introduction) and by GEM's own FAQ, which states the license in terms directly relevant to integration posture:

"The software license used by GEM, the GNU AGPL, allows users to use the software for any purpose, including commercial purposes... The AGPL does restrict (re)distribution and integration of the software — in particular it is not permitted to link AGPL software with closed-source software systems." — globalquakemodel.org/faq

That last sentence is the load-bearing one: it rules out import openquake.* anywhere in climate-lama or climate-lama-engine, regardless of how those repos' own (currently deferred, per CLAUDE.md) licensing question resolves — AGPL's linking restriction applies independent of what license we eventually pick. This is a stronger constraint than GPL-3.0/CLIMADA (ADR-016/ADR-024): CLIMADA was excluded by not importing it and reimplementing the needed surface in a clean-room engine; AGPL additionally reaches network use (its namesake clause requires source disclosure to users interacting with a modified AGPL program over a network), so even a same-host sidecar process needs the "unmodified, or source offered per instance" discipline that 01-market-scan.md's reassessment already flagged.

[ASSUMPTION] — 01-market-scan.md additionally claims "GEM sells commercial licenses as the AGPL fallback." I could not verify this independently: GEM's dedicated licensing page (storage.globalquakemodel.org/gem/terms/licensing/) returned HTTP 503 on fetch, and the FAQ page above — which does cover commercial engagement ("GEM can provide services for a fee... not our preferred approach") — does not mention an alternative license for the engine itself. Treat the commercial-license escape hatch as unconfirmed until someone reaches GEM directly or the licensing page becomes reachable; it is not load-bearing for the recommendation below (which assumes the free AGPL path).

This is not legal advice. The linking/network-boundary read above is the standard interpretation used by other AGPL-adjacent integrations (calling an unmodified AGPL service over its own network API, without linking it into a proprietary process, is broadly treated as outside the copyleft boundary) but it is exactly the kind of claim CLAUDE.md's "licensing is deferred pending validation" stance exists for — a real legal review before Phase 10 build work starts is a prerequisite, not a nice-to-have, and is folded into the entry condition below.

Packaging and Python API surface

Verified from the engine's own installation docs and package documentation:

  • Distribution: PyPI (pip install openquake.engine, with platform/Python-version-pinned requirements files for Linux/macOS/Windows), Docker images, Debian/RPM packages, and platform installers (Windows installer recommended for non-developers) — installation instructions, OpenQuake Engine LTS docs.
  • Supported Python: requirement files exist for 3.11/3.12/3.13 across linux64/macos/win64 — [same page].
  • Latest release: 3.26.2 (23 Jul, per the GitHub Releases page fetched directly — github.com/gem/oq-engine/releases); exact release year not shown on that page and not independently confirmed here — treat as "current at spike time," reconfirm at Phase 10 kickoff.
  • API surface has two very different shapes:
  • openquake.hazardlib is explicitly documented as usable standalone ("hazardlib is being actively developed by GEM foundation as a part of OpenQuake project, though it doesn't mean hazardlib depends on OpenQuake" — hazardlib API reference): source models, GMPEs/IPEs, magnitude-frequency models, and hazard calculators (curves, stochastic event sets, ground motion fields, disaggregation) with no database/webui/worker dependency. Same gem/oq-engine repo, same AGPL-3.0 license — "standalone" here means architecturally decoupled, not separately licensed.
  • openquake.risklib provides the risk/damage calculators we would actually need for ESRM20: scientific.classical() (vulnerability-curve convolution) and scientific.classical_damage() (fragility-curve damage states), plus riskmodels classes (ClassicalDamage, Scenario, ScenarioDamage) — risklib package docs.
  • The full engine (what you get running oq engine) adds a DbServer (mediates calculator↔database access, backed by a local SQLite file for accessory/log data — not a full RDBMS), a WebUI, and a ZeroMQ + workerpool distributed-compute layer, plus a REST API for submitting and monitoring jobs remotely — architecture docs, REST API docs. This is the piece that makes a network-boundary sidecar the natural deployment shape rather than an awkward one: OpenQuake already ships as a thing you run as a service and talk to over HTTP.

Model selection: ESHM20 hazard + ESRM20 risk, both already the phase's pick

No new alternative surfaced. GEM's own Global Seismic Hazard Mosaic — "a collection of [30] national and regional seismic hazard models" distributed in OpenQuake's own input format — uses ESHM20 to cover the whole Euro-Mediterranean region, Greece included (hazard.openquake.org/gem/models/EUR). That means the hazard side of an OpenQuake integration would consume the same ESHM20 source models phase-9-data-foundation.md already picked for the v1 raster ingest (E9), not a different dataset — continuity, not a fork.

  • ESHM20 inputs: OpenQuake-ready configuration + source-model files published via EFEHR, DOIs 10.12686/ESHM20-OQ-INPUT (inputs) and 10.12686/ESHM20-OUTPUT (computed hazard curves/maps) — NHESS 2024 overview paper.
  • ESRM20 inputs (exposure + vulnerability/fragility, the risk side): "the calculations are undertaken with the OpenQuake-engine and access to the input files is provided through a GitLab repository" — confirmed live at gitlab.seismo.ethz.ch/efehr/esrm20, esrm20_exposure, and esrm20_vulnerability. License: CC-BY 4.0 ("Data provided by the risk.EFEHR platform are licensed under the Creative Commons Attribution 4.0 International License") — risk.efehr.org/esrm20, EFEHR data access. This matches what phase-9-data-foundation.md already recorded for ESRM20 (CC-BY, EFEHR GitLab) — confirmed, not new.

Sidecar posture

Confirmed as the intended shape by two independent internal sources plus the primary-source licensing read above:

  • 02-personas.md: "OpenQuake (GEM) | Seismic hazard + risk | New — the earthquake answer | AGPL — sidecar isolation mandatory".
  • Issue #366's hard gate: "Seismic capability exists via the engine-plurality path: OpenQuake (GEM) adapter scoped and landed (sidecar isolation — AGPL never in-process)."

Concretely, per ADR-024's own pattern extended to a network boundary instead of a Python-import boundary:

  1. OpenQuake runs as its own deployable unit — its own container image, own process, own dependency graph (numpy/scipy plus GEM's own pinned stack) — never installed into the core or worker images.
  2. No file in climate-lama or climate-lama-engine imports openquake.*, ever — the equivalent of worker/models/engine_adapter.py being the sole CLIMADA-adjacent boundary, except here the boundary is a network client (HTTP calls to the OpenQuake REST/WebUI API), not a Python import. A new worker/models/openquake_client.py-shaped module (name TBD at Phase 10) would be the only file allowed to know the sidecar exists, mirroring the single-boundary discipline ADR-024 already established.
  3. Run unmodified GEM-published OpenQuake images/releases where at all possible — the moment the sidecar carries local patches, AGPL's network clause obligates offering that modified source to every user interacting with it, which is a process (not just a technical) commitment that needs explicit sign-off, not something to back into silently.
  4. This mirrors, not duplicates, climate-lama-engine's role: the engine stays the default and sole in-process compute path; OpenQuake becomes a second engine reached only over the network, consistent with "engine plurality" as a product commitment rather than an architecture exception.

Hardware / infrastructure needs

From the engine's own installation docs (LTS installation instructions):

  • Stated minimum: 16 GB RAM, 4 GB free disk.
  • Stated realistic scaling for non-trivial calculations: ~2 GB RAM per calculation thread for hazard, more for risk calculations — e.g. a 32-thread machine needs at least 64 GB RAM.
  • Cluster/SLURM configurations are documented as a supported deployment target for larger calculations, implying single-machine sizing is a starting point, not a ceiling, once the sidecar serves anything beyond Greece-scoped, screening-style requests.

This is a real infrastructure line item — a dedicated container with its own RAM budget, not a thin function call — and should be sized and costed as part of Phase 10 planning, not assumed away.

Effort estimate

[ASSUMPTION] — I could not find a published, citable runtime benchmark for a regional (Greece-scoped, not full pan-European) PSHA or risk calculation. A WebSearch summary surfaced an unsourced "4-day full-European PSHA" claim; I attempted to verify it against the OpenQuake manual's own PSHA methodology page and found no such statement there (PSHA-with-OQ-engine docs), so that figure is not included — inventing a number to fill this gap would be exactly the failure mode this spike is meant to avoid. Treat compute-time sizing as unresolved; a timed trial run against a Greece-only ESHM20/ESRM20 subset is the cheapest way to get a real number and belongs in Phase 10's first OpenQuake issue, not in this desk-research spike.

What can be estimated from verified facts is engineering lift, and it matches 01-market-scan.md's existing framing almost exactly — "OpenQuake is feasible but is a quarter-plus model-integration project, not 'an adapter': model selection/calibration/validation + semantic mapping." Concretely, the lift includes:

  • Standing up and operating a new deployable (sidecar container, its own image build/publish path, its own resource budget — item not currently in docker-compose.yml's two-deployable-unit shape).
  • A new adapter module confined to network calls (REST client against the OpenQuake WebUI/API, job submission + polling + result retrieval), plus whatever synchronous-vs-async translation is needed to fit the existing Celery job-queue pattern (CLAUDE.md rule 2: no synchronous long-running work in request handlers — an OpenQuake calculation is not fast).
  • Semantic mapping from ESHM20/ESRM20's native representations (Sa(T) spectral acceleration, taxonomy-keyed fragility) into this platform's hazard/exposure contracts — the same PGA-raster-vs-Sa(T) simplification called out in phase-9-data-foundation.md decision 3 as the reason today's v1 is screening-grade, not full-fidelity.
  • A real AGPL compliance review (legal, not engineering) before any sidecar ships, per the licensing section above.

No smaller-than-"quarter" estimate is defensible from what was verified here; nothing found in this spike shrinks that prior figure, and the AGPL linking-restriction finding — new to this spike — if anything reinforces it.

(b) Verdict: is screening-grade ESHM20-based EQ EAI defensible now?

Yes — the shipped v1 posture stays as-is; do not build the OpenQuake sidecar speculatively. Reasoning:

  1. The v1 path never touches OpenQuake code or its license at all. Today's screening-grade EAI consumes ESHM20's already-published RP hazard rasters (CC-BY, no AGPL surface) through climate-lama-engine's existing PGA-raster × ESRM20-curve convolution — a data-consumption relationship, not a software-integration one. The AGPL findings in this spike are about running OpenQuake ourselves, which v1 does not do and does not need to do. Decision 3's honest-labelling requirement (v1 EAI is screening-grade, and the EMS-98/macroseismic ESRM20 curve form is already the documented closer match to raster intensities) stands unchanged.
  2. The lift to go further is real and gated on unmet preconditions, not on missing technical feasibility: AGPL's linking restriction is confirmed real (not a maybe), the infra cost is a genuine new deployable with its own RAM budget, and — separately from this spike — issue #366 already requires interview validation that Greek insurers actually want per-property granularity beyond zonal (CRESTA-style) pricing before wave 2 starts at all. Building the OpenQuake sidecar now would be spending a quarter-plus of engineering effort against a demand signal that has not yet been confirmed.
  3. Earthquake does not need to go indicator-only in the meantime. The "indicator vs. computable" distinction in phase-9-data-foundation.md exists for perils with no damage curve (heatwave, drought) or a curve that cannot in principle consume the available hazard data (wildfire/FWI, #481). Earthquake has neither problem — ESRM20 curves exist and are already wired to ESHM20 rasters through the engine. Downgrading EQ to indicator-only would be a regression with no upstream cause; nothing found in this spike supports it.

The honest framing for the roadmap: v1 stays; OpenQuake is a Phase 10 wave-2 feature gated on both #366 hard gates, not a Phase 9 requirement. This spike is the anti-indefinite-deferral anchor decision 3 asked for — it exists so the "wave 2, eventually" answer has a concrete entry condition instead of staying an open-ended someday, not to force the sidecar into Phase 9.

Phase 10 entry condition (for wave 2 / #366)

Wave 2 (the 5116/2024 Greek nat-cat pricing pack, #366) may not start the OpenQuake sidecar build until all of the following are true:

  • [ ] This scoping doc is merged and read by whoever picks up the wave-2 epic (i.e. this document, satisfied by this PR).
  • [ ] #366's interview-validation hard gate clears: Greek insurer/broker interviews confirm demand for per-property granularity beyond zonal/CRESTA-style pricing (the compliance-sufficiency question flagged in 01-market-scan.md #8 and unresolved as of this spike).
  • [ ] A real AGPL compliance review (legal, not engineering) confirms the network-boundary/unmodified-instance posture in the sidecar-posture section above, given CLAUDE.md's deferred-licensing stance — this spike is desk research, not that review.
  • [ ] A timed trial run (Greece-scoped ESHM20/ESRM20 subset, one machine, whatever hardware is on hand) produces a real compute-time and RAM-budget number, replacing the "unresolved" effort estimate above — first OpenQuake issue in wave 2, before the full sidecar build.
  • [ ] The sidecar deployment is scoped as a genuine new infrastructure line item (container, image publish path, resource budget) in whatever compose/deploy story exists for Phase 10, not folded silently into the existing two-deployable-unit (core + worker) shape — ADR-024's single-boundary discipline applies to the network boundary too: one adapter module owns all contact with the sidecar.

Sources

Decided / Parked / Killed

Decided (this spike, pending owner ratification — not yet ratified) - v1 screening-grade EQ EAI (ESHM20 rasters × ESRM20 curves, already shipped) stays as-is; no rollback to indicator-only. - OpenQuake integration, when built, is a sidecar reached only over the network — never a Python import into climate-lama or climate-lama-engine — with the single-adapter-module discipline ADR-024 already established for CLIMADA, applied to the network boundary.

Parked - The actual OpenQuake sidecar build, the AGPL legal review, and the timed trial run — all deferred to Phase 10 wave 2, gated on the entry condition above. - GEM's alleged commercial-license alternative to AGPL — unconfirmed (503 on the licensing page), worth one direct outreach attempt at Phase 10 kickoff before assuming the free AGPL sidecar path is the only option.

Killed - Any notion of importing openquake.* into the backbone or worker process — ruled out by AGPL's explicit linking restriction against closed-source integration, independent of this project's own (deferred) licensing choice. - Inventing a compute-time/benchmark figure to complete the effort estimate — the unsourced "4-day full-European PSHA" claim surfaced in research was checked against the primary source and dropped rather than repeated.