13 Solving the model

13.1 Overview

ems_solve() solves the constrained optimization problem according to a range of runtime configuration options. In order to solve, a teems Docker image must be prebuilt. Singularity, accuracy, and error checks are carried out following a successful run. By default, solver outputs are automatically parsed into structured R objects via ems_compose().

13.2 Arguments

Argument	Default	Description
`cmf_path`		Path to the CMF file generated by `ems_deploy()`
`n_tasks`	`1L`	Number of tasks to run in parallel. Must be `1L` if `matrix_method` is `"LU"`
`n_subintervals`	`1L`	Number of subintervals for the applied shock. More subintervals may alleviate accuracy issues stemming from large shock magnitudes
`matrix_method`	`"LU"`	Matrix solution method (see below)
`solution_method`	`"Johansen"`	Solution method (see below)
`steps`	`c(2L, 4L, 8L)`	Vector of steps for the modified midpoint method. Must be all odd or all even, length 3
`laA`	`300L`	Memory parameter (%) for `"LU"` and `"SBBD"` methods
`laD`	`200L`	Memory parameter (%) for `"DBBD"` and `"NDBBD"` methods
`laDi`	`500L`	Memory parameter (%) for `"NDBBD"` method
`suppress_outputs`	`FALSE`	When `TRUE`, solver outputs are not automatically parsed with `ems_compose()`
`terminal_run`	`FALSE`	When `TRUE`, exits without running the solver, allowing the user to close R and run from the terminal
`append_args`	`NULL`	Character vector of additional arguments appended to the Docker run command (e.g., `c("-smllthreads 2", "-maxthreads 2")`)

13.3 Basic usage

outputs <- ems_solve(
  cmf_path = cmf_path,
  matrix_method = "LU",
  solution_method = "Johansen"
)

13.4 Matrix methods

Method	Description
`"LU"`	Standard LU decomposition. The most robust and potentially slowest for large models. `n_tasks` must be `1L`. Works with both static and dynamic models
`"DBBD"`	Doubly bordered block diagonal. Parallel solution method for static models only. Potentially faster than `"LU"` although less robust
`"SBBD"`	Singly bordered block diagonal. Parallel solution method for intertemporal models only. Potentially faster than `"LU"` although less robust
`"NDBBD"`	Nested doubly bordered block diagonal. Parallel solution method for large intertemporal models with many timesteps only

13.5 Solution methods

Method	Description
`"Johansen"`	Fast one-step approximation. Should only be used as a rough approximation due to handling of nonlinear equations. See COPS manual
`"mod_midpoint"`	Modified midpoint method that performs multiple passes for improved accuracy. The `steps` parameter controls the number of passes. See COPS manual

13.6 Memory parameters

If the solver returns “Error return from MA48B/BD because LA is …”, increase the relevant memory parameter gradually:

laA applies to "LU" and "SBBD" methods
laD applies to "DBBD" and "NDBBD" methods
laDi applies to the "NDBBD" method only

outputs <- ems_solve(
  cmf_path = cmf_path,
  matrix_method = "LU",
  solution_method = "Johansen",
  laA = 500L
)

13.7 Parallel solving

For models that support parallel matrix methods, increase n_tasks:

outputs <- ems_solve(
  cmf_path = cmf_path,
  n_tasks = 4,
  matrix_method = "SBBD",
  solution_method = "Johansen"
)

13.8 Multi-step solution

For greater accuracy, use the modified midpoint method with subintervals:

outputs <- ems_solve(
  cmf_path = cmf_path,
  n_subintervals = 2,
  matrix_method = "LU",
  solution_method = "mod_midpoint",
  steps = c(2, 4, 8)
)

13.9 Terminal mode

For long-running models, terminal_run allows the user to close any R IDE prior to running from the terminal:

ems_solve(
  cmf_path = cmf_path,
  matrix_method = "LU",
  solution_method = "Johansen",
  terminal_run = TRUE
)

13.10 Solving in-situ

solve_in_situ() calls the teems-solver directly with user-supplied input files, bypassing the ems_data() / ems_model() / ems_deploy() pipeline. The model file will be parsed but all input files must be provided in their final form — no checks or modifications are applied.

This function is intended for users who wish to use the teems solver with pre-prepared input files, or in combination with the standard pipeline by reusing the files written to disk by ems_deploy(). All input files are copied into model_dir before solving.

13.10.1 Arguments

Argument	Default	Description
`...`		Named arguments corresponding to input files necessary for an in-situ model run. Names must correspond to “File” statements within the model Tablo file. Values correspond to file paths where these files are found
`model_file`		Path to the model Tablo (.tab) file
`model_dir`		Base directory where input files will be copied and the model will be run
`closure_file`		Path to the closure (.cls) file
`shock_file`		Path to the shock (.shf) file
`n_tasks`	`1L`	Number of tasks to run in parallel. Must be `1L` if `matrix_method` is `"LU"`
`n_subintervals`	`1L`	Number of subintervals for the applied shock
`matrix_method`	`"LU"`	Matrix solution method: `"LU"`, `"DBBD"`, `"SBBD"`, or `"NDBBD"`
`solution_method`	`"Johansen"`	Solution method: `"Johansen"` or `"mod_midpoint"`
`steps`	`c(2L, 4L, 8L)`	Vector of steps for the modified midpoint method
`laA`	`300L`	Memory parameter (%) for `"LU"` and `"SBBD"` methods
`laD`	`200L`	Memory parameter (%) for `"DBBD"` and `"NDBBD"` methods
`laDi`	`500L`	Memory parameter (%) for `"NDBBD"` method
`suppress_outputs`	`FALSE`	When `TRUE`, returns the CMF file path instead of parsed outputs
`terminal_run`	`FALSE`	When `TRUE`, exits without running the solver
`append_args`	`NULL`	Character vector of additional arguments appended to the Docker run command (e.g., `c("-smllthreads 2", "-maxthreads 2")`)

13.10.2 Input files

All model-declared input files as well as model_file, closure_file, and shock_file are required. Input files are passed as named arguments via ..., where each name must correspond to a “File” statement in the model Tablo file. For GTAP-RE, the Tablo file declares:

File GTAPDATA # base data file;
File GTAPINT  # intertemporal data file;
File GTAPPARM # parameter file;
File GTAPSETS # set file;

These names are then used as the named arguments to solve_in_situ().

solve_in_situ(
  GTAPDATA = file.path(write_dir, "teems", "GTAPDATA.txt"),
  GTAPINT  = file.path(write_dir, "teems", "GTAPINT.txt"),
  GTAPPARM = file.path(write_dir, "teems", "GTAPPARM.txt"),
  GTAPSETS = file.path(write_dir, "teems", "GTAPSETS.txt"),
  model_file   = "GTAP-RE.tab",
  model_dir    = "~/in_situ_run/",
  closure_file = "GTAP-RE.cls",
  shock_file   = "a_shock_file.shf",
  n_tasks         = 1L,
  n_subintervals  = 1L,
  matrix_method   = "SBBD",
  solution_method = "mod_midpoint"
)

13.10.3 Output modes

By default, solve_in_situ() returns a tibble containing model output variables and coefficients. If suppress_outputs = TRUE, the function returns the CMF file path instead, which can be passed to ems_compose() for manual parsing.