2.12.1. The properties

endo_list

endo_list - list of endogenous

exo_list

exo_list - list of exogenous

par_list

par_list - list of parameters

def_list

def_list - list of definitions

start_date

start_date - last date of history

end_date

end_date - last date of simulation

InitialRegime

InitialRegime - Initial regime for forecasting

DynamicConstraints

DynamicConstraints - constraint,shocks,date,page

ConditionMatrix

ConditionMatrix - 3D matrix for simulation conditions

partitions

simplan/partitions is a property.

simul_periods

simplan/simul_periods is a property.

variable_list

simplan/variable_list is a property.

2.12.2. The methods

append

append - Add conditioning restrictions to a simplan object.

Syntax:

obj = append(obj, vname, date, value)
obj = append(obj, vname, date, value, page)
obj = append(obj, {vname, date, value})
obj = append(obj, {vname, date, value, page})
obj = append(obj, C)
obj = append(obj, S, date)
obj = append(obj, S, date, page)

Description:

Adds conditioning restrictions to a simplan object. A restriction pins a variable to a target value at one or more dates, optionally at a specific anticipation page (shock horizon lead).

Restrictions can target:

• A single endogenous or exogenous variable by name.

• An algebraic constraint paired with a fixing shock.

• Multiple variables at once via a struct or cell array.

append can be called multiple times. Each call adds to the existing restrictions without removing previous ones. If the same variable-date-page combination is set twice, the later call wins.

Inputs:

- obj   : Existing simplan object.

- vname : Variable name or constraint specification. One of:

            string    Name of an endogenous or exogenous variable,
                      e.g. 'inflation'. Must be in variable_list.

            1x2 cell  Algebraic constraint paired with a fixing
                      shock: {constraint, fixingShock}, where
                      constraint is a string expression such as
                      'Inflation{t} + Output = 0' and fixingShock
                      is the name of the shock enforcing it.

- date  : Date or vector of dates at which the restriction applies.
          Must be within [start_date, end_date]. Dates must be of
          the same type as the simplan horizon (numeric or RISE).

- value : Target value(s) for the restriction. Must be real numeric.
          Compatibility with date:
            scalar  + scalar date   -> one entry
            scalar  + vector dates  -> value replicated across dates
            vector  + vector dates  -> paired element-wise;
                                       lengths must match
            vector  + scalar date   -> error (ambiguous)

- page  : (Optional) Anticipation lead + 1. Positive integer.
            page 1 = shock is unanticipated (hits at date)
            page k = shock is known k-1 periods ahead of date
          Defaults to 1 (unanticipated) if not provided.
          Maximum page is determined by the model's shock_horizon.

- C     : Cell array where each row is one restriction. Accepts:
            {vname, date, value}         3-column, page defaults to 1
            {vname, date, value, page}   4-column
          Rows can mix variable names and algebraic constraints.

- S     : Struct with variable names as fields and numeric scalar
          or vector values. All fields must have the same number of
          values. Unrecognized fields trigger a warning and are
          ignored. Combined with a date argument:
            append(obj, S, date)        page defaults to 1
            append(obj, S, date, page)  explicit page

Outputs:

- obj : Updated simplan object with the appended restrictions.

Examples:

% Pin inflation to 2% at a single date
sp = append(sp, 'inflation', rq(2021,1), 0.02);

% Pin output to 1.0 across a range of dates
sp = append(sp, 'output', rq(2021,1):rq(2021,4), 1.0);

% Anticipated shock: ea is known 2 periods ahead
sp = append(sp, 'ea', rq(2022,1), 0.1, 3);

% Multiple variables via cell array
C = {'inflation', rq(2021,1), 0.02;
     'output',    rq(2021,1), 1.00};
sp = append(sp, C);

% Multiple variables via struct
S.inflation = 0.02;
S.output    = 1.00;
sp = append(sp, S, rq(2021,1));

% Struct with vector values across multiple dates
S.inflation = [0.02; 0.02; 0.03; 0.03];
S.output    = [1.0;  1.1;  1.2;  1.3];
sp = append(sp, S, rq(2021,1):rq(2021,4));

% Algebraic constraint enforced by shock EC
sp = append(sp, {'Inflation{t} + Output = 0', 'EC'}, rq(2021,1), NaN);

See also

simplan, export, query, initval, endval, histval

details

details - Display the raw property structure of a simplan object.

Syntax:

details(obj)

Description:

