Return to PSG Models documentation page

SSASIM input table RUN

Contains highest level description of model runs, consisting mostly of foreign keys pointing to rows in child tables. Each row specifies a different run.

Parent table is: QUEUE

Child table is: OUTPUT

Child table is: ASSUMP

Child table is: POP

Child table is: LABMRKT

Child table is: PRDMRKT

Child table is: ESTAB

Child table is: CAPMRKT

Child table is: BEN_DI

Child table is: BEN_RI

Child table is: TAXEARN

Child table is: COVERED

Child table is: MTE

Child table is: TAX_DI

Child table is: TAX_RI

Child table is: FUND_DI

Child table is: FUND_RI

Child table is: FUND_RD

Child table is: ACCT

Child table is: OLC

Child table is: ESP

Child table is: RCS

Child table is: COHORT

Go to SSASIM input parameters overview

SSASIM:   RUN . id
Identifies run specified on this row of table, so id value should be unique.

Valid values: 1 to 99999 (five digits), Integer

Source code: run.h and run.cpp

SSASIM:   RUN . notes
Describes specification of table row in free-form note.

Valid values: any ASCII text (Note: do not copy and paste from a word processor because of the possibility of embedded non-ASCII characters.)

Source code: notes are not read by the model

SSASIM:   RUN . year_zero
Specifies year zero of simulation (that is, year prior to first simulation year), which is most recent year for which starting information is known.

Valid values: 2004 or 2008 or 2011, Integer

Source code: run.h and run.cpp

SSASIM:   RUN . num_years
Specifies number of years simulated following year_zero. IMPORTANT NOTE: In order to produce two stochastic runs with comparable random numbers, the value for RUN.num_years must be the same in the two runs, and also the value of RUN.scenarios must be the same in the two runs.

Valid values: 2 to 9999, Integer [(year_zero+num_years) must be no greater than 3068=(2934+125+9) but must be no less than (f_test_yr+n_test_yrs+1) when olc_mode=F (i.e., when macro model is operating in CBA mode) or must be no less than (f_test_yr+n_test_yrs+135) when olc_mode=T (i.e., when macro model is operating in OLC mode)]

Source code: run.h and run.cpp

SSASIM:   RUN . scenarios
Specifies total number of scenarios (each num_years long) to be simulated. IMPORTANT NOTE: In order to produce two stochastic runs with comparable random numbers, the value for RUN.num_years must be the same in the two runs, and also the value of RUN.scenarios must be the same in the two runs.

Valid values: 1 to 99999 (five digits), Integer [practical limit is about 10,000]

Source code: run.h and run.cpp

SSASIM:   RUN . output_id
Points to row in child OUTPUT table.

Valid values: 1 to 999999999 (nine digits), Integer

Source code: run.h and run.cpp

SSASIM:   RUN . assump_id
Points to row in child ASSUMP table.

Valid values: 1 to 999999999 (nine digits), Integer

Source code: run.h and run.cpp

SSASIM:   RUN . pop_id
Points to row in child POP table.

Valid values: 1 to 999999999 (nine digits), Integer

Source code: run.h and run.cpp

SSASIM:   RUN . labmrkt_id
Points to row in child LABMRKT table.

Valid values: 1 to 999999999 (nine digits), Integer

Source code: run.h and run.cpp

SSASIM:   RUN . prdmrkt_id
Points to row in child PRDMRKT table.

Valid values: 1 to 999999999 (nine digits), Integer

Source code: run.h and run.cpp

SSASIM:   RUN . estab_id
Points to row in child ESTAB table.

Valid values: 1 to 999999999 (nine digits), Integer

Source code: run.h and run.cpp

SSASIM:   RUN . capmrkt_id
Points to row in child CAPMRKT table.

Valid values: 1 to 999999999 (nine digits), Integer

Source code: run.h and run.cpp

SSASIM:   RUN . ben_di_id
Points to row in child BEN_DI table.

Valid values: 1 to 999999999 (nine digits), Integer

Source code: run.h and run.cpp

SSASIM:   RUN . ben_ri_id
Points to row in child BEN_RI table.

Valid values: 1 to 999999999 (nine digits), Integer

