This is a record of all past PyLCM releases and what went into them in reverse chronological order. We follow semantic versioning.
- The envelope configurations,
DCEGM'srefined_grid_factorandn_constrained_points,AdaptiveOuterMesh,UniformObservedFixedCost,WidthSearchPolicyandExecutionConfigvalidate every field, and every entry of every mapping or tuple field, when they are constructed. PyLCM now depends on Pydantic 2. - A floating option accepts a Python
intand stores it as afloat:FUESEnvelope(jump_thresh=2).jump_threshis2.0, andExecutionConfig(device_memory_headroom_fraction=0)is accepted as0.0. Booleans, strings, NumPy scalars,DecimalandFractionare refused; counts accept an exactintonly. - Invalid field data of
WidthSearchPolicyandExecutionConfigraisesValueError, naming each failing field path, in place of a mix ofTypeError,ValueErrorand beartype violations. Invalid data of the envelope, outer-mesh and fixed-cost records raisesRegimeInitializationError. Positional, missing and unexpected arguments still raiseTypeError.
- Every process-law value is a float, however it is written: a stochastic process's
mu,sigma,rho,n_std,start/stopand mixture parameters,JointNormalIIDProcess'smean,covandn_std, and the values ofStateConditioned.by. Anintis accepted and stored as a Pythonfloat, soNormalIIDProcess(mu=1, ...)andNormalIIDProcess(mu=1.0, ...)declare one law, with one set of nodes and transition rows. A Boolean is refused withGridInitializationError. - The same holds for a law fixed through
Model(fixed_params=...)and for a shock-group coefficient or correlation, fixed or supplied at runtime: an integer becomes a float before any integer range check, somu=2**31is a valid law. - A model whose law was written with integers has the semantic fingerprint of its float twin. Solutions saved with an earlier version from such a model do not load; solve again.
StateConditioned.byis stored as a read-only mapping of floats; a later change to the caller's mapping does not reach it. It pickles through its constructor.
- A params slot read as a float takes an integer value as a float: a library
coefficient (
discount_factor, a Koopmans or certainty-equivalent coefficient, a taste-shockscale, a runtime process law or grid point) and a callback argument annotatedfloator with a float array alias such asScalarFloat. This holds for ordinary, edge, exit and shock-callback parameters, fixed or supplied at runtime, and for each entry of aTimeVaryingseries. A slot read as an integer, or not annotated, keeps the value's kind, and a Boolean always stays Boolean. - A model that fixes such a slot to an integer has the fingerprint of its float twin, which differs from the one an earlier version gave it; solve again.
- One parameter read as a float by one function and as an integer by another raises
ModelInitializationError; give the two readings distinct names. The same Python object may feed a float slot and an integer slot; each slot gets its own cast.
- A user function may return a Python scalar where an array is read, and an integer
where a float is read: a utility
return 0, a transition probabilityreturn 1, a constraintreturn True. The value is converted where the engine receives it, at the model's precision. - Each role's returned dtype is checked when the function is first evaluated in
solve(), and a mismatch raises the newInvalidFunctionOutputError, naming the function:- constraints,
ValueDependentConstraintpredicates, gates, participation predicates and exit availability return a Boolean. An integer0/1, which gates, participation predicates and exit availability accepted before, is refused; write the comparison, e.g.work == 1; - laws of discrete states, deterministic regime selectors and projections onto a discrete state return an integer code, or a Boolean for the codes 0 and 1. A float is refused rather than truncated onto a code;
- utilities, laws of continuous states, transition probabilities, joint-transition weights and outputs, exit utility adjustments and borrowing bounds return a number. A Boolean is refused.
- constraints,
- An integer code of any width or signedness, and an integer a law returns for an
integer value grid, is converted to
int32where the engine receives it, at both precisions. Values outside theint32range are outside the contract and wrap; declared codes and grid values are already confined to it. - A
ByAgeor per-period law is checked case by case, each by the role of the function that wrote it, before the cases are combined. - A parameter read by an edge law takes its numeric role from the laws that are live at some age; a declaration no age uses does not change it.
- See What a function returns.
- A continuous grid stores
startandstopas Pythonfloats andn_pointsandpoints_per_segmentas Pythonints. Anintbound is converted. A JAX scalar bound, and a JAX array as a count, are refused withGridInitializationError.dataclasses.replace, equality and pickling work on the stored values. - The semantic fingerprint of every model with a linearly, log- or piecewise-spaced grid changes, as do those of models with a constant regime law, a deterministic regime selector or a stochastic transition. Solutions saved with an earlier version do not load; solve again.
- An error or log message prints an age as an integer when it is whole and with two
decimals otherwise, e.g.
age 25andage 25.33. - A
ConditionalActioncondition is stored in one numeric kind: as floats if any listed value is a float, otherwise as integers.
Gradients of simulated statistics are not meaningful in models with discrete choices, so the custom derivative rules that existed only for them are removed. Values are unchanged. The solvers keep the derivative rules they use themselves.
TauchenAR1Process.on_nodes(transition_rule="density")rows, the mixture quantile, the certainty-equivalent power means and the Epstein–Zin continuation mean no longer carry a custom derivative rule.- The zero-safe weighted reductions, the balanced and scaled-down products and the hard
maximum work on the bit pattern of their operands, where plain automatic
differentiation would return zero. Differentiating through them raises the new
lcm.exceptions.UnsupportedDifferentiationError. - The native exact-affine reads and query winners carry no derivative rule; differentiating through them raises.
- The implicit derivative of a continuous outer optimum
(
_lcm.optimization.implicit_outer_derivative) and its Mahler–Yum pilot (lcm_examples.mahler_yum_2024.implicit_pilot) are removed. - Semantic fingerprints change for every model; solutions saved with an earlier version do not load.
- The grids (
LinSpacedGrid,LogSpacedGrid,IrregSpacedGrid,PiecewiseLinSpacedGrid,PiecewiseLogSpacedGrid,GridBreakpoint,DiscreteGrid,ConditionalAction) are defined inlcm.grids, the stochastic processes inlcm.processes, andRefandConditioninlcm.condition.StateConditionedis defined inlcm.state_conditionedand re-exported fromlcm.processes. The engine modules under_lcmno longer export these classes; import them fromlcm. - A class's module path enters the fingerprint of every solution whose model uses it, so a solution saved with an earlier version cannot be loaded against a model built with this one. Solve again.
- A grid's
start,stopand breakpoint values are converted tofloatat construction. - A number compared with a
ref(...)is stored as afloatand a flag as abool, soref("x") <= 1andref("x") <= 1.0declare the same condition and both render asx <= 1.0. An integer literal now works as a case threshold. - The engine's internal functions check their annotations without the numeric tower: an
intreaching a parameter the engine declares asfloatis an internal error. The publiclcmpackage keeps the tower, so a publicfloatparameter still admits anint.
ExecutionConfig(value_storage=...)says where a solve keeps solved values once no period still to be solved reads them:"device"(the default, unchanged),"host"(pinned host memory, at most three periods' values on the device) or a directory (one archive per solve on disk, in theSolutionResult.saveformat). EGM-family simulation policies take the same path. Values, policies, reads and simulated panels are bitwise those of"device". The budget planner counts only the periods on the device, and a refusal caused by stored values namesvalue_storage.- A NaN in the value function is diagnosed at the end of its period, while the values are still on the device; the solve no longer reads values back after the loop to report it.
- Off the device, a simulation of several subject chunks runs period by period: each
period's values and policies are copied once for every chunk, and the next period's
declared reads are copied while the current period runs. Block-major solves accept
"host"and a directory. A failed copy or write raises the newValueStorageError, naming the period, the regime and the target.
- A simple discrete-state law is checked against the target regimes retained by its solve or simulate graph. A regime outside those targets no longer causes a category mismatch. Per-target laws remain explicit mappings, and a simple law still cannot cross different category sets on a retained edge.
- Current IID shocks are declared once, as
ShockGroups inModel(shocks=...), and each regime that reads a group lists it inRegime(shocks=...). A function reads the physical realization by the shock's name; no state grid or stored value axis is added. See IID shock declarations and Declare current shocks independently of states. - Reading
<shock>_codeof a continuous shock in ashocks=group raisesShockDeclarationError: a physical draw has no quadrature-node position. Category codes ofDiscreteshocks stay readable. - Node rules are
Product,MonteCarlo,QuasiMonteCarloandUserNodes; thin a group of several shocks withQuasiMonteCarlo.UserNodeswith a negative weight raisesShockDeclarationErrorwhen it is declared. Regime(exits={name: Exit(...)})declares a value-dependent move in the current period, before the action, withExitTargetdestinations and a"unilateral","mutual",Consentor custom rule; see Current-period exits.simulate(shock_paths=...)and tagged entries in mapping-forminitial_conditionsoverride current shocks:BaseInnovations(values=...)supplies innovations transformed through the current law,PhysicalValues(values=...)supplies physical realizations. A path supersedes the entry value. See Typed draw inputs.- Simulated panels change once. Every draw is addressed by the seed, the subject's
original row in the initial conditions, the period, and the shock's name and
component (address version
pylcm.random.v1). Draws no longer depend on the regime path, other shocks, group membership or taste-shock toggles, and one seed gives the same base draws across parameter values. Reordering initial-condition rows changes which draws a subject receives.
- Post-decision shocks are simulated with continuous draws by default; panels change. A
shock read only as
next_<shock>is still integrated over its nodes in the solve, but simulation now draws it from its law. AModel(shocks=...)group always draws continuously; an IID process state integrated out this way honours itssimulated_draws, whose default is"continuous", andsimulated_draws="nodes"keeps the node lottery. Process states that carry an axis are unchanged.NNBEGMregimes now integrate such a shock out as well, instead of keeping a node axis along which the value was constant; their solve is cheaper andrepr(model)lists the shock underintegrated=. See Shock timing is inferred.
- Breaking API: the process keyword
simulate_draws=is nowsimulated_draws=, on every IID and AR(1) process and onTauchenAR1Process.on_nodes. The values stay"continuous"and"nodes". Passing the old keyword raisesTypeErrornaming the new one.
lcm.solvers.SolverBuildContext.fold_state_namesis removed. No declaration could set it sincefold=was removed, so it was always empty. A custom solver that read it must drop the read.
- Breaking API:
lcm.ArrivalDecisionis renamedlcm.ParticipationCheck,lcm.ArrivalReadislcm.ParticipationRead, andTransition(arrivals=...)isTransition(participation=...). The construct also re-checks continuing couples (couple → couple, where failure means divorce); it is the per-period limited-commitment participation constraint. There are no aliases; see Arrival → participation check. - The read-projection parameter path
params["edges"][source][target]["references"]is now["reads"], named afterParticipationCheck.reads. SOLUTION_FORMAT_VERSIONis 3: archives store participation surfaces under renamed manifest keys, and version-2 archives no longer load.
- An endogenous-grid regime (
DCEGM,NBEGM,NEGM,NNBEGM) whoseutilityreads a process state (IID or AR(1), such as Tauchen, Rouwenhorst oron_nodes) or ashocks=draw other than through its resources function now raisesModelInitializationErroratModel(...), unless the process state is declared withsimulated_draws="nodes". Simulation used to blend the bracketing node policies for a draw between nodes, an approximation for a process that changes preferences; node draws read one node row exactly. Move the process into resources or solve the regime withGridSearch. Otherwise, declare a process state withsimulated_draws="nodes"; ashocks=group has no draw mode of its own, so declare its shock as an IID process state withsimulated_draws="nodes". See DC-EGM.
lcm.solver_api.DISSOLUTION_FLAGandlcm.solvers.DISSOLUTION_FLAGare removed, and the type idpylcm.collective.dissolution_flagis no longer reserved. A collective kernel no longer emits the flag on its solve-time channel; simulation recomputes an empty feasible set at the realised state. External solvers that imported the key or published under it must drop it.
- An exit that observes every shock of a target group prices that group's rows from one representative, and query cells and information rows run as batched lanes. Values are unchanged up to floating-point vectorization. Partly observed groups keep their rows. Model build refuses an observed continuous caller law whose spread can vanish at the caller but not at the target; see Current-period exits.
- Every stochastic process follows one rule. Reading
xin a model function reads this period's realization, known at the choice; readingnext_xreads the draw after the choice, which the solve integrates in the continuation. AR(1) and Markov states already behaved this way. - A
ShockGrouplisted inRegime(shocks=...), or an IID process declared as a state, carries an axis only when some function of the regime reads its current value. A shock read only asnext_xby state transitions has no axis: the solve integrates the transitions over its nodes and weights, and simulation draws it from its continuous law. An initial value supplied for such a state is dropped. - Utility and constraints reading
next_xare refused at model build. A group read both asxand asnext_xin one regime is refused; declare the shock as an IID process state to carry the realization into the next period. repr(model)lists, per regime, which shocks carry an axis and which are integrated out.- The
fold=argument of IID processes is removed and raisesTypeErrornaming the replacement. Dropfold=; see Shock timing is inferred.
- Value-reading gates,
Gate.referencesand the dissolution-flag artifact are removed. State-only gate routing keeps its behavior. - A
Gatepredicate namingV_target,V_target_<s>orD_targetraises the newlcm.exceptions.GateReadsValueErrorwhen the gate is declared, andGate(references=...)raisesTypeError. Declare a value comparison made in the current period as anExitinRegime(exits=...), and one made on landing as aParticipationCheckwith namedParticipationReads inTransition(participation=...); see Gates route on states only. solve()no longer publishes aDISSOLUTION_FLAGreplay artifact, andsimulate(solution=...)reads none. A household landing in a gated target cell where no action is feasible still takes its route's fallback.
MSSEnvelopeis no longer part oflcm.solvers: a timing study found it dominated byExactEnvelope. SelectExactEnvelope(the default),FUESEnvelope,RFCEnvelopeorLTMEnvelopeinstead. An interface for envelopes maintained outside pylcm is planned in issue #632.
- Named current-IID shocks in
DCEGM,NBEGM,NEGMandNNBEGMregimes are solved only on the node-state axis. The native route that solved them without it (Case-R resources rows and banks, Case-U candidate reconstruction and the projected continuation) is removed, together with its environment switch. DCEGM(current_iid_projection_capacity=...)is removed; it sized only the native route's projected continuation.
- The shipped example now declares current Normal income with positive base
Gauss-Hermite quadrature. An explicit
lagged_uncertaintystate preserves the original law: next period's income scale depends on this period's uncertainty. Initial callers declare both uncertainty states and tag known income withPhysicalValues; income remains observed before consumption. Current policy pricing replaces the former physical income-grid interpolation, so old finite-grid values and seeded records are historical evidence rather than new-route baselines.
AgeSpecializedGrid(build=...)no longer requiressignature. Without it, ages share one compiled program exactly when the gridsbuild(age)returns have the same class, node dtype and node bytes. An explicitsignaturestill works and may be coarser.AgeSpecializedFunctionstill requiressignature.
Model(composite_states={"history": CompositeState(members=..., start_codes=...)})replaces the axes of deterministic discrete member states by one generated discrete state over the member tuples reachable from the start codes, so the value function is solved and stored on those tuples only. User functions keep reading the members, and initial conditions name them. A generated constraint,<name>_is_reachable, makes each tuple infeasible at the periods it cannot be reached in.- Member laws must be deterministic and read only discrete variables, the period, the age and fixed parameters; a stochastic or phase-specific member law, a law reading anything else, a member held on different grids, a member declared by its values, and a member law reading a variable declared by its values are refused by name.
ConditionalAction(grid=..., active_when=..., inactive_value=...)declares a continuous action that is active only where named discrete actions of the regime take listed values, and takes a node of its grid everywhere else. It is enforced as the equivalent pin constraint, so results equal those of the hand-written constraint.
characteristics(category_class=..., by_category=...)checks a table that lists every category'sint,boolor finite, float32-rangefloatcharacteristics against a categorical class and returns read-only arrays indexed by code.category_with(columns, **characteristics)maps only bool or signed-integer identifying columns back to a category code underjitandvmap, returning the int32 minimum where no category matches. A new user-guide page shows how to declare, publish and read such characteristics.
- A deterministic law of a discrete state that leaves its grid at a cell where some
choice is feasible raises
InvalidStateTransitionErrorbefore the solve, naming the regime, period, law and cell; cells where no choice is feasible never count.Model.validate_transitionsruns this check too. Feasibility here is the ordinary constraints, in both phases: a value-dependent constraint or a gate that reads a value cannot exclude a cell whose code is off the grid, since that code has no value. Declare a value-free restriction as an ordinary constraint instead. - Behavior change: with
runtime_checks=False, reading the value function at a code outside0..n-1gives NaN instead of the value at the nearest end node. This holds for category grids as well, which used to clamp silently. An integer value grid has no NaN, so a user function reading such a state receivesMISSING_CAT_CODE, the int32 minimum, while the value function there is still NaN. DiscreteGrid(values=jnp.array([0, 20, 40]))declares a discrete variable by its numbers instead of a category class.valuesis a one-dimensional NumPy or JAX array of integer or floating dtype; lists, tuples and ranges are refused. Values are strictly ascending and finite, integers are stored as int32 and floats at the canonical float dtype. Codes stay0..n-1;categoriesholds thereprof each value.- A user function may read
<name>_codefor any discrete variable<name>, state or action, in functions, constraints, state transitions and regime-transition laws. For a value grid<name>is the value (pandas: the category) and<name>_codethe int32 position (pandas: the code); for a category class both are the code. A parameter array indexed by<name>_codetakes apd.Serieswhose level is named<name>and labelled by the values or category labels, aligned to grid order in any written order. Indexing an array by the value of a value grid (table[experience]) is refused at model build, namingexperience_codeas the fix, and a state, action, function or constraint named<name>_codefor a discrete<name>is refused as a name collision. IrregSpacedGrid(points=...)andTauchenAR1Process.on_nodes(nodes=...)take only a one-dimensional NumPy or JAX array of integer or floating dtype, asDiscreteGrid(values=...)does;on_nodesnow accepts arrays, and a list, tuple or range is refused with an error that shows the array spelling.- A float matches a node exactly unless the grid declares an absolute
tolerance, which must lie below half the smallest gap between values; integer grids take integers and match them exactly.grid.encodemaps values to codes (off-grid values get the missing-category code),grid.decodemaps codes to values (an off-grid code reads NaN on a float grid), andgrid.nearestsnaps a float to its closest node. - User functions of a model receive the values of its value grids, and a deterministic
law of a value-grid state returns a value, which becomes the code of its node. A
stochastic law reads values and still returns probabilities in the order of
values. Integer values arrive as int32, as codes do. A variable declared with values must carry the same values and tolerance in every regime. Regime transition laws, gates and their projections, collective regimes (stakeholder utilities, Pareto weights, value-dependent constraints and their projections), joint transitions and carried-state imputations read values too; a projection, a joint output and an imputation of a value-grid state return a value. Afunctools.partialreading a value grid asks only for the arguments it leaves free. Condition constraints that read a value grid, and age-specialized functions, constraints and imputations in a regime with value grids, are refused; this includesPhasedfunction declarations and model-level derived value grids. - A float value grid holds its values at the precision of the model that uses it, so a grid built before x64 is enabled holds float64 values in a float64 model. Values that collide at that precision raise when the model is built.
- Breaking:
use_labelsis renameduse_categorical_codes, with the opposite meaning, inSimulationResult.to_dataframe,SolutionResult.value_arrayandSolutionResult.value_frame;SimulationResult.savetakesdf_use_categorical_codes. The defaultFalsekeeps categorical columns and coordinates;Truegives integer codes. There is no alias for the old name. - Behavior change: the user-facing boundaries speak a value grid's values instead of its
codes.
to_dataframegives an ordered numeric Categorical over all of the grid's values (cast with.astype(float)for arithmetic). Initial conditions, as a mapping or a frame, take the values, as numbers or as such a Categorical, whose categories must be exactly the grid's values in order; integers match exactly, floats within the grid's tolerance, and anything else raises naming the value. Apd.Serieslevel inparamstakes the values as labels and refuses string spellings.lookup_policyreads states andaction_gridsin values and returns a value-grid action as an array of its values.value_arrayandvalue_frameuse the values as coordinates.use_categorical_codes=Trueonsolve,simulate,validate_transitions,validate_initial_conditions,initial_conditions_feasibilityandlookup_policyswitches these inputs and outputs to integer codes, for category-class grids as well.shock_pathskeeps category codes for every discrete state, so a path replays exactly. A mapping of initial conditions also accepts pandas Series, and Categoricals for value grids.
Regime(koopmans_aggregator=lcm.Decoupled(objective=..., value=...))chooses actions withobjective(utility, CE, ...)and storesvalue(utility, CE, ...)at the chosen action.objectivemay bePhased, so the solve and simulation choose differently; withu + β̃δ·CEin the solve,u + βδ·CEin simulation andvalue = u + δ·CEthis covers the naive, sophisticated and partially naive beta-delta agents. WithExtremeValueTasteShocksthe objective sets the choice probabilities and the stored value is the expectedvalueat the noisy choice. Both functions read parameters from thekoopmans_aggregatornamespace, where a shared name is one parameter.PolicyLookup.Q_objectivepublishes the objective's action values. OnlyGridSearchsupports it; collective regimes, gated-edge sources and sharded continuous states refuse it. APhasedKoopmans aggregator is unchanged.- A state or regime-function input read only by a Koopmans aggregator reaches it.
Model.lookup_policyaccepts GridSearch regimes withExtremeValueTasteShocks. The returnedPolicyLookuphasactions=Noneand adds, per state row and discrete-action combination, the conditional valueQc, thechoice_probabilitiessoftmax(Qc / scale)and theconditional_actionsattainingQc;valueis their smoothed maximum;keep_intermediatesaddsQ,F,UandCEas elsewhere. These describe the discrete choicesimulatedraws:valueequals the stored solve value at grid rows to numerical precision when both phases share the current utility and Koopmans aggregator and the action grid is the declared one. Regimes solved by an EGM-family solver are refused.
Model.simulate(seed=...)andtaste_shock_seed=...accept scalar typedjax.random.keyroots directly, preserving their PRNG implementation and the existing integer-seeded streams. Legacy uint32 keys receive guidance naming the typed constructor. Budgeted entry accounts for caller key buffers before uploads or automatic solving; chunk profiles distinguish the actual implementations. Independent taste draws from an RBG or unsafe-RBG root fold and draw each subject's key as a scalar, so subject widths and padding do not change them.- The Mahler initial-population factory accepts the same typed roots with its existing positional splits.
Model.lookup_policy(..., keep_intermediates=...)replacesreturn_action_values=True, which is removed. It takes any subset of"Q","F","U"and"CE", in any order, and fills only those fields ofPolicyLookup; the default()keeps none and runs the plain decision.return_action_values=Truebecomeskeep_intermediates=("Q", "F", "U", "CE"), or("Q", "F")for its former output.Uis the flow utility andCEthe undiscounted certainty-equivalent continuation, per state row and action, with the shape ofQ.Q == W(utility=U, CE=CE, ...)for every Koopmans aggregator, soQ == U + discount_factor * CEunderLinearAggregator; a terminal regime hasCE == 0.actions,valueand the kept intermediates come from one evaluation of the regime's kernel.- An unknown or repeated name raises
InvalidSimulationInputError.
lcm.EULER_GAMMAexports the Euler-Mascheroni constant. Addingscale * EULER_GAMMAto Bellman utility reproduces location-0 shocks underLinearAggregatorwhen other uses of the original utility are preserved; see the location-0 recipe.
- A regime-level state that a regime only carries, with
fixed_transitionor any other law of motion, toward a target it can reach is used when that target keeps the state. Model-level states were already kept this way by broadcast pruning, and the check now runs the same closure. Its own rule is stricter than pruning's: the target must be reached in the law's own phase, at ages the source occupies, and keep the state on its grid in that phase, on an edge where no joint transition produces the state. Chains count. A zero-weight read such as0.0 * skillis no longer needed to keep such a state. The rejection message states the rule and the regimes each phase reaches.
TimeVarying.from_profile()acceptsage_to_label, mapping each model age to a source label. The result is labelled by age and serves models on anAgeGrid. Give exactly one ofperiod_to_labelandage_to_label; the validation is the same for both, and age keys must be finite numbers. A non-integer period key, including a boolean, raisesInvalidParamsError, as it does for aTimeVaryingcoordinate.- A NumPy
TimeVaryingtable keeps its dtype until the canonical cast, so an int64 value outside the int32 range raises the int32 overflow error, and a float64 value that float32 cannot hold is reported with its supplied value, also with x64 disabled.
Model.solve()andModel.simulate()acceptruntime_checks=Trueindependently oflog_level. Enabled numerical checks raise on the first failure at every verbosity, includingoff; disable them explicitly withruntime_checks=False. Construction, parameter schema, initial-condition structure and solution identity validation remain active. Infinity-only value warnings retain their existing meaning.
SolutionResult.value_array(period=..., regime=...)returns an xarrayDataArraynamedVwith one dimension per state axis, the resolved grid nodes as coordinates, discrete states labelled as categoricals in declaration order (use_categorical_codes=Truefor integer codes), and astakeholderdimension for collective regimes. It wraps the stored value without a host copy;.sel(...)selects a curve or surface by name before any table is built.SolutionResult.value_frame(...)returns the same values as a long pandas DataFrame with state columns followed byV. Both survive saving and loading.- New dependency:
xarray.
- Declare admissible starts with
InitialNodes(by_age={25: "working"})orInitialNodes(by_period={0: "working"}), matching the model's clock. Exactly one nonempty mapping is required. This replaces the singularInitialNodeinterface. The model returns a normalized immutableInitialNodesmapping exact coordinates to sorted, unique regime tuples. Code unpackingmodel.initial_nodesmust usemodel.graph.initial_nodesfor expanded pairs. Legacy pair collections and bare selector mappings remain accepted in age models; period models requireby_period. - Edge mappings and nested transition-law mappings are copied and frozen at
construction, including mappings in
ByAge,ByPeriod, andPhased. Reusing caller dictionaries cannot change a model's published configuration; callable identity is preserved.
- Breaking API:
ValueDependentTransitionis removed. A value-dependent destination is declared asTransition(law=..., gates={target: Gate(...)}). The law supplies the gated target's probability like any other per-target cell, andGatecarries the rest:predicate(formerlygate),routes,references(formerlygate_references) andoff_grid. A law celltgt: ValueDependentTransition(probability=p, gate=g, routes=r, gate_references=refs)becomes the law celltgt: pplusgates={tgt: Gate(predicate=g, routes=r, references=refs)}. - One
Gateper target holds at every age the target is reached and in both phases; a gate is never wrapped inByAgeorPhased, and only a route'sfallbackmay bePhased. WithPhasededges, a target reached in both phases carries the equalGatein both or none. A gate on a target itsTransitionnever reaches is refused. - Breaking API: the parameter paths of a gated target follow the declaration.
params["edges"][source][target]["probability"][arg]becomesparams["edges"][source][target][arg],["gate"][arg]becomes["predicate"][arg], and["gate_references"][reference][state][arg]becomes["references"][reference][state][arg]; route fallback paths are unchanged. Transition.targetsis optional when the law names its targets — a per-target mapping, a regime name, or aByAge/Phasedof those. The destinations are derived from the law: each key at the non-final source ages its case covers, and each gate's route fallback regimes at the ages of the gated target. Supplied anyway,targetsmust equal the derived mapping exactly, orModel(...)raises aModelInitializationErrorlisting both. A law over all targets — a function, aDeterministicTransitionor a full-vectorStochasticTransition— still requirestargets. See the migration guide.- Breaking API:
lcm.collectivedoes not re-exportStochasticTransition; import it fromlcm.
Model.solve(period_capture=PeriodCapture(...))atomically records selected ordinary GridSearch entry inputs and appends completed references. A freshModel.replay_periodbinds model/grid/parameter/source identities and validates recorded layout, widths, optimized HLO and admission before dispatch. Entry-only captures remain inspectable and cannot claim reference parity. See period capture.
ExecutionConfig(action_partitions={"<regime>": n})shares aGridSearchregime's action product overndevices. Each device reduces its own contiguous run of action blocks with the exact hard maximum, and the devices exchange and merge one compact accumulator per state cell instead of any value over actions. Ties, infinities, NaNs and signed zeros keep the ordinary route's conventions; at the same action width the tested workloads publish values bitwise equal to the ordinary route, alone, with a sharded continuous state and with type-local blocks. The default{}and a count of one leave the solve unchanged. Unsupported requests are refused at model construction. See Share a large action product over devices.
- A law may read the draw
next_<process>of a process state, for instance costs realized after the period's choices and paid out of next period's wealth. A persistent process's draw is conditional on the state's current node, so reading it is a read of the state: the regime that reads it keeps the state, whether the state is declared at model level (broadcast pruning) or at regime level (the unused-variable check). An IID process state read only through its draw carries no axis and is integrated in the continuation; see Shock timing is read off the model. - Toward a target that does not carry the process, the draw exists only inside the
transition: it is taken from the source's process at the source's current node, read
by the target's laws and discarded. A terminal regime valuing only wealth therefore
carries only wealth.
GridSearch,DCEGM,NBEGMandNNBEGMsolve and simulate such edges. - The same holds for a Markov state (a
DiscreteGridwith aStochasticTransitionlaw): reading its drawnext_<state>keeps the state in the reading regime, and toward a target that does not carry it the draw is taken from the source's Markov law, with that law's parameters. This requires the law to be declared once for every target; a per-target law names no law for a target that lacks the state. - When a regime law's probabilities do not sum to one because the law has a cell for
a target that the graph gives no edge at that age, the error names each such
(age, source -> target)cell and says the graph declares no edge for it. - A state law that reads
next_<state>toward a target that neither carries the state nor receives a draw of it on that edge is refused when the model is built, naming the source, the target, the law and thenext_argument. DCEGM,NBEGMandNNBEGMaccept a liquid law that reads a draw, persisted or local to the edge: the Euler state and its savings derivative are evaluated at every node of the draws the law reads.NBEGM's save-to-cliff targets are inverted per node. Under the EGM solvers only the liquid law may read a draw; any other law reading one is refused at construction.
ExecutionConfig(invariant_block_widths={"<state>": 1})solves every non-terminalGridSearchregime carrying an invariant discrete state one code at a time. Each code runs one shared executable with the code as a runtime operand, and reads every continuation carrying the state through that code's block. The tested workloads publish values, policies and simulated panels bitwise equal to the unblocked solve's; the default{}leaves the solve unchanged. Unsupported or unsafe requests are refused at model construction. See Solve one invariant code at a time.- When the simulate phase also keeps the state fixed,
simulategroups subjects by their starting code and reads each typed value through one code's block. Every subject keeps its original random draws and output row, so the panel is unchanged; otherwise simulation stays ungrouped. ExecutionConfig(invariant_block_schedule=InvariantBlockSchedule.BLOCK_MAJOR)solves each code through all of its periods before the next code, simulates its subjects while its values are still on the device, then copies them to the host and deletes the device buffers, so the device holds one code's values at a time. Every code runs the programs the first compiled. The result is complete: each value is assembled from the retained codes when read, on the layout the period-major schedule publishes, saves from the host, and simulates one code at a time;values.materialize()is refused when every value cannot fit the device budget. Values and panels equal the default period-major schedule's byte for byte. Unsupported requests (no blocked state, a regime without it, budgeted or ungrouped simulation,log_path) are refused. See Solve, simulate and release one code at a time.
- Ordinary per-target
Phasedlaws may declare different solve and simulation destinations, with state handoffs local to each phase. Every physically visited node is valued, together with its recursively required perceived continuations. - Construction-fixed, exactly zero scalar probability edges are omitted from reachability. State, action, age and free-parameter dependencies retain their declared edges; invalid all-zero lotteries still raise at execution.
- Breaking API:
ChoosebecomesDeterministicTransition,MarkovTransitionbecomesStochasticTransition, andinitial_regimesbecomesinitial_nodes. Both transition wrappers support decorator factories and carry numerical kernels only. Plain functions remain deterministic. RequiredModel.edgesmaps each source to destinations and their source-age selectors, optionally throughPhased.model.graphprovides immutable declared edges, effective reachability and fixed-zero pruning reasons. Model(edges=...)is the only place regime transitions are declared, structure and law alike. Breaking API:Regimehas noregime_transitionsfield.- A source with exactly one outgoing edge at every source age can be declared as
a plain
{target: source_ages}mapping, with no law: the graph is the law. Deterministic schedules such as"dead"orByAge.until(law="working", then="retired")are expressed by the edges alone. - A source with a law is declared as
Transition(targets={target: source_ages, ...}, law=...); one where some source age has several outgoing edges needs one. The law is any formregime_transitionstook: a per-target probability mapping, a selector function returning a regime code (a discrete choice), a full-vectorStochasticTransition, a regime name,ByAgeorPhased. - A supplied
Transitionlaw is evaluated at every source age with outgoing edges, also where one edge leaves the source; there it must put unit mass on that edge. Only an age aByAgelaw leaves unselected uses its one edge instead; aByAgelaw must select every age with several edges. - A regime with no outgoing edges is terminal.
- A law that differs between the phases is phased inside one
Transition:Transition(targets=..., law=Phased(solve=..., simulate=...)). Destinations that differ between the phases go inModel(edges=Phased(solve={...}, simulate={...})), each phase's mapping with its ownTransition. DeterministicTransitionandStochasticTransitionhave notargetsfield.Regimecarries no law, soRegime.terminal,Regime.gated_edgesandRegime.decomposed_transitionare gone.model.graph.laws[name]holds each regime's law as the model binds it, withterminal(no outgoing edges),gated_edgesanddecomposed_transition.- Parameters of edge-declared callables (the regime-transition law, gates, gate
references, route fallbacks) live at their declaration path under
params["edges"][source], and resolve from that path,params["edges"][source][arg]or the model level. A regime-level value never reaches them;next_regimeandgatekeys under a regime raise an error naming the new path. Per-target state laws keep their paths under the source regime. See the migration guide. - Names that become parameter-path segments contain no
__and do not start or end with_;edgesis reserved as a regime, function and argument name.
- A source with exactly one outgoing edge at every source age can be declared as
a plain
- Probability mass validation is shared by the solver consumers. Compiled validation now reliably rejects negative subnormal probabilities at both precisions.
Model(..., initial_nodes=...)is required and has no default. It accepts exact(age, regime)pairs or maps age selectors (exact age, tuple,range,AgeRange(start=..., exclusive_stop=...)) to one regime name or a nonempty sequence of names; the resulting pairs are the admissible roots, published asmodel.graph.initial_nodes.model.initial_nodesis the normalizedInitialNodesdeclaration.None, a bare name, an empty mapping, unknown names and off-grid ages raise.AgeGrid.inclusive_stopincludes the final grid age;AgeRange.exclusive_stopexcludes its upper selector bound.- Solved problems are derived from the roots — physical successors plus declared value
reads — rather than from transition schedules.
ByAgeselects laws only;ByAge(cases=..., default=law)fills every unmatched age, including the last. - A regime is terminal exactly when it has no outgoing edges in
Model(edges=...). Model.declared_transitions[phase][source]is theTransitiona source declared, exactly as declared, withphaseone oflcm.typing.Phase("solve","simulate"). Itslawis typedlcm.transition.TransitionLaw, itsgatesmap each gated target to itsGate, and itstargetsare the declared or derived destinations;model.graph.lawsholds the law as bound to the graph.ByAge,ByAge.until,AgeRange,DeterministicTransitionandStochasticTransitiontake keyword arguments only.ByAge.until(*, stop_age_exclusive, law, then, start_age_inclusive)usesthenat the last source age belowstop_age_exclusive. See Migrating to age-indexed regimes.
ExecutionConfig.device_memory_bytesdefaults to"device": the budget is the smallest selected device's allocator pool limit lessdevice_memory_headroom_fraction. On GPUs and TPUs, which report a pool limit, the planner now picks the widest widths that fit instead of compiling every omitted axis at its bootstrap width. CPUs report no limit, so the default stays unbudgeted there.device_memory_bytes=Nonerestores the unbudgeted planning explicitly; an integer is unchanged.- Importing pylcm no longer sets
XLA_PYTHON_CLIENT_PREALLOCATE=false: JAX preallocates its default 75% of each GPU again, and the default budget is derived from that pool. To allocate on demand, setXLA_PYTHON_CLIENT_PREALLOCATE=falseyourself and pass an explicitdevice_memory_bytesorNone. With a reported pool limit the default refuses an on-demand pool, because the BFC allocator then grows it in separate regions and the limit does not promise one contiguous block; the error names the fixes (preallocation,TF_GPU_ALLOCATOR=cuda_malloc_async, an integer budget orNone). - The GPU test tasks and workflows preallocate a per-worker share instead of turning
preallocation off:
XLA_PYTHON_CLIENT_MEM_FRACTIONis 0.75 for the serial policy launcher (pixi run test,gpu32,gpu64) and 0.1875 for the four-workerteststasks, so each worker's default budget comes from its own slice. - Routes that cannot be budgeted ---
enable_jit=False, forward simulation through host gated or replay adapters, and a supplied foreign result with replay payloads --- refuse the default budget as they refuse an explicit one; passdevice_memory_bytes=Noneto run them unbudgeted. - Budgeted simulation of finite NB-EGM replay on GPU no longer charges the policy copy's host-side scratch to the device ceiling, which refused every such simulation with "names an unbudgeted device", and a warm budgeted call no longer retraces its process grids.
- Every admission refusal names the budget and its source, then lists the remedies:
raise
device_memory_bytesor lowerdevice_memory_headroom_fraction, cap or fix widths withaxis_width_ceilings/axis_widths, shard over more devices withsharded_states/devices, or disable admission withdevice_memory_bytes=None. - The benchmarks, which run with preallocation off, pass the default budget as an
explicit one wherever they built a model without a budget (
bench_aca_baseline,bench_collective_household,bench_iskhakov_et_al_2017,bench_mahler_yum,bench_precautionary_savings,bench_simulation_dispatchand the paired GridSearch scenarios), so they plan under it and their widths and timings change.lcm_examples.collective_household.get_modeltakes anexecution_config, andlcm_examples.mahler_yum_2024.MAHLER_YUM_MODELis built on first access rather than at import.
Model.validate_initial_conditions(initial_conditions=..., params=...)andModel.initial_conditions_feasibility(initial_conditions=..., params=...)check a population without solving or simulating. Both accept thesimulateinput forms (a mapping of arrays or a DataFrame with regime names, ages and categorical labels) and ordinary user parameters. The first raisesInvalidInitialConditionsErrorwith the simulation diagnostics; the second returns a one-dimensional boolean mask in caller order,Trueexactly for the subjects admitting a jointly feasible action combination on the declared action grids. Malformed inputs raise from both, and so does a collective start without theown_stakeholderdeclarationsimulatedemands, so a population the methods accept is onesimulateaccepts. The checks take nolog_level; at present they run in one eager pass on one device without device-memory admission or subject padding, which does not affect the verdict.- Subjects of a regime without actions are now checked against that regime's state-only
constraints, in
simulateas well. Populations that previously simulated from such rows raiseInvalidInitialConditionsErrorwhen a state-only constraint fails. - When a constraint depends on an age-specialized function, each subject's initial feasibility is checked against the constraints and functions resolved at its own start period, so subjects may start at any active age of the regime.
- Coverage now measures the child Python processes the test suite spawns
(
[tool.coverage.run] patch = ["subprocess"]), so the execution and sharding code those tests exercise is reported as covered instead of missing from every diff.
docs/explanations/architecture.mdnow describes the execution layer as built: ownership and lifetime of device buffers, admission and workspace planning, value transfers between regime meshes, and the resolved simulation plan. The development pages gaincertification.md, which explains the candidate certificate, its source corridors, the seal check and the re-pin tool, andcontinuous_integration.mdnow documents the sharded CPU workflow, the workload manifest and its generator. The user guide's debugging, tuning and subject-parallel pages cover the log tiers, the budget knobs and the sharding routes that landed in this cycle, and every engine module carries a module docstring naming what it owns.- The claim that a
Nonedevice-memory budget queries no device was wrong and is corrected everywhere it appeared: an unbudgeted request applies no pool-derived cap, but public model construction still reads each visible device's pool statistics once. tests/ci/generate_ci_workloads.pyregenerates the CI workload manifest and checks it accounts for every test file;tests/candidate_certificate/test_repin_corridors.pypins the re-pin tool's contract.
- Budgeted admission now reserves a planned transfer's declared temporary bytes — what the operator holds beyond the value it delivers, which for a copy onto another regime's mesh is a second whole value — whenever a solve plans a copy, rather than only on the route that shards a continuous state. The charge lands on each endpoint of the copy, the devices the stored value sits on as well as the reader's, and a device that only sources a copy therefore enters the admission maximum on the stored shards plus that storage instead of escaping the comparison because no kernel of the cell runs there. An endpoint outside the plan's devices has no ceiling to be compared against and is refused by name. Both admission comparisons see the complete figure: the position gate that decides whether a core is compiled at all, and the reservation-plus-residency test that selects its workspace width. A refusal names the transfer charge alongside the regime, period, core and resident bytes, so a cell refused over a copy it only reads is distinguishable from one refused over its own values. Plans whose reads all arrive in their stored layout are unaffected; a plan that copies is admitted at a strictly larger, and now complete, footprint, so a budget that previously admitted it may refuse it.
- A gated edge's
ProjectedRegimeValue— a gate reference or a leg fallback — may now have its projection read a discrete state the source declares inExecutionConfig.sharded_states. Such a state's device axis is sliced off every value array before the continuation is read, so the interpolation places no coordinate on it; the projection, however, is evaluated at the point the source lands on and consumes the state as a value rather than as an index. The landing coordinate was dropped together with the axis, so the solve refused withExpected arguments: [..., 'next_<state>'], missing: {'next_<state>'}. A coordinate the continuation still names is now supplied, which reproduced on a single device as well, since the declaration alone co-maps the state. Values and simulated frames are unchanged wherever the solve already ran.
- Which model-level states and actions a regime keeps is now the least common fixed
point of the solution-slice and simulation-slice reachability operators, instead of
one application of each in a fixed order. The two slices feed each other: a target
regime that keeps a state only because its simulation-side payoff reads it turns the
solution side of the entry law toward that target into a live computation, and
whatever that law reads has to survive in the source regime. Closing the slices one
at a time stopped before that hand-over was visible and pruned a retained law's own
input, which surfaced at solve time as a spurious required parameter named after the
entry law (
<source>__<target>__next_<state>__<input>). It also made promoting a state from regime level to model level change the retained-state set, contrary to the declaration-move guarantee. Models with more than two alternating hops close to the end of the chain, a source feeding several targets keeps what every retained entry law reads, and the closed set does not depend on which slice is closed first. The additional work is build-time dependency traversal only; no warm-call path changes.
-
A regime reading another regime's stored value — a gated edge's
ProjectedRegimeValuefallback is the case that reaches this most often — now has that read planned from the layout the value is actually stored on. Two regimes that retain differently named sharded states run on meshes with different axis names, and the reading core's own partition spec describes its own axes and its own rank, not the other regime's; applying it to the stored value refused a solve that is well defined, with a bare "source sharding is incompatible with value shape" at solve time. Such a value is delivered to the reading core as a replica on that core's mesh and classified by the transfer catalogue from the two concrete layouts, so a model sharding one discrete state in one group of regimes and another in a second group solves. Reads between regimes on one mesh are unchanged, and a pair of meshes that overlap without either containing the other — which no single operator serves — is refused while planning, naming both regimes and both device axes. -
What such a read costs is stated where the layout is chosen. The replica is charged at its own size — the whole value on every device of the reading mesh, not a shard — with the stored value still charged on its own devices, the operator's scratch charged at the same size again, and every device either end touches named on the planned transfer. A device whose budget the reservation exhausts hosts no workspace and is refused by regime and period. A partitioned delivery is refused rather than chosen even when the reading mesh carries an axis of the stored value's own name and extent, because a value read consumes the complete value on every device: an entry law puts probability on every category of a discrete axis and interpolation spans the whole continuous line, so splitting the value would move the missing pieces into compiled work as a collective the plan does not name.
Model.simulatenow reports, once per call, the resolved execution plan: the forward route (legacy/subjects), the ordered subject devices and their backend, the resolved planner axis widths by regime, the outer chunk count and admitted chunk widths, and the budget mode with its effective device-memory bytes. A one-line summary logs atlog_level="progress"and"debug"; the complete record logs at"debug"only. Neither line appears at"warning"or"off". The record is also exposed asSimulationResult.plan_summary(Noneaftersave/load, diagnostic only). This closes the gap where a clean production run carried no evidence of which route actually engaged (issue #450). Purely diagnostic: no numerical, RNG, ownership or admission behavior changes.
- A model whose regime declares a gated edge — a
Gateon its transition, such as the dissolution edge of a collective regime — may be simulated withExecutionConfig(simulation_sharding="subjects")on more than one device. The gate fold reads and writes regime-level grids and declares no subject axis, so it is replicated and the continuations it publishes stay shared operands; the gate route recomputes each row's gate at that row's own realized candidate state, follows the leg its role selects, and writes its fallback coordinates under an elementwise mask, so its population operands are partitioned over the configured devices. The rows published are the rows one device publishes.
- A state named in
ExecutionConfig.sharded_statesmay be dropped from any regime whose DAG never reads it, not only from a terminal one. The regimes that read the state carry its grid axis and keep the submesh that axis defines; the regimes that prune it publish a value without the axis, are placed as single-device regimes, and exchange values with the sharded regimes through the existing transfer catalogue. A wage shock read through working life and dropped entirely in retirement therefore shards the expensive working-life regimes without forcing the retirement regimes to carry it. Only a state that every regime prunes is refused, because no grid axis is then left to spread over devices; continuous sharding keeps its stricter requirement that the state be retained in every regime.
- A regime that does not read a model-level state keeps the
state_transitionsentry through which it hands the state to a regime that does. Pruning drops a keyed entry law only for the targets that also prune the state, and an unkeyed law only when no reachable target retains it, so promoting a state from regime level to model level no longer turns a declared entry law into a "the source does not carry '' and defines no entry law" build error.
ExecutionConfig(device_memory_headroom_fraction=0.15)keeps a share of each selected device's allocator pool out of the admission ceiling, so a caller may pass the device's whole pool limit asdevice_memory_byteswithout planning against memory the pool cannot actually hand out. The effective budget is the smaller of the request and every selected device's pool limit less its headroom; an already-conservative request is never reduced again, a device that reports no pool limit places no cap, anddevice_memory_bytes=Nonestays unbudgeted and applies no pool-derived cap — model construction still reads each visible device's pool statistics once. The margin is an operational policy for pressure outside the represented accounting — collective buffers, library workspaces, driver context, fragmentation — and0.0restores planning against the whole pool. A capped budget is logged as a warning naming request, per-device limits and effective ceiling, and admission refusals name both budgets.
ExecutionConfig(axis_widths=...)accepts a width per regime. A bare integer under an axis name fixes that axis in every regime declaring it; a mapping from regime name to width —axis_widths={"cell": {"cheap": 512, "heavy": 8}}— fixes it only in the regimes it names and leaves the planner free in every other one, so a width one regime's shape demands no longer chunks an unrelated regime. The two forms may be mixed across axes. A regime name the model does not declare, and a per-regime width for an axis only simulation programs declare, are refused at model build with anExecutionPlanningErrornaming the declaration.
Model.simulate(taste_shock_seed=...)selects an independent Threefry stream for EV1 taste shocks. Matching exact ages, initial subject rows and ordered discrete action domains share standardized draws across policies and regimes, independently of the ordinary seed, horizon endpoints, chunking and padding. Omitting the argument preserves the ordinary seeded behavior. Reordering or resizing a discrete action domain changes its stream.- Cached simulation key generation now follows changes to JAX's Threefry partition setting between calls, including when an executable has already been compiled.
SOLVER_API_VERSIONis 3. Every solver implementscapabilities, returning the frozenSolverExecutionCapabilitiesexported bylcm.solver_apiandlcm.solvers. Its structural requirements, execution axes and supported preference features drive the solver reference tables. Concrete model programs remain the authority for accepted execution widths. Custom plugins must implement this property and target API 3. Solver identities and model fingerprints change with this compatibility version; API 2 solution archives are not automatically migrated.- A core program declares what it publishes to another
program of the same kernel graph with
InternalOutputSpec, and a consumer names what it reads withInternalInputRef; both are published throughlcm.solvers. The engine lowers producers before consumers against the exact shapes, dtypes and weak typing the references select, so a consumer no longer runs against a stand-in filled in later. NEGM's keeper-to-sweep dependency uses the typed edge. - A program graph's typed internal edges lower for every admitted shape, not only for
a dense one-hop edge. A producer's abstract output is computed from the complete
invocation the engine lowers — its arguments, the internal inputs it reads itself,
and the widths the execution planner owns — so a chain of producers and a
PLANNEDproducer both reach their consumers. Weak typing is part of the template a consumer is lowered against, since equal shapes and dtypes can still promote differently in a consumer: a handed-over leaf whose weak typing departs from what the consumer was traced with is refused at dispatch, naming the program and the argument. A producer whose published output would change with the selected width — its weak typing included — is refused with anExecutionPlanningError. CoreExecutionDisposition.HOST_DRIVENdeclares a program whose host loop dispatches it a data-dependent number of times. LikeDENSEit owns its own width and must carry adisposition_reason; the engine plans nothing for it.- A compiled solve executable is keyed by program identity — the durable model
fingerprint, the regime name, the core name, the engine's per-period signature
(
SolutionPhase.period_signatures), and the solver's own period group key (SolutionKernels.period_group_keys) — instead of the identity of a Python callable. Equivalent programs built separately within one solve share one executable, and a solver whose published group key is coarser than what it actually specialized is refused at build time with anExecutionPlanningErrornaming both colliding programs. - The value-transfer catalogue names one operator for every stored/required layout pair
the planner produces:
ALIGNED_LOCAL,COPY_TO_SOURCE_LAYOUT,ALL_GATHER,LOCAL_SLICE,RESHARD, andCROSS_MESH_COPY. Two device meshes that share devices while neither contains the other are the one pair no single collective serves, and are refused while the period is planned with anExecutionPlanningErrornaming both device sets. - A published continuation answers questions about itself.
ContinuationReaderis the protocol a parent queries —value_at,marginal_atin a named state, andleaves()for the payload's addressable arrays — andContinuationCapabilitiesis the payload's own statement of what it can answer. A parent declares what it needs inSolver.required_continuation_capabilities; every endogenous-grid solver demands the value and the marginal inEGM_ENDOGENOUS_COORDINATE, and the shippedEGMCarrypublishes both. A reachable target whose payload is not a reader, or whose reader answers less than the parent asks, is refused while the model builds. - A dense EGM-family core declares the continuation leaves it reads instead of being
pinned conservatively against every reachable value. Which leaves exist is a fact
about the target's published template, so a solver names them in the new
Solver.declare_continuation_reads, which the engine calls once per continuation-reading regime after every regime is built, withSolverBuildContext.continuation_specsfilled. The default declares nothing; the hook may only attachvalue_readsto the programs the kernels already publish, so no kernel is built twice. Only the returned container'speriod_kernelsare honoured, and a hook that moves any other field, or that declares reads for a regime whose continuation the engine publishes on the solver's behalf, is refused at model build. - The engine's gated-edge fold declares the same-period values it reads. Folding one edge at one period is a dispatch in its own right, so the target's value and each reference regime's value are counted consumers rather than values pinned wholesale because nobody had named them.
- Solution archives written under solver API version 1 are rejected with
IncompatibleSolutionError. Compatibility remains exact; pylcm does not migrate an archive across a solver API version. - Backward induction releases every cross-period input after its final consumer and
donates sole-consumer inputs a program names in
donation_candidates; the donation set is part of the compilation key. Regime values are never released. Underlog_level="debug"every release and donation is logged with the artifact key and the closing dispatch. - On several devices every regime is placed on a submesh before compilation: a distributed state of extent three solves on three of four devices, single-device regimes fill idle devices, and independent regimes of a period dispatch concurrently. Two placements of one model publish values that name the same real number — each partition is vectorized at its own width, so they agree to within a few units in the last place rather than bit for bit. One device or one regime per period is placed as before.
- A streaming width fits when its compiler-reported peak plus accounted external
residency fits
ExecutionConfig.device_memory_bytes. Retained owners and compiler-eliminated operands remain in residency; only the overlapping spans of actual compiler-kept inputs are excluded to avoid counting them twice. Fixed model inputs and scheduled transfer copies are included conservatively.
- Pass
ExecutionConfigtoModel(...)to select devices, sharded states, execution widths and a per-device memory budget for both phases. Grids describe economic support; theirbatch_sizeanddistributedconstructor arguments and the corresponding solver execution knobs are removed. Explicitaxis_widthsnames the actual compiled program axes; a flattened state-cell width is not a per-state grid width. Execution policy does not enter the durable model fingerprint. - With a budget, solve planning compiles candidates along a deterministic widest-first
frontier and selects the first whose compiler peak plus accounted residency fits.
Without a budget, streamed solve axes use their bootstrap widths unless an explicit
width is supplied: a reduced axis, whose block is purely temporary, is capped at 64;
a tiled output axis, whose tiles concatenate into a full-size resident result, is
capped at up to 1024, the cap shrinking so the product of an unbudgeted candidate's
widths stays bounded regardless of model size. An omitted width requests planning,
and zero is not a full-width sentinel in
axis_widths. - Budgeted solves wait for earlier compiled work before dispatching another core whose execution or transfer devices overlap. Completion retains auxiliary outputs and copy witnesses through validation and error cleanup, and runs before eligible buffers are deleted or donated. Work with disjoint complete device footprints may remain asynchronous. This does not bound compiler autotuning or unprofiled host allocations.
- Configure subject chunks with
ExecutionConfig(axis_widths={"subject": width});Model.simulate(subject_batch_size=...)is removed. Device alignment can increase the outer chunk extent while preserving the requested inner width. With a budget and no fixed subject width, complete chunk profiles include retained results, numerical programs, RNG, diagnostics, padding and assembly. Chunk boundaries preserve each original subject's random stream. The constructorn_subjectshint and its duplicate concrete-template prewarm route are removed; call-shape runtime executors are cached instead, keyed on subject shape, so the firstsimulate()call at a given shape compiles it and later calls at that shape reuse it. - Solve candidate preparation uses shape and layout descriptors instead of allocating transfer copies for each width. Budgeted foreign eager solution values use compiled copy admission and retain intermediate copies through validation. Native archive materialization, artifact copies and mixed-backend foreign copies remain unsupported under a budget.
- Budgeted simulation accepts built-in native GridSearch value archives, admitting verified uploads and both private copies while retaining the archive cache. Actual source devices on the execution backend participate in residency and transfer-scratch accounting even when they are outside the selected execution subset.
- Simulation programs whose inputs are all removed by the compiler still run on their selected devices, preserving inferred scalar and vector output layouts.
- Eager solve inputs now bind weakly typed values to matching declared strong types, preserving compiled type promotion and their actual device layout. Shape and dtype mismatches remain errors; normalization copies are shared within each call and released with that call.
- Eager solve cores place ordinary inputs on their planned submesh before executing the numerical body, including bodies that create constant outputs. Repeated inputs share a placement when their complete descriptors match. Equivalent runtime layouts are accepted without changing declared transfer or compilation identities. Declared producer outputs reach subsequent eager cores with their actual validated layouts.
- Solve operand profiling uses a shared descriptor callable, allowing model disposal to release every per-program nested function.
- Finite NNBEGM simulation admits its declared candidate preparation, dropped-candidate diagnostics and canonical ranking under the chunk budget. The full candidate bank remains owned and counted through ranking, with addressed policy transfers shared across both programs.
- Supplied solutions on regime submeshes are accepted by simulation. Forward programs and profiled allocation operations recheck current retained inputs and growing results at dispatch. Unprofiled eager or host-driven programs fail visibly under a budget. These checks do not yet bound every allocation across the whole call or memory used during compilation.
- Period captures record the selected tile widths, so
replay_periodand the compiler-memory analyzer lower exactly the executable the solve dispatched. - The ASV GPU-memory series for the ACA baseline and Mahler–Yum rows are split into
three independently measured phases — automatic solve+simulate,
ALL_PERSISTABLE_ARTIFACTSsolve+save, and load+supplied-solution simulate — each in a fresh, phase-isolated child process with exact provenance. The combined timing/CPU subprocess no longer reports a GPU peak.
- The envelope's comparison arithmetic is selectable:
MSSEnvelope(arithmetic=...)takes"certified", the default, or"ordinary". The geometry is the same either way — which stored piece covers an interval, which node owns a query, and where two branches hand over — so both settle a knot at the root of the pieces covering it, and only the comparison changes. The certified arithmetic decides on the stored operands, so an ordering the working format cannot separate is still settled and a comparison it cannot decide publishesNaN; it needs the installed exact-affine payload for the active backend, and a regime selecting it is refused at model construction when that payload is absent. The ordinary one compares two readings formed in the working format, each a slope and then an affine step rather than one correctly rounded value, so a reading carries no bound in representable steps: cancellation or a large common level can reverse an ordering the correctly rounded values would separate, and candidates whose readings coincide are separated by the declared tie order rather than by value. It reaches no native kernel, so it is the route available where that payload is absent; it trades certified decisions for warm cost, and its values, owners and crossings are the caller's to validate for the intended model. - Which link owns a query is certified rather than read off a rounded comparison: every link bracketing that query enters one exact reduction through the integer comparator the other envelope paths already use. Links certified level with one another are separated right-continuously — the link reaching strictly right of the query, then the steeper one, then the earlier stored link — so a node where two branches meet is owned by the branch that owns the interval above it, and a switch decided by a single representable step is published at the node the geometry puts it at rather than lost.
- A query whose owner the exact comparator leaves undecided publishes no value: the
envelope reads
NaNthere instead of falling back to a rounded comparison, so an ordering the arithmetic cannot settle is visible rather than silently chosen. - Which links compete for a query is decided by their stored spans alone, never by whether reading one of them succeeded numerically. A model whose grids and values sit near the top or bottom of the working format keeps the owner it should have: the reading of the selected owner is range-safe, so an intermediate product that leaves the representable range no longer removes a finite winner from the contest.
- A link's value at a query is its own chord's value: the certified reader forms the exact rational through the two stored endpoints and rounds it once to the working format, without weighted floating products. The reading is the stored value at either endpoint exactly and elsewhere does not carry the cancellation of a line extrapolated from one far anchor. The published value and policy at a node always come from one owner.
- Ownership, support, orientation and node identity are decided from each link's original stored coordinates. A link stored as a single point keeps its own abscissa as its support instead of acquiring a readable width to the right, so a point and a segment that read the same value at a query are separated by the declared right-continuous order rather than by whichever carries the wider line. A readable surrogate is still used to read a channel, but never to decide who owns the query.
- Two abscissae name one published node exactly when they are the same geometric location, decided on the stored encodings: the two spellings of zero are one location, while distinct values closer together than the smallest normal remain distinct. The same rule orders, orients, admits and coalesces, so no two of those can disagree about whether two coordinates coincide.
- A crossing is constructed from the pieces that cover the interval the switch was
observed in, not from whichever piece owns each of its two nodes. A branch entered at
the right node is often represented there by the piece continuing above that node,
whose line says nothing about the interval below it; the piece covering both of the
interval's abscissae is the one the crossing is solved from, so a kink sits where the
branches actually meet rather than where a continuation extrapolated backwards would
meet them. Exact equality at the shared endpoint connects the selected piece to the
node it hands over at, and a trace that is missing, ambiguous, or disconnected from
that node publishes
NaNrather than a plausible abscissa. - The gap between those two pieces is signed only where both of them are supported, and its root is solved from the stored operands themselves, so a switch whose two rounded chord readings coincide is still placed at the abscissa the geometry puts it at instead of being collapsed onto an interval endpoint, and the policy read on each side of it belongs to the branch that owns that side. Its published value is the higher of the two chords there, so an emitted kink can never sit below both branches.
- A crossing landing exactly on one of the two query nodes is published rather than discarded. That node's own row is one of the two records the switch needs and the emission contributes the other: the incoming owner after a crossing at the left node, the outgoing owner before a crossing at the right node. Either way the kink abscissa carries exactly two rows, outgoing owner first.
- Whether a crossing lies on the envelope is settled by naming the owner at the crossing
abscissa and requiring it to carry the same value there as the piece the crossing was
built from, rather than by comparing two readings within a tolerance band. A shared
branch label is not provenance on its own, so the emission depends on neither a
declared band nor the working precision, and a crossing whose provenance the exact
comparator cannot certify is published as
NaNrather than admitted.
- Every function the engine defines is a module-level function or a frozen dataclass
with a
__call__, apart from the five sources named below; no other function definition runs inside another function per model build, per solve, per simulate, or per trace. pylcm's beartype claw decorates each function definition it sees and beartype memoizes every decorated function object for the life of the process, so a per-call definition pinned everything it closed over: grids, arrays, tracers, compiled kernels, whole models. Building and solving, then dropping, a model of any shipped solver family leaves no engine function behind outside those five, and a long session or test worker no longer grows with every model it builds. - Five sources still define a function per call, and the nested-function probe names
each of them as an exemption:
regime_building/max_Q_over_a.py,regime_building/collective.py,regime_building/processing.py,solution/negm.py, andsolution/nnbegm.py. The candidate certificate pins the reducer builders' bodies verbatim, nested definitions included, so their shape changes with that certificate or not at all; the remaining three are converted together with the execution work that rewrites the same call sites.
save_solution(solution=..., path=...)andSolutionResult.save(path=...)atomically persist a complete labelled solution.load_solution(path=...)restores independently lazy values and artifacts; each numerical leaf is checksummed together with its logical address, shape, and dtype. The versioned archive contains JSON metadata and numerical datasets only — no model, plugin class, callable, pickle, or executable code. The old bare-mapping writer signature is removed;load_legacy_solution(path=...)remains the explicit reader for old value-only HDF5 files.SolutionMetadatanow carries a durable mathematical model fingerprint plus exact solver, replay-route, artifact, solution-schema, and archive-format identities. A restored result can replay in a separately constructed compatible model process; an in-memory result retains its additional same-instance guard. Compatibility is exact, and incompatible versions fail clearly rather than migrating implicitly.- Persistence is selected per model-built artifact authority. Static or otherwise
independently model-verifiable artifacts are saved, while a present artifact whose
authority declares
NOT_PERSISTEDbecomes an explicit omission in the restored result. The adaptive NNBEGM policy carries its solve-generated outer nodes as the candidate axis of its descriptor, so it is model-verifiable and persists: a consuming model admits the nodes after checking that they are exact finite floats, strictly increasing, within the search's node budget and inside the outer state's domain for that period. - Solver diagnostics are persisted. Each retained
SolverDiagnosticspayload is described by a model-verifiable descriptor the solve generates from the payload itself; a consuming model admits the descriptor only when it names exactly the published fields with the dtypes they carry, and a restored archive reads its diagnostics without a model. A diagnostic omission without a descriptor is refused on both save and load. The solution-format version is 2. - A result restored by
load_solutioncan be saved again without a model. Its payloads are re-read from the archive they came from and verified against their checksums and descriptors before they are written to the new archive. - A
SolutionResultis consumed according to its provenance. A result the same model instance solved for the same canonical parameters is read by reference, so a simulate following a solve copies and re-validates nothing; every other result — restored, unpickled, or from another instance — is validated in full and materialized once per consuming model and parameter vector, and later simulations from it reuse that view. The consumed result stays reachable asSimulationResult.solutionuntil the simulation result is saved. - A model is sealed when it is built.
Model(...)records every global and closure binding its declared callables read; rebinding one afterwards makessolve()andsimulate()refuse withModelSealErrornaming the binding, and a model whose callables cannot be fingerprinted is refused at build withModelInitializationError. - Every external solver declares how its decision is replayed.
SolutionKernelscarriesreplay_route, which is anExecutableReplayRoute,DeclaredReplay.GRID_RECOMPUTATION(the shipped argmax over the declared action grids), orDeclaredReplay.UNSUPPORTED(the model solves but refuses to simulate, naming the regime and solver). A solver outside the shipped set that leaves the route unset is refused at model build.DeclaredReplayis exported fromlcm.solvers. ValueRead,ValueArtifactAddress,ValueArtifactKind,ValueConsumerAddress, andValueInputChannelare public throughlcm.solvers, so a core program that reads next-period stored values can declare each access;SolverBuildContext.solution_reachability.targets(period=..., source=...)names the targets to declare.- Retention now selects computation per exact artifact address. Replay alternatives and
additive artifact programs declare
CoreProgram.retained_artifact_keys; DCEGM, NB-EGM, NNBEGM, and external solvers avoid assembling outputs that the selected retention will discard. ValueStoreandArtifactStoreexpose per-entryLoadState. Metadata, omissions, coordinates, and whole-archive checksum verification do not materialize payloads; value-only inspection therefore does not load replay banks.ValueStore,ArtifactStore, and theomissionsofSolutionResultadmit a public mapping through one item traversal and check every raw address before inserting it: a Boolean period alias (Truefor1) is refused rather than merged into the exact integer coordinate, a repeated logical address is refused rather than contracted, and a mapping's key view is never consulted, so flat and nested forms are recognized from the items alone.- The durable model fingerprint and the canonical-parameter digest hash every referenced array with its original rank and shape; a scalar array and a length-one vector with the same bytes are distinct identities, while memory order does not enter the digest. The model-fingerprint record version is 6.
- The model fingerprint is split at the boundary no parameter vector crosses.
fingerprint_model_structuredigests what a model fixes at build — topology, names, identities, artifact descriptors, per-period state axes, and the declared callables' semantics — andfingerprint_modelcombines that digest with the concrete grid support and canonical solution parameters read from the parameter vector. AModelhashes its structure once and reuses it, so an estimation loop no longer walks every declared user callable per solve; the walk had been the largest single cost of a warm solve, ahead of the solve itself. - A model function may read an array constant's
shape,size,ndimordtypeand still be fingerprintable. Those four are functions of the array the digest already covers, so binding them adds no state the fingerprint misses. The array's own descriptor is what earns the exemption rather than the attribute name, and the bound value must be the metadata it claims to be, so asizeproperty on a type that is not an array still fails closed. - The durable model fingerprint sees through beartype guards that a downstream package's own claw wraps around its model functions: such a guard is accepted only when beartype regenerates its code from the bound callee with the guard's own configuration, and the callee is what enters the identity.
SolutionResult.save()flushes the archive through a writable handle before the atomic rename, so publication also succeeds on platforms that refuse to flush a read-only one.- A result nobody references any more releases its arrays. The store constructors and the artifact plan walkers keep their working state in explicit arguments rather than in per-call closures: pylcm's beartype claw decorates every function definition, including one executed inside a call, and beartype memoizes each decorated function object for the rest of the process, so a per-call closure would pin the value entries or artifact leaves it closed over long after the result was dropped.
- External solvers can declare an
ExecutableReplayRoutewith durable plugin and route identities, period-specific artifact requirements, model-built artifact authorities, a mathematical preflight, and a JAX-transformable reader returning namedActionOutput. The engine canonicalizes required restored or caller-supplied entries once and passes the same immutable snapshot through validation, reader construction, and forward execution. - An in-repository out-of-tree reference solver imports only public modules. It exercises a planner-owned program, a non-EGM continuation, a persistable plugin-defined replay PyTree, explicit non-persisted artifacts, lazy restoration into a freshly constructed model, custom replay, and fail-closed rejection of invalid artifacts.
- An omission names the artifact its solver declared.
SolutionResult.omissionsis enumerated from the model's own artifact authority, so a solver that publishes its own continuation key sees that key at its own cell under every retention, and no key the model never declared appears. - A continuation published under a key its payload does not claim is refused where the producing regime and period are still known, naming both the publication key and the payload's own.
- Every shipped period kernel — plain EGM, DC-EGM, NEGM, NB-EGM, NNBEGM (finite and
adaptive), grid search, and the engine's terminal-carry wrapper — publishes a native
core-program graph and returns a
KernelOutput. The centralized legacy adapter is gone, and with itrequire_legacy_kernel_result,normalize_kernel_output,KernelResult, theUNPLANNEDlayout, and the post-hoc repair that moved a kernel's published value onto its template's placement. A value now lands in its declared placement or the solve fails. - NEGM's outer sweep over the durable margin is one compiled program driven by
jax.lax.maprather than a Python chunk loop, withouter_batch_sizeselecting the block width. Solved values are invariant to that width to within a few units in the last place; the support of the compiled DC-EGM adjuster at float32 is not, because each width is a separate XLA kernel, so support identity is asserted under float64 only. - NB-EGM reads its continuation once per branch equivalence class rather than once per discrete action, and a solve retaining only values never compiles or lowers the replay program.
- A solver can be written against
lcm.solvers,lcm.solver_api,lcm.typingandlcm.gridsalone. Those modules now export the execution-contract types a solver constructs (CoreProgram,CoreBuildContext,CoreExecutionRequirements,CoreExecutionDisposition,ProgramScope,StreamableProductAxis,ReductionSemantics,OutputRole,StateAxesLeading,PeriodKernel,StateActionSpace), the continuation types and helpers (ContinuationSpec,EGMContinuationSpec,EGMContinuationLayout,ContinuationArtifact,period_to_continuation_target,target_period_grid,union_free_params,union_fixed_params), the parameter aliases (FlatParams,FlatRegimeParams,EconFunction,EconFunctionsMapping), andContinuousGrid. The exact-version persistence, replay, and conformance contract is documented in Custom solvers. Solver.requires_continuationis replaced bySolver.required_continuation_keys, a frozenset ofArtifactKey. Model building matches every declared key against what each reachable target publishes and refuses the model, naming both regimes and the demanded version, before anything compiles.- The rolling continuation channel is keyed rather than concrete. A period kernel may
publish any payload satisfying the
ContinuationArtifactprotocol under its own versioned key, and the engine stores and rolls it without reading its fields. - Every regime declares one replay route,
SimulationPhase.replay_route, carrying aReplayModeofEXACT_REPLAY,VALID_RECOMPUTATION, orUNSUPPORTED, the exact payload class it retains, and the reader that consumes it. External routes now supply their own model-verifiable authorities, preflight validator, and JAX-transformable reader. Forward simulation dispatches on that declaration instead of on the class of whatever payload a solve happened to keep.
- A regime carrying ride-along co-states solves each period in one tile-local
NBEGMcore: every cell block's transition-aware continuation read (the complete expectation over reachable targets and stochastic nodes, on the savings grid) is consumed by that block's envelope solve inside the same compiled body, so the expected-continuation stacks over every cell are never a complete array and never a core argument. The period kernel publishes a native two-program graph with planned outputs:mainfor a values-only solve (the value array and the carry) andreplayfor a solve retaining replay artifacts (adding the consumption policy and the conditional branch banks). A direct scalar oracle in the test suite, independent of the production expectation and envelope code, replaces the split continuation and envelope cores; the compile-only fused replay experiment is replaced by a per-period core memory analyzer that lowers the production programs.
- Simulation reads a gated edge's gate references and leg fallbacks only in the periods
where that edge's target is active. A regime declaring two edges whose targets are
active over disjoint age windows no longer fails with a
KeyErrorfor a fallback regime the landing period never solved (#434). The per-period reference set is recorded on the canonical regime's simulation phase, and both the ahead-of-time lowering and the runtime call consult it.
Model.solve()returns aSolutionResultand is the only public solve entry point.solve_result(), mapping and tuple returns,return_simulation_policy, andreturn_dissolution_flagsare removed;simulate(solution=...)consumes the complete result, and omittingsolutionsolves automatically. The result carries values, replay artifacts, metadata, and explicit omission reasons, and the model that produced it authenticates every value and replay cell on simulation.- One native
CoreProgramgraph perGridSearchperiod kernel is the sole authority for each core's function, argument builder, execution requirements, value reads, output roles, execution disposition, and reason. Eager, JIT, ahead-of-time, liveness, output-layout, and period-replay paths resolve the same graph through one seam; unmigrated endogenous-grid kernels cross one fail-closed legacy adapter. A kernel publishing both a native graph and a legacy declaration is rejected at build. - Streamed action reduction is planned per program with an explicit disposition and
reason. Singleton expected-value (EV1) reductions and collective hard-max reductions
stay dense by disposition: blockwise grouping changes the canonical floating-point
reduction order, and the collective streamed row regressed every measured resource
surface. The transition ledger in
docs/development/architecture_transition_ledger.mdrecords each remaining bridge with its retirement condition. - The fp32/fp64 candidate certificate binds the native graph: seals, AST hashes, and 354 synchronized mutations cover duplicate authority, wrapped or rebound functions and builders, erased requirements, roles, and reasons, forced dispositions, and eager/AOT/replay bypasses.
- The backward-induction diagnostics fold combines per-period scalars across value arrays with different device placements: a planned single-device layout is committed, and a mesh-sharded neighbour is moved onto the running flag's placement before it is combined.
- A gated edge into a stateless target is gated in solve: the source's continuation applies the gate and the leg fallbacks to the target's folded channel stack, so a closed gate pays the projected fallback. Previously the dense action reduction silently reduced over the channel axis and the source always paid the target's own value.
ConsumptionSavingsRegimeandNestedConsumptionSavingsRegimedeclare the DAG roles the endogenous-grid solvers need — the liquid state, consumption action, resources node, and post-decision node, plus an outer continuous margin for the nested form — while retaining an arbitrary regime function DAG.EGM,DCEGM, andNEGMcarry numerical configuration only and read their role names from the regime that binds them, so an endogenous-grid solver on a plainRegimeis rejected at construction.RegimewithGridSearchis unchanged.- Every solver now participates in model-stage and build-stage validation through the
common solver contract. Plain
EGMrejects constraints, discrete/process axes, incompatible terminal targets, and a post-decision function that is not resources minus the continuous action before solving. - DC-EGM semantic validation is independent of native exact-kernel presence. Exact-backend capability is checked only after the regime satisfies the model contract; exact-only tests declare that requirement explicitly, and CI records their node IDs and skip reasons on kernel-less platforms.
- Cross-regime endogenous-grid continuation calls preserve target-regime parameter identity for both runtime and fixed parameters.
- Upper-envelope selection uses typed backend configurations (
ExactEnvelope,FUESEnvelope,RFCEnvelope,LTMEnvelope, andMSSEnvelope). Selecting the exact backend requires a loadable native kernel during model construction. - EGM continuation templates and their static layouts are bundled in one
EGMContinuationSpec, and GridSearch/terminal carries are published only for reachable targets that have an incoming endogenous-grid consumer. - Simulation-policy host copies and retention are demand-driven. When an off-grid policy replacement is accepted, the reported value is the canonical value attained by that same emitted action.
- NEGM locates its durable carry axis by name rather than declaration order and checks utility separability through the complete composed utility DAG.
- Negative Euler targets fail loudly, numerical marginal-utility inversion expands its initial bracket, and ordinary one-dimensional continuation reads use nearest-segment extrapolation outside support.
-
The marginal a brute (
GridSearch) child publishes to an endogenous-grid parent is one-sided next to a feasibility boundary. A central difference straddling an infeasible state said nothing, so the first feasible state above a borrowing constraint carried a zero marginal and biased the parent's Euler inversion toward over-consumption there. -
A constraint reading an auto-named
next_<state>(the NEGM budget cut on the next durable stock) no longer breakssimulate(). The initial-conditions feasibility check, its per-constraint diagnostic, and the additional-target pool now resolve that name the way the within-period decision does. -
envelope="mss": a value decrease no larger than rounding noise is no longer read as a branch boundary. Along a near-linear tail the sign of the difference between consecutive candidate values is set by rounding, and splitting there silently dropped the top of the published row. A candidate whose value is not finite now costs only its own nodes instead of poisoning every node it covers with NaN. -
envelope="exact": a handover between two links the pair's arithmetic cannot separate is refused rather than placed at a fabricated abscissa. -
An endogenous-grid regime reads its continuation on the grid the target regime tabulates at period
t+1, not on its own period-tgrid. The two differ whenever the target is a different regime whose grid differs, or whenever anAgeSpecializedGridmoves the nodes with age; before, such a model either raised on the length mismatch or published values inverted against the wrong abscissae. A target that does not carry the state now raises instead of falling back. -
EGMandTwoAssetEGMvalidate their regime when the model is built: the number of continuous states, the declared roles, and — for the two-asset solver — the retirement boundary target. The errors name the regime's own state names and the field that fixes them.
-
EGMreads the two quantities the Euler inversion needs — where a level of savings lands next period, and how that landing point moves when savings move — off the regime's own transition, composed through the post-decision node and differentiated there. It previously rebuilt(1 + r) * savings + incomefrom two parameters resolved by name, so every term the modeller declared outside that form was silently discarded and the solver published a policy for a model its user had not written. A per-period fixed cost, a means test, or a balance-dependent return now reaches the inversion like any other term. -
Breaking:
return_paramandincome_paramare gone.EGMtakespost_decision_function=in their place, naming the function inRegime.functionsthat computes the end-of-period balance the liquid state's transition is written through. A model that renames every parameter in its laws now solves with no solver-side declaration at all. -
Breaking: the borrowing corner is the savings grid's lower bound rather than zero, so a household allowed to borrow is no longer solved as one that is not. A grid starting at zero reproduces the previous arithmetic exactly.
-
Two laws are now refused instead of solved wrongly. A law reaching a state or action other than through the post-decision node is not a function of savings, so neither reading exists; it is named at model build rather than failing deep inside
dags. A law whose landing points do not ascend strictly with savings breaks the interpolation back onto the regular grid, which returns quietly wrong numbers rather than raising — a falling law is now told it falls, a flat one that it is flat.
-
The endogenous-grid solvers are named by the problem they solve rather than by the dimension count they were built around:
OneAssetEGMis nowEGMandTwoDimEGMis nowTwoAssetEGM. There are no aliases. -
TwoAssetEGMtakes the regime's two continuous states by name —liquid_state=andpension_state=— instead of requiring them to be spelledliquidandpension. -
The refinement argument is
envelope=on bothTwoAssetEGMandDCEGM(wasupper_envelope=). The_lcm/egm/upper_envelope/package keeps its name: it is the FUES backend, not the field.
- There is no
metal/tests-metalpixi environment: macOS runs on CPU, and Apple-Silicon GPU acceleration is not installable from this project.
-
Phased(solve=..., simulate=...)gives any regime-slot value a per-phase variant; a bare value broadcasts to both phases. Carried states —Phased(solve=callable, simulate=Grid)instates— are derived functions during backward induction and genuine seeded-and-evolved states in simulation. See the phase grammar explanation. -
fixed_transition(state_name)marks a fixed state (identity law) instate_transitions. TheNonespelling for fixed states is removed; a regime-levelNonenow masks a model-level entry instead. -
Regime transitions take a third form: a per-target dict
{target_regime: StochasticTransition(func=prob_func)}whose key set declares the regime's reachable targets — omitted regimes are structurally unreachable. Per-target dicts instate_transitionshand state values across regime boundaries, including into states the source regime does not carry and across grids that differ between regimes. -
A bare callable or bare
StochasticTransitiononRegime.transitiondeclares conservative support over every regime active in the next period, so every temporally compatible candidate must have a valid state handoff (a carried state, a deterministic/stochastic law, or an explicit target-local/entry law). Use a per-target mapping to declare narrower support instead. Runtime transition probabilities of zero do not narrow this topology — only the declared form does. -
Model-level regime slots:
Model(functions=..., constraints=..., states=..., state_transitions=..., actions=...)declares shared structure once and merges it into every regime under the exactly-one-level rule. Broadcast states and actions are pruned per regime by DAG reachability;model.pruned_variablesrecords the result. -
model.user_regimesholds plainlcm.regime.Regimeinstances, finalized at model build (model-level slots merged, the model-level Koopmans aggregator and certainty equivalent injected into non-terminal regimes, completeness validated).
-
Per-target transition parameters nest under the target regime's name in the params template —
template[regime][target][func][param]— replacing theto_<target>_…spelling. Param qnames parallel engine function qnames. -
Parameters resolve at four levels, most to least specific: target / function (one value broadcasts over the law's targets) / regime / model. Exactly one level per parameter; multi-level specifications are ambiguity errors.
-
Canonical flat params always key transition-law params per target, every target of a broadcast value sharing one leaf object. A coarse regime transition is evaluated once and shared, so it takes no per-target parameters.
-
Model-level
derived_categoricalsfollow the exactly-one-level rule of the other model-level slots: a name declared at model level and regime level is an ambiguity error, also when the grids match.
-
A continuous stochastic process may condition its
sigmaon a discrete regime state viasigma=StateConditioned(on="<discrete state>", by={<category>: sigma}). The declaration stands where the scalar would, so which parameter is conditioned is explicit and there is no way to give that parameter twice.Every category shares one set of nodes, placed from the widest value in
by— the narrowest axis that still covers all of them. The per-category values move no nodes; each row is evaluated directly at the from-value with the value for the time-$t$ category, with no precomputed-row interpolation. This expresses regime-switching income risk and stochastic volatility.Supported for the CDF-binned
NormalIIDProcess(gauss_hermite=False) andTauchenAR1Process, whose transition probabilities carrysigma. Gauss-Hermite node placement and Rouwenhorst are refused when the model is built, their fixed-node kernels having no channel to carry it. Abywhose values are not all finite and positive is refused at construction.Solving and simulating use the same conditioned law. Every grid parameter must be fixed at construction, and the conditioning state must map its categories to the same integer codes in every regime that carries it. Current-regime conditioning only. See
lcm_examples/stochastic_volatility.py.
-
A simulated agent prices its continuation under the law it believes, while the world it moves through follows the law that is true.
Phasedstate transitions acceptStochasticTransitionlaws, so perceived mortality, perceived health or income risk, and misread policy rules are expressible: give thesolvevariant the agent's beliefs and thesimulatevariant the data-generating process. See the phase-grammar explanation in the docs.The simulated state-action value is assembled from two halves. Today's payoff and feasible set — period utility, constraints, the Koopmans aggregator — come from the simulate phase, because they are known when the action is chosen. The continuation — next-period kernels, regime-transition probabilities, and every helper they read — comes from the solve phase, because the future is only perceived and the value function was solved under those beliefs. The realized draw is unchanged and still follows the simulate laws.
The two phases need not agree on whether a law is stochastic: a deterministic law is a degenerate kernel, so an agent may perceive risk where there is none, or treat as certain a transition that is not.
Constraints must be phase-invariant through their whole dependency chain. A constraint that reaches a
Phasedhelper or law of motion is rejected when the model is built, because a phase-specific feasible set would let the simulated agent choose actions its value function was never computed for.Behaviour change. A model's numbers are unchanged unless a
Phasedfunction lies in the dependency ancestry of a continuation transition, or of anext_<state>read by period utility or feasibility. The solve phase is untouched, and for every phase-invariant name both phases hold the same function. Models that do have such a dependency change by design: the helper was resolved from the wrong phase. That pattern was reachable before this release through aPhasedhelper under a phase-invariant law, so the correction can move published results.Both variants of a
Phasedstochastic law are validated numerically; before, only one of them was. A per-target dict insidePhasedmust be per-target in both phases and cover the same targets.
-
Adds the DC-EGM solver (Iskhakov, Jørgensen, Rust & Schjerning 2017) as a per-regime alternative to grid search:
Regime(solver=lcm.DCEGM(...)). Euler-equation inversion on an exogenous savings grid with a fast upper-envelope scan (Dobrescu & Shanker 2022) — no consumption grid enters the solve, and the credit-constrained segment is exact. Requires declaredresources, post-decision, andinverse_marginal_utilityregime functions; the model contract is validated atModelconstruction. Supports discrete states and actions, EV1 taste shocks, stochastic processes, and passive continuous states. Forward simulation works with grid-restricted consumption (the intrinsic budget constraint is applied as a feasibility mask). -
Adds regime-level EV1 taste shocks as a model property:
Regime(taste_shocks=lcm.ExtremeValueTasteShocks())with the scale as the runtime param{"taste_shocks": {"scale": ...}}. The solve aggregates discrete actions by the smoothed expected maximum and simulation draws the discrete action by Gumbel-max — identical solutions under either solver. -
Promotes the Iskhakov et al. (2017) retirement model to
lcm_examples.iskhakov_et_al_2017(brute-force and DC-EGM variants) with an explanation notebook comparing the two solvers.
-
First public release of PyLCM.
-
Includes core functionality:
-
Specification of finite-horizon discrete-continuous choice models with an arbitrary number of discrete and continuous states and actions.
-
Linearly and Log-linearly spaced grids that approximate continuous states and actions.
-
Linear interpolation and extrapolation of the value function for continuous states.
-
Grid search (brute-force) for finding the optimal continuous policy.
-
Stochastic state transitions for discrete states which may depend on other discrete states and actions.
-
-
Built with contributions from the PyLCM team.
Thanks to everyone who contributed to this release:
-
{ghuser}
hmgaudeckerInitiated and drove the development agenda for PyLCM, ensuring strategic direction and alignment. He actively steered the project, facilitated collaboration, and secured funding to support core development. Additionally, he reviewed pull requests and provided feedback on the internal and external code structure and design.
-
{ghuser}
janosgDesigned and implemented the initial prototype of PyLCM, laying the foundation for its development. He onboarded {ghuser}
timmensand played a key role in shaping the project's direction. After stepping back from active development, he contributed to implementation discussions and later provided guidance on architectural decisions. -
{ghuser}
timmensTook over development of PyLCM, expanding its functionality with key features like the simulation function, extrapolation capabilities, and special arguments. He led extensive refactoring to improve code clarity, maintainability, and testability, making the package easier to develop and extend. His contributions also include improved documentation, type annotations, static type checking, and the introduction of example and explanation notebooks.
-
{ghuser}
mj023Analyzed and optimized PyLCM's performance on the GPU, profiling execution and examining the computational graph of JAX-compiled functions. He fine-tuned the
solvefunction's just-in-time compilation to reduce runtime and improve efficiency. Additionally, he compared PyLCM's performance against similar libraries, providing insights into its computational efficiency. -
{ghuser}
mo2561057Added tests for the model processing and fully discrete models.
-
{ghuser}
MImmesbergerAdded checks to test PyLCM's results against analytical solutions.
-
{ghuser}
segsell -
{ghuser}
ChristianZimpelmann -
{ghuser}
tobiasraabe