Facilitate matrix simulations

The backend allows for n x m number of values and components to vary.
The frontend utilises this to make a 1D grid to vary single component
over a linear range.

Author: lars-petter-hauge

backend/alembic/versions/a7f3c9d21b84_add_sweeps.py

@@ -0,0 +1,35 @@
+"""add grid simulations
+
+Revision ID: a7f3c9d21b84
+Revises: b5d2e3f14a70
+Create Date: 2026-06-12 00:00:00.000000
+
+"""
+
+from typing import Sequence, Union
+
+import sqlalchemy as sa
+from alembic import op
+
+
+revision: str = "a7f3c9d21b84"
+down_revision: Union[str, Sequence[str], None] = "b5d2e3f14a70"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "grid_simulations",
+        sa.Column("owner_id", sa.Uuid(), nullable=True),
+        sa.Column("axes", sa.JSON(), nullable=False),
+        sa.Column("simulation_ids", sa.JSON(), nullable=False),
+        sa.Column("id", sa.Uuid(), nullable=False),
+        sa.Column("created_at", sa.DateTime(), nullable=False),
+        sa.Column("updated_at", sa.DateTime(), nullable=False),
+        sa.PrimaryKeyConstraint("id"),
+    )
+
+
+def downgrade() -> None:
+    op.drop_table("grid_simulations")

backend/src/acidwatch_api/database.py

@@ -49,6 +49,14 @@ class Simulation(Base):
     model_inputs: Mapped[list[ModelInput]] = relationship(back_populates="simulation")
 
 
+class GridSimulation(Base):
+    __tablename__ = "grid_simulations"
+
+    owner_id: Mapped[UUID | None] = mapped_column(Uuid)
+    axes: Mapped[list[dict]] = mapped_column(JSON)
+    simulation_ids: Mapped[list[str]] = mapped_column(JSON)
+
+
 class ModelInput(Base):
     __tablename__ = "model_inputs"
 

backend/src/acidwatch_api/models/datamodel.py

@@ -2,7 +2,7 @@
 
 from typing import Any, Literal, Optional, Dict, TypeAlias
 
-from pydantic import BaseModel, ConfigDict, Field
+from pydantic import BaseModel, ConfigDict, Field, model_validator
 from pydantic.alias_generators import to_camel
 
 
@@ -53,9 +53,68 @@ class ModelResult(_BaseModel):
 
 
 class SimulationResult(_BaseModel):
-    status: Literal["done", "pending"]
+    status: Literal["done", "pending", "error"]
     input: Simulation
     results: list[ModelResult]
+    error: str | None = None
+
+
+class AxisRange(_BaseModel):
+    """A linear, inclusive range that is sampled at ``steps`` points."""
+
+    min: float
+    max: float
+    steps: int = Field(default=10, ge=2, le=25)
+
+    @model_validator(mode="after")
+    def _check_bounds(self) -> "AxisRange":
+        if self.max <= self.min:
+            raise ValueError("max must be greater than min")
+        return self
+
+    def values(self) -> list[float]:
+        step = (self.max - self.min) / (self.steps - 1)
+        return [self.min + step * i for i in range(self.steps)]
+
+
+class Axis(_BaseModel):
+    substance: str
+    range: AxisRange
+
+
+class CreateGridSimulation(_BaseModel):
+    """Request body for starting a grid simulation.
+
+    Runs a model chain once for each point in the cartesian product of the
+    axes, substituting each axis's substance in ``concentrations`` with the
+    corresponding value.
+    """
+
+    axes: list[Axis] = Field(min_length=1, max_length=2)
+    concentrations: dict[str, int | float]
+    conditions: Conditions = Field(default_factory=Conditions)
+    models: list[ModelInput] = Field(min_length=1)
+
+    @model_validator(mode="after")
+    def _check_axes(self) -> "CreateGridSimulation":
+        substances = [axis.substance for axis in self.axes]
+        if len(substances) != len(set(substances)):
+            raise ValueError("Each axis must use a unique substance")
+
+        total = 1
+        for axis in self.axes:
+            total *= axis.range.steps
+        if total > 100:
+            raise ValueError(
+                f"Grid too large: {total} points exceeds the maximum of 100"
+            )
+        return self
+
+
+class GridSimulationResult(_BaseModel):
+    status: Literal["done", "pending"]
+    axes: list[Axis]
+    simulations: list[SimulationResult]
 
 
 class JsonResult(BaseModel):

backend/src/acidwatch_api/routes/__init__.py

@@ -4,10 +4,12 @@
 
 from . import models
 from . import oasis
+from . import grid_simulations
 
 router = APIRouter()
 router.include_router(models.router)
 router.include_router(oasis.router)
+router.include_router(grid_simulations.router)
 
 
 __all__ = ["router"]

backend/src/acidwatch_api/routes/grid_simulations.py

