Core Containers

@dataclass(frozen=True)
class MCStep(
    name: str,
    op_type: OpType,
    func: Callable[..., Any],
    kwargs: Mapping[str, Any] = {},
    store_key: str | None = None,
    step_type: str | None = None,
)

MCStep describes one operation in the pipeline. Most users should create steps through the factories under SymbolicDSGE.monte_carlo.operations.

Fields:

Name	Type	Description
name	str	Unique step name. Test steps use this as the key in MCPipelineResult.test_summaries.
op_type	OpType	Operation type: DATAGEN, TRANSFORM, FILTER, TEST, REGRESSION, or POSTPROC.
func	Callable	Callable executed by the pipeline.
kwargs	Mapping[str, Any]	Keyword arguments stored with the step and passed into func.
store_key	str | None	Optional payload key. If omitted, name is used.
step_type	str | None	Serializable step kind stamped by the factory, for example "wald", "simulation", "standardize", or "custom". None is reserved for hand-built steps that cannot be projected to a PipelineSpec.

Factory groups

Step factories are organized by operation group:

• SymbolicDSGE.monte_carlo.operations.core
• SymbolicDSGE.monte_carlo.operations.tests
• SymbolicDSGE.monte_carlo.operations.regressions
• SymbolicDSGE.monte_carlo.operations.transforms

 

@dataclass(frozen=True)
class MCData(
    states: ndarray | None = None,
    observables: ndarray | None = None,
    n_exog: int = -1,
    raw: Mapping[str, ndarray] = {},
    observable_names: tuple[str, ...] = (),
)

MCData is the standard per-replication data payload. State-only and observable-only payloads are supported, but downstream steps may require one or the other.

Fields:

Name	Type	Description
states	ndarray | None	Simulated or supplied state matrix.
observables	ndarray | None	Simulated or supplied observable matrix.
n_exog	int	Number of exogenous shocks when known.
raw	Mapping[str, ndarray]	Additional raw arrays, usually from SolvedModel.sim(...).
observable_names	tuple[str, ...]	Observable column names used by the reference filter when explicit names are not supplied.

 

@dataclass(frozen=True)
class DataGenReturn(
    state_mat: ndarray | None,
    obs_mat: ndarray | None,
    n_exog: int,
)

Legacy simulation-data container kept for compatibility.

 

@dataclass
class MCContext(
    rep_idx: int,
    reference: SolvedModel,
    dgp: SolvedModel | None,
    data: MCData | None = None,
    payloads: dict[str, Any] = {},
    results: dict[str, TestResult] = {},
    regressions: dict[str, RegressionResult] = {},
)

MCContext is the mutable object passed through a single replication. Custom transform, filter, test, and post-processing operations receive it as context.

Methods:

Name	Description
require_data()	Return data or raise if no data-generation step has populated it.
require_payload(key)	Return a payload by key or raise if the key is missing.

 

@dataclass(frozen=True)
class MCFailure(
    rep_idx: int,
    step_name: str,
    error_type: str,
    message: str,
)

MCFailure records one collected replication failure when MCPipeline.run(..., fail_fast=False).

Fields:

Name	Type	Description
rep_idx	int	Replication index that failed.
step_name	str	Step executing when the failure occurred.
error_type	str	Exception type name.
message	str	Exception message.

 

@dataclass(frozen=True)
class MCPipelineResult(
    n_rep: int,
    n_successful: int,
    test_summaries: Mapping[str, MCResult],
    test_results: Mapping[str, tuple[TestResult, ...]] | None,
    payloads: tuple[Mapping[str, Any], ...] | None,
    contexts: tuple[MCContext, ...] | None,
    failures: tuple[MCFailure, ...] = (),
    regression_summaries: Mapping[str, MCRegressionResult] = {},
    elapsed_s: float = 0.0,
    step_elapsed_s: Mapping[str, float] = {},
    step_counts: Mapping[str, int] = {},
    step_failures: Mapping[str, int] = {},
)

MCPipelineResult is the aggregate return object from MCPipeline.run(...).

Fields and Properties:

Name	Type	Description
n_rep	int	Requested replication count.
n_successful	int	Number of completed replications.
test_summaries	Mapping[str, MCResult]	Per-test aggregate result containers.
test_results	Mapping[str, tuple[TestResult, ...]] | None	Optional scalar per-replication test results.
payloads	tuple[Mapping[str, Any], ...] | None	Optional per-replication payload dictionaries.
contexts	tuple[MCContext, ...] | None	Optional full contexts.
failures	tuple[MCFailure, ...]	Failures collected when fail_fast=False.
regression_summaries	Mapping[str, MCRegressionResult]	Per-regression aggregate result containers.
elapsed_s	float	Total elapsed wall time for the pipeline run.
step_elapsed_s	Mapping[str, float]	Elapsed wall time by step name.
step_counts	Mapping[str, int]	Number of attempted calls by step name.
step_failures	Mapping[str, int]	Number of collected failures by step name.
succeeded	bool	True when no failures were collected.
it_s	float	Replications attempted per elapsed second.
step_it_s	Mapping[str, float]	Step calls attempted per elapsed second by step name.
statistic_traces	Mapping[str, ndarray]	Shortcut for each test summary's statistic trace.
pval_traces	Mapping[str, ndarray]	Shortcut for each test summary's p-value trace.
test_status_traces	Mapping[str, tuple[TestStatus, ...]]	Shortcut for each test summary's status trace.
rejection_traces	Mapping[str, ndarray]	Boolean rejection trace for each test summary.
coefficient_traces	Mapping[str, ndarray]	Shortcut for each regression summary's coefficient trace.
regression_status_traces	Mapping[str, tuple[RegressionStatus, ...]]	Shortcut for each regression summary's status trace.
report_performance()	None	Print the aggregate pipeline throughput report.
report_step_performance()	None	Print one throughput report line per pipeline step.

P-Value Evaluation

Scalar TestResult objects produced inside Monte Carlo Wald steps defer p-value and frozen-distribution construction until pval, frozen_dist, or compute_pval() is accessed. Aggregate MCResult objects compute vectorized p-values when MCPipelineResult.test_summaries is built.