Source code: run.h and run.cpp

SSASIM:   RUN . paypctfile
Specifies file name of OASI and DI payable-benefits percent file that contains payable percentages for each simulation year during the actuarial test period in each scenario. When this field contains a single dot character, which is the parameter value for all the benchmark runs used a base runs in run specification files, a scheduled-benefits policy is simulated. When specifying a filename, a payable-benefits policy is implemented using the paypct values in the specified file. The format of the paypctfile is exactly like the format of the .pay output file, except for the fact that the column-headings row in the pay output file must be removed. There must be rows for each scenario specified by RUN.scenarios, and for each scenario there must a row for each year beginning with RUN.year_zero+1 through the actuarial test period, which ends in the calendar year RUN.f_test_yr+RUN.n_test_yrs+1. Also, the name of the paypctfile cannot look like an output file name, so the .pay output file needs to be renamed so that it does not begin with the characters runNNNNN (where NNNNN is the RUN.id with leading zeros).

Not specifying a paypctfile is equivalent to assuming a scheduled-benefits policy, which implies the paypct value is 100 for every year. Specifying a paypctfile is equivalent to assuming a payable-benefits policy, in which fewer benefits than authorized under policy will to be paid during any scenario year for which the paypct value is less than 100.

NOTE: To simulate a payable-benefits policy requires two runs. The first run produces a pay output file, while the second run uses that file (after renaming it and after deleting the first line with the column names) as input. Be sure the first run and the second run specify the same number of scenarios and the same number of simulation years.

Valid values: the paypctfile name may not be blank, cannot have any embedded spaces, and it cannot have a name like an output file.

SSASIM:   RUN . taxearn_id
Points to row in child TAXEARN table.

Valid values: 1 to 999999999 (nine digits), Integer

Source code: run.h and run.cpp

SSASIM:   RUN . covered_id
Points to a row in child COVERED table.

Valid values: 1 to 999999999, Integer

SSASIM:   RUN . mte_id
Points to row(s) in child MTE table.

Valid values: 1 to 999999999 (nine digits), Integer

Source code: run.h and run.cpp

SSASIM:   RUN . tax_di_id
Points to row in child TAX_DI table.

Valid values: 1 to 999999999 (nine digits), Integer

Source code: run.h and run.cpp

SSASIM:   RUN . tax_ri_id
Points to row in child TAX_RI table.

Valid values: 1 to 999999999 (nine digits), Integer

Source code: run.h and run.cpp

SSASIM:   RUN . fund_di_id
Points to row in child FUND_DI table.

Valid values: 1 to 999999999 (nine digits), Integer

Source code: run.h and run.cpp

SSASIM:   RUN . fund_ri_id
Points to row in child FUND_RI table.

Valid values: 1 to 999999999 (nine digits), Integer

Source code: run.h and run.cpp

SSASIM:   RUN . fund_rd_id
Points to row in child FUND_RD table.

Valid values: 1 to 999999999 (nine digits), Integer

Source code: run.h and run.cpp

SSASIM:   RUN . acct_id
Points to row in child ACCT table.

Valid values: 1 to 999999999 (nine digits), Integer

Source code: run.h and run.cpp

SSASIM:   RUN . f_test_yr
Specifies first calendar year in the actuarial test period used to calculate summarized cost and summarized income rates for the OASI and the DI programs. The difference between the summarized income and cost rates is the actuarial balance statistic, which is often used to describe the aggregate financial condition of the program.

Valid values: (year_zero+1) to 9999, Integer [(f_test_yr+n_test_yrs) must be less than (year_zero+num_years)]

Source code: read from table in run.cpp; used in ssa.h and ssa.cpp

SSASIM:   RUN . n_test_yrs
Specifies number of years in the actuarial test period used to calculate summarized cost and summarized income rates for the OASI and the DI programs. The convention in the Trustees' Report is to use 75 years. The difference between the summarized income and cost rates is the actuarial balance statistic, which is often used to describe the aggregate financial condition of the program.

Valid values: 1 to 999, Integer [(f_test_yr+n_test_yrs) must be less than (year_zero+num_years)]

Source code: read from table in run.cpp; used in ssa.h and ssa.cpp

