Solvers and capabilities

All solver-related names live under lcm.solvers:

from lcm.solvers import DCEGM, EGM, GridSearch, NBEGM, NEGM, NNBEGM

A solver object contains numerical configuration. Specialized economic roles are declared on the regime.

Regime pairing¶

Collective regimes and transition-local JointTransition lotteries currently require GridSearch. EV1 taste shocks are supported by GridSearch and DCEGM; NEGM, NBEGM, and NNBEGM reject them. Model construction validates the concrete solver’s remaining prerequisites.

Capability table¶

Nonlinear certainty equivalents¶

NBEGM and NNBEGM implement the recursive Euler equation through the NBEGM inner kernel. Here, a ride-along route means that the continuation varies over at least one supported non-liquid state; the single-liquid NBEGM route remains additive and rejects a nonlinear certainty equivalent. This capability does not waive their budget, state-layout, taste-shock, or smoothness restrictions. See Preference aggregation and certainty equivalents before choosing the solver.

A valid declaration is part of the model, not a hint. Start with Authoring for EGM-family solvers.

Constructors¶

GridSearch¶

GridSearch()

Covers the complete represented state-action product and applies constraints directly. It is the broadest route and the default solver on Regime. Eligible JIT solve-value routes evaluate bounded C-order action blocks while preserving the complete support. This matrix uses exactly three disposition labels:

JIT solve route matrix¶

The streamed rows assume JIT execution, a nontrivial action product, and no applicable unsupported composition. When several rows describe one route, an unsupported composition takes precedence, followed by a deliberately dense condition; only the remaining eligible route is streamed.

Here, unsupported is a disposition of the action-streamed solve program, not a new public solver capability verdict. Model validation may reject the corresponding declaration; where the declaration is otherwise valid, the existing dense GridSearch core remains the compatibility path. Streamed programs publish only solve-time VALUE, or VALUE plus DISSOLUTION_FLAG for a collective route; replay and policy artifacts are not integrated. Runtime and peak-memory effects require measurement; bounded action evaluation alone is not a performance claim.

For planned GridSearch solve cores, a continuation or reference declaration identifies both the stored target artifact and the exact channel and tree path at which the source core consumes it. Planning resolves each read either as a local pass-through that keeps the value’s stored partitioning on the shared source mesh, or as an explicit copy into a supported layout on the source core’s mesh. The resolved plan is applied identically to lowering and runtime arguments, and unsupported layout conversions or mismatched array metadata are errors. Each declaration’s (source_regime, source_period, core_key) must also match the actual compiled core before its channel and argument-tree path are resolved. Remaining-consumer counts are committed only after successful dispatch. A zero count records eligibility for future memory planning; it does not release, donate, or offload an array. Dense programs without declared value reads and other unplanned consumers remain pinned.

With EV1 taste shocks, GridSearch first maximizes over the continuous-action axes within each discrete-action combination and then applies the discrete log-sum. Simulation uses the corresponding Gumbel-max choice rule. See ExtremeValueTasteShocks for the complete feature boundary.

EGM¶

EGM(savings_grid=...)

Plain one-margin EGM. It validates the exact cash-on-hand identity summarized in the capability table and takes no upper envelope.

DCEGM¶

from lcm.solvers import DCEGM, LTMEnvelope

solver = DCEGM(
    savings_grid=...,
    envelope=LTMEnvelope(),
    refined_grid_factor=2.0,
    n_constrained_points=20,
    stochastic_node_batch_size=0,
)

DCEGM does not require a nontrivial discrete choice: it is also the supported route for a smooth liquid problem whose genuine resources node, passive states, or stochastic processes make plain EGM ineligible.

The supported typed envelope configurations are ExactEnvelope, FUESEnvelope, RFCEnvelope, LTMEnvelope, and MSSEnvelope. String selectors are not part of the public API. See Upper envelopes for their distinct contracts.

refined_grid_factor provides NaN-padded storage headroom for ownership changes in each envelope row. A row that needs more slots is reported as overflow and NaN-poisoned; this field does not change the density of the policy read-out grid. n_constrained_points controls the borrowing-corner segment, and stochastic_node_batch_size the stochastic-node workspace.

