Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions changelog.d/c1-39-include-cliffs.added.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
`POST /reports` and `POST /reports/{report_id}/runs` accept `include_cliffs: true` again: once the request has ended on its report run, created or joined, the Simulation Entrypoint finds or creates the cliff calculation (a row of API v1's `cliff_impacts`) of each simulation run that report run names, and starts the run's simulation function in its cliff mode only for a calculation it created, so identical requests share one calculation per run. The answer names each side's cliff calculation and its status in `cliffs`. `include_cliffs` is never stored, keyed or passed to the coordinator, and a report stored before keys asking for cliffs is re-run with its runs' cliffs instead of a 422. A budget window's or household report's re-run asking for cliffs is refused with 422 `cliffs_not_available`.
18 changes: 10 additions & 8 deletions docs/migration/stage-12-modal-worker-foundation.md
Original file line number Diff line number Diff line change
Expand Up @@ -370,12 +370,13 @@ holds, or one that failed, it returns `{"deduplicated": true,
**A simulation run's cliff result** (C1 · 24, answer 4b). Each simulation run
can have one cliff result, its cliff gap and cliff share, which every report
naming the run reads: a row of API v1's `cliff_impacts`, one per
calculation. Nothing starts one yet. The simulation service is to insert it
pending, start the country's simulation worker (`run_single_simulation_us` or
`run_single_simulation_uk`) with the run's own simulation input, built as a
standalone run's, and a context naming the row
calculation. The simulation service inserts it pending when a report's
create or re-run asks for cliffs (`include_cliffs`, C1 · 39) and the run has
none that hasn't failed, starts the country's simulation worker
(`run_single_simulation_us` or `run_single_simulation_uk`) with the run's own
simulation input, built as a standalone run's, and a context naming the row
(`Stage12InvocationContext.cliff_result_id`, left out of a context that names
none, which older workers refuse), and record the call (C1 · 39). The worker
none, which older workers refuse), and records the call. The worker
claims the row as a run is claimed, and refuses, failing it with
`cliff_result_input_mismatch`, an input that is not the simulation of the
row's run on that run's year and versions; the calculation then checks those
Expand Down Expand Up @@ -412,9 +413,10 @@ policy turns a response on; in the US, the two inputs .py's labour-supply
output reads from either side (`self_employment_income`,
`weekly_hours_worked`); and never the cliff columns, so a US national run keeps
its region-group split. Cliffs are a calculation of each simulation run of
their own (above). A report run asking for them (`include_cliffs: true`) still
fails before any worker starts, with `cliff_impacts_unavailable`, and touches
none of its simulation runs, and its completion never writes `report_runs`'
their own (above), so the simulation service never asks a coordinator for
them: a report run asking for them (`include_cliffs: true`) would fail before
any worker starts, with `cliff_impacts_unavailable`, and touch none of its
simulation runs, and a report run's completion never writes `report_runs`'
four cliff columns. The
coordinator gives each worker its simulation's
stored plan, and keeps the report's own plan, from its pair, for what the
Expand Down
13 changes: 12 additions & 1 deletion libs/policyengine-simulation-persistence/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -215,7 +215,18 @@ report and run rows (C1 · 24). These modules do it:
weren't forced, outside budget windows), then a read of the row that
won, retried when that run fails in between (`SharedRowNotSettledError`
after three tries). A forced run is inserted directly and never looked
up or joined.
up or joined. `find_or_insert_cliff_calculations` does the same for each
simulation run's cliff calculation, against `uq_cliff_impacts_unfailed`,
in simulation run ID order: a run's calculation that hasn't failed is
found, and otherwise one is inserted pending with no Modal call. A
keyed report's create (`KeyedEconomyReport.cliffs`, the IDs it proposes)
or an economy report's re-run (`insert_report_rerun_with_cliffs`) whose
request asks for cliffs runs it on the two simulation runs of the report
run it ended on, in the same transaction
(`find_or_insert_report_run_cliffs`), so a refused calculation writes
nothing, and returns each side's calculation (`FoundCliffs`). `EconomyRunStore.record_cliff_call` and
`fail_unstarted_cliff_calculation` record a calculation's call, or fail
it when Modal refused it, each only while it is pending with no call.
- `keyed_economy_records.py` runs a report's find-or-create in one
transaction: each side's simulation by key, in key order; the report by
key; the report's joinable run on the current versions, joined with the
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,7 @@
definition_key,
)
from policyengine_simulation_persistence.economy_rerun_records import (
FoundReportRerun,
HouseholdRerunSide,
NewHouseholdReportRerun,
NewReportRerun,
Expand All @@ -37,6 +38,7 @@
WindowYearDefinition,
insert_household_report_rerun,
insert_report_rerun,
insert_report_rerun_with_cliffs,
insert_simulation_rerun,
insert_window_rerun,
lock_reruns_of,
Expand Down Expand Up @@ -139,6 +141,7 @@
ProposedSide,
find_or_create_economy_report,
find_or_create_economy_simulation,
find_or_insert_report_run_cliffs,
)
from policyengine_simulation_persistence.keyed_household_records import (
FoundHouseholdReport,
Expand Down Expand Up @@ -187,12 +190,16 @@
result_metadata,
)
from policyengine_simulation_persistence.shared_rows import (
FoundCliffCalculation,
FoundCliffs,
FoundReportRun,
FoundRow,
FoundSimulationRun,
FoundWindowRun,
ProposedCliffs,
SharedRowNotSettledError,
find_joinable_report_run,
find_or_insert_cliff_calculations,
find_or_insert_report,
find_or_insert_report_run,
find_or_insert_simulation,
Expand Down Expand Up @@ -251,9 +258,12 @@
"EconomySimulationInputs",
"EconomySimulationState",
"FoundBudgetWindow",
"FoundCliffCalculation",
"FoundCliffs",
"FoundEconomyReport",
"FoundEconomySimulation",
"FoundHouseholdReport",
"FoundReportRerun",
"FoundReportRun",
"FoundRow",
"FoundSide",
Expand Down Expand Up @@ -297,6 +307,7 @@
"PolicyReform",
"Poverty",
"ProgramStatistics",
"ProposedCliffs",
"ProposedSide",
"RecordKind",
"ReferencedBase",
Expand Down Expand Up @@ -357,15 +368,18 @@
"find_or_create_economy_report",
"find_or_create_economy_simulation",
"find_or_create_household_report",
"find_or_insert_cliff_calculations",
"find_or_insert_report",
"find_or_insert_report_run",
"find_or_insert_report_run_cliffs",
"find_or_insert_simulation",
"find_or_insert_simulation_run",
"find_or_insert_simulation_runs",
"input_metadata",
"insert_household_job",
"insert_household_report_rerun",
"insert_report_rerun",
"insert_report_rerun_with_cliffs",
"insert_simulation_rerun",
"insert_window_rerun",
"lock_reruns_of",
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,10 @@
indexes leave out, so it is created beside any run on the same versions,
even one under way, and nothing ever joins it.

An economy report's re-run asking for cliffs also finds or inserts the cliff
calculation of each simulation run the report run it ended on names, in the
same transaction (``find_or_insert_report_run_cliffs``, answer 4b).

The service then starts and records the new run's call as it does a new
record's (``economy_run_records``).
"""
Expand All @@ -64,6 +68,7 @@
insert_household_simulation_run,
)
from policyengine_simulation_persistence.keyed_economy_records import (
find_or_insert_report_run_cliffs,
find_or_insert_report_run_on_sides,
)
from policyengine_simulation_persistence.keyed_window_records import (
Expand Down Expand Up @@ -108,7 +113,11 @@
RunVersions,
)
from policyengine_simulation_persistence.keyed_economy_records import Side
from policyengine_simulation_persistence.shared_rows import FoundSimulationRun
from policyengine_simulation_persistence.shared_rows import (
FoundCliffs,
FoundSimulationRun,
ProposedCliffs,
)


@dataclass(frozen=True)
Expand Down Expand Up @@ -153,6 +162,14 @@ def new_simulation_run_ids(self) -> tuple[UUID, ...]:
return (self.baseline.simulation_run_id, self.reform.simulation_run_id)


@dataclass(frozen=True)
class FoundReportRerun:
"""The report run a re-run asking for cliffs ended on, and its runs' cliffs."""

run: FoundReportRun
cliffs: FoundCliffs


@dataclass(frozen=True)
class WindowRerunYear:
"""One year of a budget window's re-run: its report run and each side's run."""
Expand Down Expand Up @@ -345,6 +362,21 @@ def insert_report_rerun(session: Session, rerun: NewReportRerun) -> FoundReportR
return found


def insert_report_rerun_with_cliffs(
session: Session, rerun: NewReportRerun, proposed: ProposedCliffs
) -> FoundReportRerun:
"""Join or create the report's run, with its runs' cliff calculations.

As ``insert_report_rerun``, then, in the same transaction, finds or
inserts the cliff calculation of each simulation run that report run
names, joined or created (``find_or_insert_report_run_cliffs``).
"""
run = insert_report_rerun(session, rerun)
return FoundReportRerun(
run=run, cliffs=find_or_insert_report_run_cliffs(session, run, proposed)
)


def _rerun_report_run_row(
*, run_id: UUID, report_id: UUID, versions: RunVersions
) -> dict[str, Any]:
Expand Down Expand Up @@ -598,6 +630,7 @@ def _record_checked(*own_keys: InstrumentedAttribute[Any]) -> Iterator[None]:

# The definition reads moved to rerun_definitions; their names stay importable here.
__all__ = [
"FoundReportRerun",
"HouseholdRerunSide",
"NewHouseholdReportRerun",
"NewReportRerun",
Expand All @@ -613,6 +646,7 @@ def _record_checked(*own_keys: InstrumentedAttribute[Any]) -> Iterator[None]:
"WindowYearDefinition",
"insert_household_report_rerun",
"insert_report_rerun",
"insert_report_rerun_with_cliffs",
"insert_simulation_rerun",
"insert_window_rerun",
"lock_reruns_of",
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,7 @@
)
from policyengine_simulation_persistence.tables import (
BudgetWindowRun,
CliffImpact,
Report,
ReportRun,
ReportRunStatus,
Expand All @@ -68,21 +69,28 @@
from sqlalchemy import ColumnElement
from sqlalchemy.orm import Session

# The two classes whose runs a Modal call calculates.
type RunModel = type[SimulationRun | ReportRun]
# The classes whose rows a Modal call calculates: runs and cliff calculations.
type RunModel = type[SimulationRun | ReportRun | CliffImpact]

# PostgreSQL's SQLSTATE for a row naming one that does not exist.
FOREIGN_KEY_VIOLATION: Final = "23503"
# A report's type, as API v1 reads it.
ECONOMY_REPORT_TYPE: Final = "economy"
# Both run tables' statuses use these values.
# These classes' statuses use these values.
_PENDING: Final = SimulationStatus.PENDING.value
_FAILED: Final = SimulationStatus.FAILED.value
# Each foreign key of the tables the service writes, by name: its table and
# the first column it constrains.
_KEY_COLUMNS: Final = {
str(constraint.name): (model.__tablename__, constraint.column_keys[0])
for model in (Simulation, SimulationRun, Report, ReportRun, BudgetWindowRun)
for model in (
Simulation,
SimulationRun,
Report,
ReportRun,
BudgetWindowRun,
CliffImpact,
)
for constraint in model.__table_args__
if isinstance(constraint, ForeignKeyConstraint)
}
Expand Down Expand Up @@ -351,6 +359,18 @@ def record_simulation_run_call(
return None if status is None else SimulationStatus(status)


def record_cliff_calculation_call(
session: Session, *, cliff_result_id: UUID, modal_call_id: str
) -> SimulationStatus | None:
"""Record a cliff calculation's Modal call ID while it is pending with none.

Return its status afterwards, or None when there is no such row. One
the worker has claimed already keeps its claim.
"""
status = _record_call(session, CliffImpact, cliff_result_id, modal_call_id)
return None if status is None else SimulationStatus(status)


def _record_call(
session: Session, model: RunModel, run_id: UUID, modal_call_id: str
) -> str | None:
Expand Down Expand Up @@ -402,6 +422,17 @@ def fail_unstarted_simulation_run(
return _fail_unstarted(session, SimulationRun, simulation_run_id, error_message)


def fail_unstarted_cliff_calculation(
session: Session, *, cliff_result_id: UUID, error_message: str
) -> bool:
"""Fail a cliff calculation at once while it is pending with no Modal call ID.

Return whether it was failed: one a call has been recorded for, or one
the worker has claimed, is left as it is.
"""
return _fail_unstarted(session, CliffImpact, cliff_result_id, error_message)


def _fail_unstarted(
session: Session, model: RunModel, run_id: UUID, error_message: str
) -> bool:
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,7 @@
)
from policyengine_simulation_persistence.economy_rerun_records import (
insert_report_rerun,
insert_report_rerun_with_cliffs,
insert_simulation_rerun,
insert_window_rerun,
read_report_definition,
Expand All @@ -46,8 +47,10 @@
)
from policyengine_simulation_persistence.economy_run_records import (
SimulationChoice,
fail_unstarted_cliff_calculation,
fail_unstarted_report_run,
fail_unstarted_simulation_run,
record_cliff_calculation_call,
record_report_run_call,
record_simulation_run_call,
)
Expand All @@ -72,6 +75,7 @@
from sqlalchemy.orm import Session, sessionmaker

from policyengine_simulation_persistence.economy_rerun_records import (
FoundReportRerun,
NewReportRerun,
NewSimulationRerun,
NewWindowRerun,
Expand All @@ -96,6 +100,7 @@
from policyengine_simulation_persistence.shared_rows import (
FoundReportRun,
FoundSimulationRun,
ProposedCliffs,
)
from policyengine_simulation_persistence.tables import (
ReportRunStatus,
Expand Down Expand Up @@ -239,6 +244,18 @@ def create_report_rerun(self, rerun: NewReportRerun) -> FoundReportRun:
"""
return self._create(lambda session: insert_report_rerun(session, rerun))

def create_report_rerun_with_cliffs(
self, rerun: NewReportRerun, cliffs: ProposedCliffs
) -> FoundReportRerun:
"""Join or create the report's run, with its runs' cliff calculations.

See ``insert_report_rerun_with_cliffs``; raise as
``create_report_rerun`` does.
"""
return self._create(
lambda session: insert_report_rerun_with_cliffs(session, rerun, cliffs)
)

def create_simulation_rerun(self, rerun: NewSimulationRerun) -> FoundSimulationRun:
"""Join or create the simulation's run; see ``insert_simulation_rerun``.

Expand Down Expand Up @@ -352,6 +369,28 @@ def fail_unstarted_simulation(
error_message=error_message,
)

def record_cliff_call(
self, cliff_result_id: UUID, modal_call_id: str
) -> SimulationStatus | None:
"""Record a cliff calculation's call ID while it is pending with none."""
with self._transaction() as session:
return record_cliff_calculation_call(
session,
cliff_result_id=cliff_result_id,
modal_call_id=modal_call_id,
)

def fail_unstarted_cliff_calculation(
self, cliff_result_id: UUID, error_message: str
) -> bool:
"""Fail a cliff calculation while it is pending with no call ID."""
with self._transaction() as session:
return fail_unstarted_cliff_calculation(
session,
cliff_result_id=cliff_result_id,
error_message=error_message,
)

def read_report(self, report_id: UUID) -> EconomyReportState | None:
"""Return the report with its newest run, or None when there is none."""
with self._transaction() as session:
Expand Down
Loading