SSASIM:   RUN . threads
Specifies number of processes to be used simultaneously to execute OLC, ESP, ESP+, and RCS mode runs. There is little advantage to setting threads greater than one unless you have a computer with multiple chips and/or multiple cores per chip. But if you have a multiple-core computer, setting threads equal to the number of available CPU cores will speed up the execution of all OLC mode runs and of multiple-scenario ESP, ESP+, and RCS mode runs. The exception to this rule is that multiple-scenario RCS mode runs that use the income tax module with imputations (that is, set the GEMINI input database parameter RUN.use_inctax=T and also set either RUN.iti_write=T or RUN.iti_read=T) act as if threads=1 regardless of the actual value of the threads parameter.

Valid values: 1 to 32, Integer

Source code: read from table in run.cpp; used in various files.

SSASIM:   RUN . dp_active
Specifies whether or not this run is a distributed-processing subrun that simulated the bundle of scenarios specified by the RUN.dp_f_scen and RUN.dp_l_scen fields (see below). When the parameter is false, the dp_f_scen and dp_l_scen fields are not read and the the internal model value of the distributed-processing first scenario is set to one and the internal model value of the distributed-processing last scenario is set to RUN.scenarios.

NOTE: a set of distributed-processing subrun specification files can be created from an rsf using the dp-split utility program from the Windows command prompt. The results of the subruns can be combined using the dp-merge utility program from the Windows command prompt.

NOTE: For those who are registered to use the AWS Toolkit, distributed-processing subruns can be created automatically using the 'Create subruns' item on the PSG menu of the AWS Toolkit, and the AWS Toolkit will automatically combine the subrun results after all subruns have finished execution on AWS computers.

Valid values: T (=1) or F (=0) (for true or false), Logical

Source code: read from table in run.cpp; used in olc.cpp.

SSASIM:   RUN . dp_f_scen
When using distributed-processing capability, specifies first scenario in the bundle of scenarios that is simulated in this subrun. This parameter is not read when RUN.dp_active is false.

Valid values: 1 to RUN.scenarios, Integer

Source code: read from table in run.cpp; used in various files.

SSASIM:   RUN . dp_l_scen
When using distributed-processing capability, specifies last scenario in the bundle of scenarios that is simulated in this subrun. This parameter is not read when RUN.dp_active is false.

Valid values: RUN.dp_f_scen to RUN.scenarios, Integer

Source code: read from table in run.cpp; used in various files.

SSASIM:   RUN . rng_offset
Specifies the number of random numbers to call when random number generators are initialized in the SSASIM model (both the CBA model of operation and the ECI mode of operation) and in the PENSIM and GEMINI runs that support the SSASIM model's OLC, ESP, and RCS modes of operation. If changing the value of this parameter produces substantial differences in the summary statistics generated by this run, then reduce the Monte Carlo sampling variability by (a) increasing the value of SSASIM:RUN.scenarios and/or (b) increasing the value of PENSIM:RUN.sample_pct (for ESP and RCS mode) or increasing the value of SSASIM:OLC.sample_pct (for OLC mode).

Valid values: 0 to 999, Integer

Source code: read from table in run.cpp; used in various files.

SSASIM:   RUN . olc_mode
Specifies whether the macro model operates in the overlapping cohorts (OLC) mode or in the cell-based actuarial (CBA) mode. Note that both the PENSIM add-on to SSASIM and the GEMINI add-on to SSASIM are required to use the OLC mode of operation. It is possible to use the OLC mode in a SSASIM run that uses either, both, or neither of the ESP and RCS modes of operation.

Valid values: T (=1) or F (=0) (for true or false), Logical

Source code: read from table in run.cpp; used in olc.cpp.

SSASIM:   RUN . olc_id
Points to row in child OLC table.

Valid values: 1 to 999999999 (nine digits), Integer

Source code: read from table in run.cpp; used in olc.cpp.

SSASIM:   RUN . esp_mode
Specifies whether the micro model operates in the employer-sponsored pension (ESP) mode rather than in the default exemplary cohort individuals (ECI) mode. Note that the PENSIM add-on to SSASIM is required to use the ESP mode. It is possible to use both the ESP and RCS modes in the same SSASIM run.