NEGM¶

NEGM(inner=..., outer_grid=..., outer_batch_size=0)

Runs the bound DCEGM inner solve for every finite outer-grid node and includes the keeper. outer_batch_size limits how many candidate values are evaluated at once. It can reduce temporary evaluation memory, but it does not in general cap the size of the candidate bank retained for later envelope or ordered-fold operations. Peak memory can therefore continue to grow with the full candidate set. Measure both temporary and retained arrays for the exact model and solver profile.

NEGM rejects EV1 taste shocks. Its outer durable-margin maximum currently wraps the inner DCEGM solve, but a taste-shocked discrete choice must be the outermost aggregation: max_outer logsumexp_discrete is not logsumexp_discrete max_outer. Use GridSearch, or remove the taste shocks when the NEGM structure is required.

NBEGM¶

NBEGM(
    savings_grid=...,
    jump_read="one_sided",
    stochastic_node_batch_size=0,
    envelope_segment_block_size=0,
    envelope_arithmetic="certified",
    interval_batch_size=0,
    cell_block_size=0,
    branch_batch_size=0,
    probe_failure="reject",
)

jump_read selects topology-preserving one-sided continuation reads or a faster bridged finite-grid read. probe_failure="assume_declared" turns an unexecutable structural probe into an author assertion and warning; it does not relax the mathematical prerequisite.

With envelope_arithmetic="certified", candidate ownership is ordered from the stored floating-point operands using fixed-width integer arithmetic. Exact affine value comes first, followed by deterministic geometric and stable-index tie-breaks. NaNs and other non-finite or invalid geometry are not ordinary ordered values: the query is rejected and remains uncovered/NaN so runtime validation can surface it. "ordinary" compares in the working floating format and requires model-specific validation near crossings.

Native capability. "certified" uses pylcm’s installed exact-affine CPU/CUDA payload; it is not a pure-JAX numerical option. A compatible payload must exist for the active JAX backend. NBEGM never silently falls back: if the payload is absent or unloadable, certified mode raises ExactAffineKernelUnavailableError before returning a certified result. Select envelope_arithmetic="ordinary" only when working-format ownership is acceptable under model-specific crossing checks. The same requirement applies when this NBEGM is the inner solver of NNBEGM.

The memory controls do not all mean “compiled batch width”:

• stochastic_node_batch_size and envelope_segment_block_size stream their named intermediate axes;

• interval_batch_size streams the continuation read and the candidate-envelope fold together. A positive width reads only that many interval rows, folds their candidates into one standing winner per query, then requests the next block. The standing winner retains its global stored-link index, so given the candidate records every partition decides ownership by the same total order over the same identities as the one-shot layout, under both envelope arithmetics: no width can hand a query to another candidate by where a record happens to be stored, and the step reports the owner of every node on request (return_owner=True) so a partition test asserts it exactly. What a width does change is the compiled vmap width the records are produced at, and the backend vectorizes each one differently: the published levels agree to within a few units in the last place rather than bit for bit, and two candidates whose reads tie to within that spacing are ordered by the records each width produced. The one place this is visible on a regular grid is a node where a savings-node point candidate coincides with an interior candidate: the two are the same point, and which of them is named the owner can differ between widths while the published level does not. interval_batch_size=0 keeps the one-shot continuation matrix and envelope reduction;

• cell_block_size and branch_batch_size are compiled lax.map batch widths for the ride-cell and discrete-branch axes. The continuation read behind the branch axis runs once per class of branches that agree on every discrete action reaching the continuation (the regime transition, a law of motion, stochastic-state transition weights, a child’s resources, the discount factor, or a schedule variable), so a budget-only action costs one read per cell however many branches it declares;

• lower positive values bound the named streamed or mapped width. For the map-width controls, 0 or a value covering the axis selects one vectorized pass.

These fields bound only their named mapped work, not surrounding arrays or total memory.

NNBEGM¶

NNBEGM(inner=..., outer_search=...)