Displays the full internal property listing of the simplan object using MATLAB’s built-in display, bypassing the overloaded disp. Useful for debugging or inspecting internal state such as ConditionMatrix, DynamicConstraints, initval, endval, and histval directly.

Notes:

• Equivalent to calling builtin(‘disp’, obj).

• For a human-readable summary, use disp instead.

• For querying specific variable values, use query.

Example:

details(sp) % shows raw property dump disp(sp) % shows formatted summary

See also

disp, query, simplan

disp

disp - Display a readable summary of a simplan object.

Syntax:

disp(obj)

Description:

Prints a structured, human-readable summary of the simplan object to the console. The summary includes:

• Simulation horizon (start and end dates, number of periods)

• Initial regime

• Status of initval, endval, and histval blocks (if set)

• All conditioned endogenous variables with their non-NaN date-value pairs, grouped by variable

• All conditioned exogenous variables with their non-NaN date-value pairs, grouped by variable and anticipation page

• Dynamic (algebraic) constraints with their associated shocks, dates, and pages

Only non-NaN entries are shown. Variables with no conditioning (all NaN) are omitted.

Called automatically by MATLAB when disp(obj) is invoked, or indirectly via display when an expression is evaluated without a semicolon.

Notes:

• To see the raw property structure, use details(obj).

• To query specific variables interactively, use query.

See also

details, query, simplan

endval

endval : Overloads/emulates Dynare’s endval for the simplan class

Syntax:

obj = endval(obj, steady, C)

Description:

The endval method overloads/emulates Dynare’s endval for the simplan class. It sets initial conditions for simulation periods, considering the presence of steady state calculations and historical values.

Input:

• obj: The simplan object.

• steady: A logical flag indicating whether steady state calculations should be performed. If true, the provided initial conditions (C) will be used to calculate the steady state, resulting in an updated C.

• C: Initial conditions, start values and terminal conditions. For the syntax, see the help for initval.

  • In the absence of any other block, (the possibly updated) C provides initial conditions, terminal conditions and start values for perfect-foresight optimization.

  • In the presence of an initval block and/or a histval block, (the possibly updated) C provides terminal conditions and start values for perfect-foresight optimization.

Output:

• obj: Updated simplan object with initialized conditions.

Example:

sp = simplan(model, date_range, 1); sp = initval(sp, true, init_conditions);

Notes:

• The endval method dominates initval in that it overrides the terminal conditions and the initial values for perfect-foresight optimization

See also

• simplan

export

export - Compile conditioning information for simulation.

Syntax:

[histdb, np]                = export(obj, dsgemodel)
[histdb, np, ss]            = export(obj, dsgemodel)
[histdb, np, ss, partitions] = export(obj, dsgemodel)

Description:

Compiles the conditioning information stored in a simplan object into outputs suitable for perfect-foresight simulation or conditional forecasting in RISE.

The compilation resolves the following in order:

1. initval block (if set) — provides initial conditions and, in the absence of endval, terminal conditions and start values.

2. endval block (if set) — overrides terminal conditions and start values from initval.

3. histval block (if set) — overrides initial conditions from both initval and endval.

4. Explicit restrictions added via append.

If steady=true was passed to initval or endval, the steady state is recomputed subject to the provided values before compilation.

Inputs:

- obj       : simplan object containing all conditioning information.
- dsgemodel : RISE DSGE model object. Required when initval or
              endval was called with steady=true, in which case
              `export` calls `sstate` to recompute the steady state.
              For steady=false workflows, dsgemodel is still required
              but sstate is not called.

Outputs:

- histdb : ts (time series) object covering [start_date, end_date].
           Contains the compiled conditioning values for all
           endogenous and exogenous variables. NaN entries indicate
           unconstrained variable-date combinations.

- np     : Number of simulation periods. Equal to simul_periods,
           i.e. numel(start_date:end_date) - 1.

- ss     : Struct of start values for endogenous variables, or []
           if neither initval nor endval was set. Fields are
           variable names; values are the corresponding start values
           used to initialize the perfect-foresight solver.
           Exogenous variables are excluded from ss.

- partitions : Struct describing the layout of histdb and the
               extent of conditioning. Fields:

               .endogenous  : column indices of endogenous variables
                              in ConditionMatrix.
               .exogenous   : column indices of exogenous variables
                              in ConditionMatrix.
               .regime      : column index of the regime variable.
               .constrained_periods : struct with fields:
                   .endogenous : vector (n_periods x 1); entry k is
                                 the number of pages on which at
                                 least one endogenous variable is
                                 constrained at period k.
                   .exogenous  : same for exogenous variables.
                   .regime     : same for the regime variable.