Valid values: T (=1) or F (=0) (for true or false), Logical

Source code: read from table in run.cpp; used in esp.cpp.

SSASIM:   RUN . esp_id
Points to row in child ESP table.

Valid values: 1 to 999999999 (nine digits), Integer

Source code: read from table in run.cpp; used in esp.cpp.

SSASIM:   RUN . rcs_mode
Specifies whether the micro model operates in the representative cohort sample (RCS) mode rather than in the default exemplary cohort individuals (ECI) mode. Note that both the PENSIM add-on to SSASIM and the GEMINI add-on to SSASIM are required to use the RCS mode. It is possible to use both the ESP and RCS modes in the same SSASIM run.

Valid values: T (=1) or F (=0) (for true or false), Logical

Source code: read from table in run.cpp; used in rcs.cpp.

SSASIM:   RUN . rcs_id
Points to row in child RCS table.

Valid values: 1 to 999999999 (nine digits), Integer

Source code: read from table in run.cpp; used in rcs.cpp.

SSASIM:   RUN . cohort_id
Points to row in child COHORT table.

Valid values: 1 to 999999999 (nine digits), Integer

Source code: read from table in run.cpp; used in cohort.cpp.

SSASIM:   RUN . tab_script
Specifies file name of user-supplied script that tabulates, or otherwise processes, the raw output files produced by this run. The script file must be located in the same directory as the run specification file that specifies this run. The script file must be either a Windows batch file whose name ends with the .bat extension or a Tcl program whose file name ends with the .tcl extension (a Tcl interpreter is part of the SSASIM installation package). And finally, the script must be written to use exactly one command-line parameter: the value of RUN.id (padded with leading zeros to make the parameter five digits long). The use of the RUN.id parameter means that the same script can be used to process the raw output of many different runs. Obviously, the Windows batch file option is not available when the PSG models are running under Unix-like operating systems like Mac OS X or Linux. If the script writes its results to a file in the SSASIM database directory that has a *.res extension, then that tabulation results file can be opened, viewed, and printed from the RSF Toolkit editor after the run finishes execution.

NOTE: if the RUN.tab_script parameter contains a single dot character, as it does in all the benchmark runs that are used as base runs in run specification files, then no tabulation of raw output files will be conducted.

BAT EXAMPLE: if run 987 is specified by myrun.rsf located in the SSASIM\db directory, then the tabulation script must also be located in that same directory. If the script is named mytabs.bat, the entry in the RUN.tab_script parameter must be 'mytabs.bat' (without the quotes). In this example, at the end of run execution after all the raw output files have been written, SSASIM will execute the following command in the SSASIM\db directory: 'mytabs.bat 00987' (without the quotes).

TLC EXAMPLE: if run 987 is specified by myrun.rsf located in the SSASIM\db directory, then the tabulation script must also be located in that same directory. If the script is named mytabs.tcl, the entry in the RUN.tab_script parameter must be 'mytabs.tcl' (without the quotes). In this example, at the end of run execution after all the raw output files have been written, SSASIM will execute the Tcl program. When running under Windows, SSASIM will execute the following command in the SSASIM\db directory: 'tclkitsh mytabs.tcl 00987' (without the quotes). When running under Unix-like operating systems, SSASIM will execute the following command in the ~/SSASIM/db directory: 'tclsh mytabs.tcl 00987' (without the quotes).

Valid values: the tabulation script file name cannot have any embedded spaces.

SSASIM:   RUN . tab_params
Specifies optional extra command-line parameters used by the user-supplied tab_script that tabulates, or otherwise processes, the raw output files produced by this run. The extra parameters are passed to the tab_script after the mandatory RUN.id parameter (see tab_script above for details). The user-supplied tab_script must know what to do with the supplied extra parameters.

NOTE: if the RUN.tab_params parameter contains a single dot character, as it does in all the benchmark runs that are used as base runs in run specification files, then no extra tab_script parameters are passed to the tab_script when it is executed.

Valid values: each parameter value cannot have any embedded spaces; parameter values are separated by a ~ (tilde) character, so that the tab_params field value contains no embedded spaces.