@@ -0,0 +1,153 @@
+from __future__ import annotations
+
+import itertools
+import logging
+from typing import Annotated, Literal
+from uuid import UUID
+
+from fastapi import APIRouter, BackgroundTasks, Depends, HTTPException, Request
+
+import acidwatch_api.database as db
+from acidwatch_api.authentication import OptionalCurrentUser
+from acidwatch_api.database import GetDB
+from acidwatch_api.models import InputError
+from acidwatch_api.models.datamodel import (
+    Axis,
+    CreateGridSimulation,
+    GridSimulationResult,
+    SimulationResult,
+)
+from acidwatch_api.models.base import BaseAdapter
+from acidwatch_api.routes.models import (
+    AdapterSet,
+    build_adapters,
+    build_model_input_rows,
+    build_simulation_result,
+    get_adapters,
+    run_adapters,
+)
+
+router = APIRouter()
+
+logger = logging.getLogger(__name__)
+
+
+def _cartesian_values(axes: list[Axis]) -> list[list[float]]:
+    ranges = [axis.range.values() for axis in axes]
+    return [list(point) for point in itertools.product(*ranges)]
+
+
+@router.post("/grid-simulations")
+async def run_grid_simulation(
+    create: CreateGridSimulation,
+    user: OptionalCurrentUser,
+    request: Request,
+    session: GetDB,
+    background_tasks: BackgroundTasks,
+    all_adapters: Annotated[AdapterSet, Depends(get_adapters)],
+) -> UUID:
+    jwt_token = user.jwt_token if user else None
+
+    adapters = build_adapters(create.models, create.conditions, all_adapters, jwt_token)
+
+    for axis in create.axes:
+        if axis.substance not in adapters[0].valid_substances:
+            raise HTTPException(
+                status_code=422,
+                detail={
+                    "axes": [
+                        f"'{axis.substance}' is not supported by the selected model"
+                    ]
+                },
+            )
+
+    test_concentrations = {
+        **create.concentrations,
+        **{axis.substance: 0 for axis in create.axes},
+    }
+    try:
+        adapters[0].validate_concentrations(test_concentrations)
+    except InputError as exc:
+        raise HTTPException(status_code=422, detail=exc.detail)
+
+    grid_points = _cartesian_values(create.axes)
+
+    scheduled: list[tuple[dict[str, int | float], list[BaseAdapter], list[UUID]]] = []
+    simulation_ids: list[str] = []
+
+    for coordinates in grid_points:
+        point_concentrations = {
+            **create.concentrations,
+            **{axis.substance: value for axis, value in zip(create.axes, coordinates)},
+        }
+        model_input_rows = build_model_input_rows(create.models)
+        simulation = db.Simulation(
+            owner_id=UUID(user.id) if user else None,
+            phases=[
+                {
+                    "kind": "co2-rich",
+                    "fraction": 1.0,
+                    "concentrations": point_concentrations,
+                }
+            ],
+            conditions=create.conditions.model_dump(),
+            model_inputs=model_input_rows,
+        )
+        session.add(simulation)
+        session.flush()
+        simulation_ids.append(str(simulation.id))
+
+        point_adapters = build_adapters(
+            create.models, create.conditions, all_adapters, jwt_token
+        )
+        scheduled.append(
+            (
+                point_concentrations,
+                point_adapters,
+                [row.id for row in model_input_rows],
+            )
+        )
+
+    grid = db.GridSimulation(
+        owner_id=UUID(user.id) if user else None,
+        axes=[axis.model_dump() for axis in create.axes],
+        simulation_ids=simulation_ids,
+    )
+    session.add(grid)
+    session.commit()
+
+    for point_concentrations, point_adapters, model_input_ids in scheduled:
+        background_tasks.add_task(
+            run_adapters,
+            request.state.session,
+            point_concentrations,
+            point_adapters,
+            model_input_ids,
+        )
+
+    return grid.id
+
+
+@router.get("/grid-simulations/{grid_id}/result")
+def get_grid_simulation_result(
+    grid_id: UUID,
+    session: GetDB,
+) -> GridSimulationResult:
+    grid = session.get_one(db.GridSimulation, grid_id)
+
+    axes = [Axis(**a) for a in grid.axes]
+    sim_uuids = [UUID(sid) for sid in grid.simulation_ids]
+
+    simulations: list[SimulationResult] = [
+        build_simulation_result(session, sim_id) for sim_id in sim_uuids
+    ]
+
+    overall_status: Literal["done", "pending"] = "done"
+    if any(s.status == "pending" for s in simulations):
+        overall_status = "pending"
+
+    return GridSimulationResult(
+        status=overall_status,
+        axes=axes,
+        simulations=simulations,
+    )

backend/src/acidwatch_api/routes/models.py

@@ -160,7 +160,7 @@ def query_chain_rows(
         .where(db.ModelInput.simulation_id == simulation_id)
         .outerjoin(db.ModelResult)
     )
-    return list(session.execute(q).fetchall())
+    return [(row[0], row[1]) for row in session.execute(q).fetchall()]
 
 
 @router.get("/models")
@@ -253,11 +253,7 @@ async def _run_adapter(
             session.add(result_obj)
 
 
-@router.get("/simulations/{simulation_id}/result")
-def get_result_for_simulation(
-    simulation_id: UUID,
-    session: GetDB,
-) -> SimulationResult:
+def build_simulation_result(session: Session, simulation_id: UUID) -> SimulationResult:
     db_simulation = session.get_one(db.Simulation, simulation_id)
 
     model_inputs: list[ModelInput] = []
@@ -278,9 +274,17 @@ def get_result_for_simulation(
 
         if result.error is not None:
             logger.error("Simulation %s failed: %s", simulation_id, result.error)
-            raise HTTPException(
-                status_code=500,
-                detail=f"Simulation failed: {result.error}",
+            return SimulationResult(
+                status="error",
+                input=Simulation(
+                    concentrations=_phases_to_concentrations(
+                        [Phase(**p) for p in db_simulation.phases]
+                    ),
+                    conditions=Conditions(**(db_simulation.conditions or {})),
+                    models=model_inputs,
+                ),
+                results=results,
+                error=result.error,
             )
 
         results.append(
@@ -320,6 +324,14 @@ def get_result_for_simulation(
     )
 
 
+@router.get("/simulations/{simulation_id}/result")
+def get_result_for_simulation(
+    simulation_id: UUID,
+    session: GetDB,
+) -> SimulationResult:
+    return build_simulation_result(session, simulation_id)
+
+
 @router.post("/simulations")
 async def run_simulation(
     create_simulation: Simulation,