Notes:

• export does not modify the simplan object.

• The order of precedence for overlapping conditions is: histval > endval > initval > append.

• Dynamic (algebraic) constraints stored in DynamicConstraints are not included in histdb — they are handled separately by the solver.

Examples:

% Basic export
[histdb, np] = export(sp, m);

% Full output
[histdb, np, ss, partitions] = export(sp, m);

% Check how many periods have endogenous constraints
[~,~,~,p] = export(sp, m);
disp(p.constrained_periods.endogenous)

See also

simplan, append, initval, endval, histval

histval

histval : Overloads/emulates Dynare’s histval for the simplan class

Syntax:

obj = histval(obj, C)

Description:

The histval method overloads/emulates Dynare’s histval for the simplan class. It sets the historical values (initial conditions) for the perfect-foresight simulations.

Input:

• obj: The simplan object.

• C: historical values to be set. The syntax is as follows:

  Example 1:
  
  C = {
       'y(0)', 1
       'k(-1)', 12
       'm{0}', 0.5
       'x{-1}', 1
      };
  
  Example 2:
  
  C = {
       'y(0)=1;'
       'k(t-1)=12;'
       'm{0}=0.5;'
       'x{t-1}=1;'
       };
  
  Example 3:
  
  C = 'y(0)=1; k(-1)=12; m{0}=0.5; x{-1}=1;';
  

Output:

• obj: Updated simplan object with initialized conditions.

Example:

sp = simplan(model, date_range, 1); sp = initval(sp, true, init_conditions);

Notes:

• The histval method dominates both initval and endval

See also

• simplan

initval

initval : Overloads/emulates Dynare’s initval for the simplan class

Syntax:

obj = initval(obj, steady, C)

Description:

The initval method overloads/emulates Dynare’s initval for the simplan class. It sets initial conditions for simulation periods, considering the presence of steady state calculations and historical values.

Input:

• obj: The simplan object.

• steady: A logical flag indicating whether steady state calculations should be performed. If true, the provided initial conditions (C) will be used to calculate the steady state, resulting in an updated C.

• C: Initial conditions, start values and terminal conditions. It can be provided as a cell array with variable-value pairs, or as a cell array with expressions for each variable:

  Example 1:
  C = {
       'y', 1
       'k', 12
       'm', 0.5
       'x', 1
      };
  Example 2:
  C = {
       'y=1;'
       'k=12;'
       'm=0.5;'
       'x=1;'
      };
  Example 3:
  C = 'y=1; k=12; m=0.5; x=1;';
  

  • In the absence of any other block, (the possibly updated) C provides Initial conditions, terminal conditions and start values for perfect-foresight optimization.

  • In the presence of a histval block, (the possibly updated) C provides, terminal conditions and start values for perfect-foresight optimization.

  • In the presence of a endval block, (the possibly updated) C provides only initial conditions.

Output:

• obj: Updated simplan object with initialized conditions.

Example:

sp = simplan(model, date_range, 1); sp = initval(sp, true, init_conditions);

Notes:

• The initval method cannot be called twice.

See also

• simplan

query

query - Query conditioning values from a simplan object.

Syntax:

[values, dates, pages] = query(obj, vname) [values, dates, pages] = query(obj, vname, target_dates) [values, dates, pages] = query(obj, vname, target_dates, target_pages)

Description:

Retrieves conditioning values stored in a simplan object for a given variable, optionally filtered by date and anticipation page. Only non-NaN entries are returned. Results are also printed to the console in a formatted table.

Anticipation pages:

page 1 = shock is unanticipated (hits at the specified date) page k = shock is known k-1 periods ahead of the specified date

Inputs:

• obj : simplan object.

• vnameName of the variable to query. Must be in

  variable_list (endogenous, exogenous, or ‘regime’).

• target_dates(Optional) Date or vector of dates to query.

  Must be within [start_date, end_date] and of the same type as the simplan horizon. Defaults to all dates in the simulation horizon.

• target_pages(Optional) Scalar or vector of anticipation pages

  to query. Must be positive integers within [1, shock_horizon+1]. Defaults to all pages.

Outputs:

• valuesNumeric matrix of size (n_active_dates x n_active_pages).

  Contains only rows and columns with at least one non-NaN entry. NaN entries within the retained rows/columns are shown as ‘—’ in the printed table.

• datesVector of dates corresponding to rows of values.

  Same type as simplan horizon (numeric or RISE date).

• pages : Vector of page indices corresponding to columns of values.

If no conditioned values are found, all outputs are empty ([]) and a warning (‘simplan:query’) is issued.

Notes:

• query prints a formatted table to the console on every call. The printed output cannot be suppressed — capture outputs and redirect if console output is unwanted.

• query does not distinguish between values set explicitly via append and values set implicitly by steady-state initialization. To inspect only explicitly set values, use append selectively and query the specific dates of interest.

Examples:

% Query all conditioned dates for inflation [v, d, p] = query(sp, ‘inflation’);

% Query inflation at specific dates [v, d, p] = query(sp, ‘inflation’, rq(2021,1):rq(2021,4));

% Query shock ea at anticipation page 2 (known 1 period ahead) [v, d, p] = query(sp, ‘ea’, rq(2022,1), 2);

% Query across multiple pages [v, d, p] = query(sp, ‘ea’, [], 1:3);

See also

simplan, append, disp

simplan

simplan - Simulation and forecasting plan for DSGE models.

Syntax:

obj = simplan(m, horizon, initialRegime) obj = simplan(m, horizon, initialRegime, ‘shockInit’, spec) obj = simplan(m, horizon, initialRegime, ‘shockInit’, spec, C) obj = simplan(m, horizon, initialRegime, C)

Description:

Creates a simulation/forecasting plan for a DSGE model. The plan stores conditioning information — fixed values for endogenous and exogenous variables at specific dates and anticipation horizons — that is later compiled by export for use in perfect-foresight simulation or conditional forecasting.

If the model has not been solved, simplan solves it automatically before constructing the plan.

Inputs:

• mRISE DSGE model object. Solved or unsolved — if

  unsolved, simplan calls solve internally.

• horizon1x2 vector [start_date, end_date] defining the

  simulation horizon. start_date is the last date of history; end_date is the last date of simulation. Must satisfy start_date < end_date.

• initialRegimePositive integer selecting the initial regime for

  regime-switching models. For single-regime models, pass 1 or []. Required for multi-regime models.

Optional Name-Value Inputs:

• ‘shockInit’Controls how exogenous variables are initialized

  in the ConditionMatrix. Accepted values:

  [] Legacy behavior — shocks initialized

  to their steady-state values. This is the default when ‘shockInit’ is not provided.

  ‘zero’ All shocks set to zero across all

  periods and anticipation pages.

  ‘randn’ All shocks drawn independently from

  N(0,1). Reproducibility is the caller’s responsibility via rng.

  scalar All shocks set to the given numeric

  value, e.g. ‘shockInit’, 0.01.

  struct Per-shock control. Each field name

  must match a variable in exo_list. Field values can be ‘zero’, ‘randn’, or a numeric scalar. Shocks not mentioned default to zero.

  Example: spec = struct(‘ea’,’randn’,’eb’,0);

Optional Positional Inputs:

• CInitial conditioning information passed directly

  to append. Accepts all formats supported by append: 3- or 4-column cell array, or triplet (vname, date, value). See append for details.

Outputs:

• obj : Initialized simplan object.

Notes:

• The ConditionMatrix is a 3D array of size:

  (n_periods) x (n_endo + n_exo + 1) x (shock_horizon + 1)

  where the third dimension corresponds to anticipation pages:

  page 1 = unanticipated shock (hits at date) page k = shock known k-1 periods ahead

• Endogenous variables are initialized to their steady-state values.

• The regime column is initialized to 1 for single-regime models.

• For multi-regime models, the regime column is left as NaN until set explicitly via append.

Examples:

% Basic plan with numeric dates sp = simplan(m, [1, 40], 1);

% Plan with RISE dates sp = simplan(m, [rq(1990,1), rq(2000,4)], 1);

% Initialize all shocks from N(0,1) rng(42) sp = simplan(m, [1, 40], 1, ‘shockInit’, ‘randn’);

% Per-shock initialization spec = struct(‘ea’, ‘randn’, ‘eb’, 0); sp = simplan(m, [1, 40], 1, ‘shockInit’, spec);

% Initialize with immediate conditioning sp = simplan(m, [1, 40], 1, ‘y’, 5, 1.5);

See also

append, export, initval, endval, histval, query