choice.RustNFP

Guide & worked example · Source

choice.RustNFP(
    n_states,
    n_choices,
    discount_factor,
    transition_type='nonparametric',
    optimizer=torch.optim.LBFGS,
    maxiter=1000,
    tol=1e-06,
    device=None,
    estimate_transitions=False,
)

Rust (1987) full maximum likelihood via nested fixed point (NFP).

Attributes

Name	Description
device
discount_factor
estimate_transitions
history
maxiter
n_choices
n_states
optimizer_class
params
tol
transition_matrix
transition_params
transition_type
utility_fn
utility_params

Methods

Name	Description
counterfactual	Re-solve and simulate altered utilities without mutating fitted state.
fit	Fit the model to the data.
predict_proba	Structural/equilibrium probabilities using fitted utility coefficients.
set_flow_utility	Specify per-period utility ū(x, a; θ).
set_transition_probabilities	Specify state transition mechanism P(x_{t+1} | x_t, a_t).
simulate	Simulate paths under fitted utility and transition probabilities.
solve_value_functions	Solve value function fixed point via successive approximations.
summary	Print a formatted summary of model estimation results.
to	Move model and transition matrix to specified device.

counterfactual

choice.RustNFP.counterfactual(data, policy_change, rng=None, *, n_periods=None)

Re-solve and simulate altered utilities without mutating fitted state.

Starts with each individual’s earliest observation. Default horizon is the largest number of observed periods per individual, not max(time ID). Pass n_periods explicitly for unbalanced-panel policy simulations.

fit

choice.RustNFP.fit(data, init_params=None, verbose=False)

Fit the model to the data. Overriden to handle DynamicChoiceData.

predict_proba

choice.RustNFP.predict_proba(states)

Structural/equilibrium probabilities using fitted utility coefficients.

For Hotz-Miller this re-solves the Bellman equation; it does not return the empirical first-stage CCPs or freeze them under policy changes.

set_flow_utility

choice.RustNFP.set_flow_utility(utility_fn, utility_params=None)

Specify per-period utility ū(x, a; θ).

Args: utility_fn: Function computing u(x, a; θ) utility_params: Initial values for θ

set_transition_probabilities

choice.RustNFP.set_transition_probabilities(
    transition_matrix,
    transition_params=None,
)

Specify state transition mechanism P(x_{t+1} | x_t, a_t).

Args: transition_matrix: (n_states, n_choices, n_states) tensor P[x, a, x’] = Pr(x_{t+1}=x’ | x_t=x, a_t=a) transition_params: Parameters φ if transitions are parametric

Raises: ValueError: If transition matrix shape is incorrect

simulate

choice.RustNFP.simulate(initial_states, n_periods, rng=None)

Simulate paths under fitted utility and transition probabilities.

Parameters

Name	Type	Description	Default
initial_states	tensor of shape (n_individuals,)	Integer state indices at the start of the simulation.	required
n_periods	int	Number of decisions per individual.	required
rng	torch.Generator	Random generator matching the model’s device; not a NumPy RNG.	None

Returns

Name	Type	Description
	tuple of torch.Tensor	State paths with shape (n_individuals, n_periods + 1) and action paths with shape (n_individuals, n_periods).

solve_value_functions

choice.RustNFP.solve_value_functions(flow_utility, tol=1e-08, max_iter=10000)

Solve value function fixed point via successive approximations.

Iterates: v̄^{k+1} = T(v̄^k) until convergence, where T is the Bellman operator.

Args: flow_utility: (n_states, n_choices) per-period utilities ū(x,a) tol: Convergence tolerance for sup-norm max_iter: Maximum iterations

Returns: v_bar: (n_states, n_choices) converged value functions

Raises: RuntimeError: If iteration does not converge

summary

choice.RustNFP.summary(alpha=0.05)

Print a formatted summary of model estimation results.

Displays a comprehensive table including parameter estimates, standard errors, t-statistics, p-values, and confidence intervals (if standard errors are available).

Args: alpha: Significance level for confidence intervals (default: 0.05 for 95% confidence intervals).

Examples: >>> model.fit(X, y) >>> model.summary(alpha=0.01) # 99% confidence intervals

to

choice.RustNFP.to(device)

Move model and transition matrix to specified device.