feat: add concentration range sweep across models

Add a range-sweep feature to the model page: select one concentration,
define a linear range (2-25 values, default 10), and run the selected
model chain across that range.

Backend:
- New Sweep table owning child Simulations (one per range value), reusing
  the existing simulation infrastructure so each point is itself a
  shareable simulation.
- POST /sweeps validates the chain + swept substance up front and
  schedules a background run per point; GET /sweeps/{id}/result aggregates
  child simulations into per-point status/concentrations for single-URL
  polling.
- Alembic migration for the sweeps table and simulation FK columns.

Frontend:
- Sweep range controls on the model page and a 'Run Sweep' action.
- Shareable /sweeps/:sweepId route that reloads inputs and results.
- SweepResults view (line chart + table + CSV export) and sweep overlay
  in Compare via ?sweeps=, selectable from the history sidebar.
- History entries gain a 'kind' to distinguish simulations from sweeps.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: lars-petter-hauge

backend/alembic/versions/a7f3c9d21b84_add_sweeps.py

@@ -0,0 +1,55 @@
+"""add sweeps
+
+Revision ID: a7f3c9d21b84
+Revises: 7c2e1f4b8a90
+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] = "7c2e1f4b8a90"
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "sweeps",
+        sa.Column("owner_id", sa.Uuid(), nullable=True),
+        sa.Column("swept_substance", sa.String(), nullable=False),
+        sa.Column("values", 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"),
+    )
+    op.add_column(
+        "simulations",
+        sa.Column("sweep_id", sa.Uuid(), nullable=True),
+    )
+    op.add_column(
+        "simulations",
+        sa.Column("sweep_value_index", sa.Integer(), nullable=True),
+    )
+    op.create_foreign_key(
+        op.f("simulations_sweep_id_fkey"),
+        "simulations",
+        "sweeps",
+        ["sweep_id"],
+        ["id"],
+    )
+
+
+def downgrade() -> None:
+    op.drop_constraint(
+        op.f("simulations_sweep_id_fkey"), "simulations", type_="foreignkey"
+    )
+    op.drop_column("simulations", "sweep_value_index")
+    op.drop_column("simulations", "sweep_id")
+    op.drop_table("sweeps")

backend/src/acidwatch_api/database.py

@@ -46,7 +46,21 @@ class Simulation(Base):
     concentrations: Mapped[dict[str, float]] = mapped_column(JSON)
     conditions: Mapped[dict[str, float] | None] = mapped_column(JSON)
 
+    sweep_id: Mapped[UUID | None] = mapped_column(ForeignKey("sweeps.id"))
+    sweep_value_index: Mapped[int | None] = mapped_column()
+
     model_inputs: Mapped[list[ModelInput]] = relationship(back_populates="simulation")
+    sweep: Mapped[Sweep | None] = relationship(back_populates="simulations")
+
+
+class Sweep(Base):
+    __tablename__ = "sweeps"
+
+    owner_id: Mapped[UUID | None] = mapped_column(Uuid)
+    swept_substance: Mapped[str] = mapped_column()
+    values: Mapped[list[float]] = mapped_column(JSON)
+
+    simulations: Mapped[list[Simulation]] = relationship(back_populates="sweep")
 
 
 class ModelInput(Base):

backend/src/acidwatch_api/models/datamodel.py

@@ -1,8 +1,9 @@
 from __future__ import annotations
 
 from typing import Any, Literal, Optional, Dict, TypeAlias
+from uuid import UUID
 
-from pydantic import BaseModel, ConfigDict, Field
+from pydantic import BaseModel, ConfigDict, Field, model_validator
 from pydantic.alias_generators import to_camel
 
 
@@ -46,6 +47,57 @@ class SimulationResult(_BaseModel):
     results: list[ModelResult]
 
 
+class SweepRange(_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) -> "SweepRange":
+        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 CreateSweep(_BaseModel):
+    """Request body for starting a concentration sweep.
+
+    A sweep runs a single model configuration (the ``models`` chain) once for
+    each value in ``range``, substituting ``swept_substance`` in
+    ``concentrations`` with that value.
+    """
+
+    swept_substance: str
+    range: SweepRange
+    concentrations: dict[str, int | float]
+    conditions: Conditions = Field(default_factory=Conditions)
+    models: list[ModelInput] = Field(min_length=1)
+
+
+class SweepPoint(_BaseModel):
+    value: float
+    simulation_id: UUID
+    status: Literal["done", "pending", "error"]
+    error: str | None = None
+    concentrations: dict[str, int | float]
+
+
+class SweepResult(_BaseModel):
+    status: Literal["done", "pending"]
+    swept_substance: str
+    values: list[float]
+    concentrations: dict[str, int | float]
+    conditions: Conditions
+    models: list[ModelInput]
+    points: list[SweepPoint]
+
+
 class JsonResult(BaseModel):
     type: Literal["json"] = "json"
     label: str | None = None

backend/src/acidwatch_api/routes/__init__.py

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

backend/src/acidwatch_api/routes/sweeps.py

@@ -0,0 +1,219 @@
+from __future__ import annotations
+
+import logging
+from collections import defaultdict
+from typing import Annotated
+from uuid import UUID
+
+from fastapi import APIRouter, BackgroundTasks, Depends, HTTPException, Request
+from sqlalchemy import select
+
+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 (
+    Conditions,
+    CreateSweep,
+    ModelInput,
+    SweepPoint,
+    SweepResult,
+)
+from acidwatch_api.routes.models import (
+    AdapterSet,
+    build_adapters,
+    build_model_input_rows,
+    get_adapters,
+    order_chain,
+    run_adapters,
+)
+
+router = APIRouter()
+
+logger = logging.getLogger(__name__)
+
+
+def _summarize_point(
+    ordered: list[tuple[db.ModelInput, db.ModelResult | None]],
+) -> tuple[str, dict[str, int | float], str | None]:
+    """Reduce a simulation's chain to a sweep point status and final output.
+
+    The "output" of a chain is the concentrations of its last model.
+    """
+    if not ordered:
+        return "pending", {}, None
+
+    for _, result in ordered:
+        if result is not None and result.error is not None:
+            return "error", {}, result.error
+
+    if any(result is None for _, result in ordered):
+        return "pending", {}, None
+
+    final_result = ordered[-1][1]
+    assert final_result is not None
+    return "done", final_result.concentrations, None
+
+
+@router.post("/sweeps")
+async def run_sweep(
+    create_sweep: CreateSweep,
+    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
+
+    # Validate the model chain and concentrations once up front so the caller
+    # gets a synchronous 422 instead of a sweep full of failed points.
+    adapters = build_adapters(
+        create_sweep.models, create_sweep.conditions, all_adapters, jwt_token
+    )
+
+    if create_sweep.swept_substance not in adapters[0].valid_substances:
+        raise HTTPException(
+            status_code=422,
+            detail={
+                "sweptSubstance": [
+                    f"'{create_sweep.swept_substance}' is not supported by "
+                    f"the selected model"
+                ]
+            },
+        )
+
+    try:
+        adapters[0].validate_concentrations(
+            {**create_sweep.concentrations, create_sweep.swept_substance: 0}
+        )
+    except InputError as exc:
+        raise HTTPException(status_code=422, detail=exc.detail)
+
+    values = create_sweep.range.values()
+
+    sweep = db.Sweep(
+        owner_id=UUID(user.id) if user else None,
+        swept_substance=create_sweep.swept_substance,
+        values=values,
+    )
+    session.add(sweep)
+
+    scheduled: list[tuple[dict[str, int | float], list, list[UUID]]] = []
+    for index, value in enumerate(values):
+        point_concentrations = {
+            **create_sweep.concentrations,
+            create_sweep.swept_substance: value,
+        }
+        model_input_rows = build_model_input_rows(create_sweep.models)
+        session.add(
+            db.Simulation(
+                owner_id=UUID(user.id) if user else None,
+                concentrations=point_concentrations,
+                conditions=create_sweep.conditions.model_dump(),
+                sweep=sweep,
+                sweep_value_index=index,
+                model_inputs=model_input_rows,
+            )
+        )
+        point_adapters = build_adapters(
+            create_sweep.models, create_sweep.conditions, all_adapters, jwt_token
+        )
+        scheduled.append(
+            (
+                point_concentrations,
+                point_adapters,
+                [row.id for row in model_input_rows],
+            )
+        )
+
+    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 sweep.id
+
+
+@router.get("/sweeps/{sweep_id}/result")
+def get_sweep_result(
+    sweep_id: UUID,
+    session: GetDB,
+) -> SweepResult:
+    sweep = session.get_one(db.Sweep, sweep_id)
+
+    simulations = (
+        session.execute(
+            select(db.Simulation).where(db.Simulation.sweep_id == sweep_id)
+        )
+        .scalars()
+        .all()
+    )
+    simulation_by_index = {sim.sweep_value_index: sim for sim in simulations}
+
+    rows_by_simulation: dict[
+        UUID, list[tuple[db.ModelInput, db.ModelResult | None]]
+    ] = defaultdict(list)
+    simulation_ids = [sim.id for sim in simulations]
+    if simulation_ids:
+        q = (
+            select(db.ModelInput, db.ModelResult)
+            .where(db.ModelInput.simulation_id.in_(simulation_ids))
+            .outerjoin(db.ModelResult)
+        )
+        for model_input, result in session.execute(q):
+            rows_by_simulation[model_input.simulation_id].append(
+                (model_input, result)
+            )
+
+    points: list[SweepPoint] = []
+    overall_pending = False
+    for index, value in enumerate(sweep.values):
+        simulation = simulation_by_index.get(index)
+        if simulation is None:
+            overall_pending = True
+            continue
+
+        ordered = order_chain(rows_by_simulation.get(simulation.id, []))
+        status, concentrations, error = _summarize_point(ordered)
+        if status == "pending":
+            overall_pending = True
+
+        points.append(
+            SweepPoint(
+                value=value,
+                simulation_id=simulation.id,
+                status=status,  # type: ignore[arg-type]
+                error=error,
+                concentrations=concentrations,
+            )
+        )
+
+    first_simulation = simulation_by_index.get(0)
+    if first_simulation is not None:
+        models = [
+            ModelInput(model_id=mi.model_id, parameters=mi.parameters)
+            for mi, _ in order_chain(rows_by_simulation.get(first_simulation.id, []))
+        ]
+        base_concentrations = dict(first_simulation.concentrations or {})
+        conditions = Conditions(**(first_simulation.conditions or {}))
+    else:
+        models = []
+        base_concentrations = {}
+        conditions = Conditions()
+
+    return SweepResult(
+        status="pending" if overall_pending else "done",
+        swept_substance=sweep.swept_substance,
+        values=list(sweep.values),
+        concentrations=base_concentrations,
+        conditions=conditions,
+        models=models,
+        points=points,
+    )