Nests an NBEGM liquid solve inside a configurable outer search. The inner solver must use a bridged carry compatible with the outer fold. See Outer search and branch aggregation.

The nested period kernel publishes no traced body of its own: its core-program graph republishes the inner NB-EGM programs as keeper:main, keeper:replay, adjuster:main, and adjuster:replay, each with the inner program’s output roles, scope, and planned disposition. The keeper programs are built from the period’s own inputs; the adjuster programs bind the outer post-decision at the first outer node, the same shape every per-node call rebinds. A values-only solve dispatches the inner main programs and the nested collapse publishes the value and the carry alone; a replay-retaining solve dispatches the inner replay programs and assembles the nested policy from their banks.

How the keeper and adjuster branches combine is an economic declaration, not a solver setting: it lives on OuterContinuousMargin.adjustment_cost.

With FiniteOuterGrid, NNBEGM replays the keeper-plus-outer-grid candidates ranked during the solve; with AdaptiveOuterMesh it republishes the mesh policies and the search settings, and re-refines per subject at that subject’s own resources. The adaptive replay reads the exact generated mesh, whose nodes the result carries as the candidate axis of the policy’s descriptor, so both the adaptive policy and the finite candidate bank are self-contained, retained under every replay-retaining ResultRetention, and persist in the complete archive. Every declaration that can affect that replay must therefore be phase-invariant by object identity: a bare declaration and Phased(solve=f, simulate=f) are accepted, while distinct solve/simulate functions, state or regime transitions, Koopmans aggregators, and carried-only states are rejected during Model(...) construction. Use identical declaration objects, remove the carried-only state, or use GridSearch until phase-specific NNBEGM replay is implemented. In the Phased spelling, f must be the exact same callable object in both fields; two distinct functions that compute the same formula still count as phase variation.

NNBEGM searches the outer margin over post-decision targets — the outer stock a candidate reaches — so simulation recovers the outer action that reached a stored target by inverting the declared post-decision map. That inversion is exact or refused, never approximate, so the map must be affine in the outer action with a constant coefficient that is exactly a power of two, positive or negative:

• accepted: new = old + action, new = old + 2 * action, new = old + 0.5 * action, and new = offset(states, params) + action for an arbitrarily nonlinear offset. Anything the action does not enter is unrestricted, so depreciation, returns, and fixed transfers are all free.

• refused: a non-affine dependence — action ** 2, exp(action), clip(action, ...), jnp.where(action > 0, ...), or division by the action.

• refused: a coefficient of zero, i.e. a map the action does not enter. Such a map retains no information about the action that reached the target, so none can be recovered.

• refused: a constant but non-dyadic slope. 3, 1.5, and 0.9 all fail.

• refused: a state-dependent slope, such as old + (1 + 0.1 * old) * action.

Recovery divides the coefficient out of the retained target, and binary division is exact only by a power of two. Any other factor rounds, and a rounded action reassembles a stock away from the node the solve ranked — at the edge of the outer state’s declared grid, or off the declared domain entirely, where there is no value function to read. Each refusal is a RegimeInitializationError raised where the map is declared, rather than a candidate dropped silently during the solve.

The restriction excludes any state-dependent conversion technology: a scale economy in durable investment, a portfolio-size-dependent transaction cost, increasing-returns installation — any adjustment cost that does not separate into a state-only offset plus a dyadic multiple of the action. That is a modelling restriction, not a formatting one. A constant non-dyadic price is usually recoverable by choosing units so the action is the stock increment itself and moving the conversion factor into the budget’s cost term, which the inversion never reads. A state-dependent slope has no single coefficient to divide out, so it is not recoverable that way. Both solve under GridSearch, which searches the outer action directly and so never inverts it.

Capability is validated, not inferred from class names¶

The selected solver inspects finalized declarations before numerical lowering. A model that violates its state/action count, budget form, constraint route, continuation layout, shock, or boundary assumptions fails during Model(...) or the first parameter-dependent validation. There is no supported “try EGM and see whether it runs” workflow.

Start with Choosing a solver. The mathematical map is Solver families.