Package {teems}

Character vector of length 1, file name in working directory or path to a GTAP HAR file with basedata coefficient data.

Character vector of length 1, file name in working directory or path to a GTAP HAR file with parameter coefficient data.

Character vector of length 1, file name in working directory or path to a GTAP HAR file with set elements and attributes.

Character vector of length 1 (default is NULL). One of:

• NULL: the files are read as they are, with no conversion or preparation.

• "GTAPv6" or "GTAPv7": converts a standard GTAP database to the v6.2 or v7 data format. Version conversion applies to the standard GTAP database only.

• "GTAP-AEZ", "GTAP-E" or "GTAP-EP": prepares a v7-format GTAP-AEZ, GTAP-E (12a) or GTAP-Power (12a) database for the corresponding model, adding the sets and parameters the model reads that the database does not ship. These targets do not convert between data formats: a v6-format database (the GTAP 10a layers) is refused. ems_data() applies the same preparation on its own when it detects one of these databases.

Character length 1, path to the CMF file generated by ems_deploy().

The method: "DoPri54" (default), "BoSha32", "RK4", "Heun" or "RK2". "DoPri54" and "BoSha32" are embedded pairs, so each step also yields an error estimate for adaptive control to act on; "RK4", "Heun" and "RK2" take fixed steps. "DoPri54" measured the most accurate per step on large shocks and "RK4" with a few steps the best cheap fixed-step method. When most retries come from step checks rather than from eps_tolerance, the cheaper steps of "BoSha32" can make it faster (Schiffmann 2022).

Integer length 1 (default 4L), the number of steps; under adaptive control, the number to start from. Runge-Kutta methods do not extrapolate, so there is no step-count triple.

Numeric length 1 (default 0.01), the error estimate a step may not exceed under adaptive control. On large shocks 0.01 gives four correct digits on most elements; 0.001 adds the last digits at about 1.6 times the cost. GEMPACK suggests 0.1, which measured rougher on large shocks. Ignored when adaptive = "no".

Character length 1. NULL (default) means "yes" for "DoPri54" and "BoSha32" and "no" for the fixed-step methods, which have no error estimate.

• "no": fixed steps.

• "yes": a step whose error estimate exceeds eps_tolerance is redone shorter, and a step that passes may lengthen the next one, by at most a factor of two either way. A step that fails a step check (a percentage-change variable crossing ⁠-100%⁠, a coefficient range test, a TAB assertion or the guard) is also retried shorter.

• "accuracy-only": as "yes", but step checks do not trigger a retry.

Character of length 1, matrix solution method (default is "LU"). Choices:

• "LU": Standard LU decomposition, the most robust and potentially slowest for a large model. For use with both static and dynamic models.

• "DBBD": Doubly bordered block diagonal, parallel solution for static models partitioned by their regional set.

• "SBBD": Singly bordered block diagonal, parallel solution for intertemporal models partitioned along the time chain.

• "NDBBD": Nested doubly bordered block diagonal, for intertemporal models whose "SBBD" host copy does not fit the memory available. ems_probe() (experimental) suggests the method and the tasks and threads to run it with for a deployment and a machine, and prints the call to paste (see Details).

Integer length 1 (default is 1L), number of tasks to run in parallel. Must be 1L if "matrix_method" == "LU".

Integer length 1 (default 1L), OpenMP threads per MPI task. "LU", "SBBD" and "NDBBD" give byte-identical results at any thread count; "DBBD" with more than one thread agrees only to rounding (see the solving chapter of the user manual).

Character length 1, "single" (default) or "double": floating-point precision of the solver's coefficient storage. "single" halves memory traffic and suffices for ordinary step counts. "double" selects the double-precision solver binary shipped in the same image, removing the single-precision update-rounding floor that deep extrapolation ladders and many-step large-shock runs otherwise converge onto (per-pass rounding accumulates with step count, so beyond the floor extra steps stop helping). Roughly doubles coefficient-array memory. The effective precision is recorded in sol.stats.json and the model diagnostics solve record.

Integer length 1 (default is 1L), number of subintervals for the applied shock. More subintervals may alleviate accuracy issues stemming from large shock magnitudes. In a model with active complementarities each subinterval runs its own approximate and accurate run; the Runge-Kutta methods take subintervals only there.

Integer length 1, 0, 1 (default) or 2. Solver log detail: 0 restricts output to errors, warnings, and the accuracy summary; 1 adds phase progress and timings; 2 adds per-rank and per-block debug detail.

Logical length 1 (default is FALSE). When TRUE solver outputs are not automatically converted into structured data with ems_compose().

Logical length 1 (default is FALSE). When TRUE, the function is exited without running the solver. This allows the user to close any R IDE or other programs prior to running from the terminal. When TRUE solver outputs are not automatically converted into structured data with ems_compose().

Character vector of variable names (default NULL). When given, the accuracy summary of a three-solution "Gragg", "Midpoint" or "Euler" run covers just these variables, exogenous ones included, instead of every endogenous result. Under the "solution" and "both" accuracy criteria (see ems_option_set()) the warning then judges only them, so a run can be held to the results it is about.

Integer length 1 (default 3L). How many times a step that fails a step check is retried shorter before the run aborts.

Numeric length 1 in (0, 1) (default 0.5). The factor the step is shortened by on each retry.

Character length 1, the coordinates the stages are combined in. "log" (default) carries each percentage-change variable as the logarithm of its level ratio, so levels stay positive whatever the step and no percentage-change variable can reach ⁠-100%⁠; the methods keep their order (Munthe-Kaas 1999). "percent" combines the stages in percentage changes from the initial level.

Character length 1. Whether the worst element ("max", default) or the root mean square over elements ("rms") is compared with eps_tolerance.

Character length 1, the step-size rule: "std" (default), or "pi", which also weighs the previous step's estimate and rejects fewer steps on rough solution paths.

Character length 1, which elements the accept test looks at: "pct" (default), the percentage-change variables, whose error estimate is dimensionless; or "all", which adds the ordinary-change variables. Their estimate is in their own units, so an accumulator in dollars can reject every step early in the path. error_estimate is reported for every element either way.

Numeric length 1 in (0, 1/steps] (default NULL, which is 1/steps), the first step length. Under adaptive control the first step is also capped from the initial gradient.

Numeric length 1 greater than 1 (default NULL, no guard), chart = "log" only: the level ratio beyond which a stage is rejected and the step retried.

Named extras, as ... of ems_solve(): the MA48 workspace guesses (laA, laD, laDi) and the expert solver flags. The Runge-Kutta controls are formal arguments here, so their ⁠rk_*⁠ names are refused.

Character length 1, path to the CMF file generated by ems_deploy().

Character vector of variable length (default "all"). When "all", all model variables and coefficients (updated, post-simulation values, plus any PostSim coefficients typed "postsim") are returned. Condensation coefficients (⁠CSUB<n>⁠) are returned only when named. Otherwise, a character vector of variable and/or coefficient names to retrieve (case insensitive). Note that some coefficient names differ from their associated headers (e.g., VTWR/VTMFSD). Coefficient values are read from the solver's binary coefficient dump (sol.cof/sol.cbin).

Logical length 1 (default FALSE). When TRUE, each variable's data.table gains the three separate solutions of a "Gragg", "Midpoint" or "Euler" run and their accuracy columns, and the output gains an accuracy attribute (see Details). An error is raised for a run that wrote no separate solutions.

Character of length 1, the variable to be shocked.

Path to a CSV file, or a data frame or data frame extension (e.g., tibble, data.table). Must contain one column named "Value" with the shock for each tuple (percentage or ordinary change, as the variable is declared), plus one column per set index for the variable. Note that set names must conform to the model-specific hybrid format (e.g., ACTSa, REGr). Column order is inconsequential.

Character vector of length 1, file name in working directory or path to a data input containing basedata coefficient data, or the corresponding "dat" list object generated by GTAP_convert().

Character vector of length 1, file name in working directory or path to a data input containing parameter coefficient data, or the corresponding "par" list object generated by GTAP_convert(). NULL (default) together with a NULL set_input selects the single-file route.

Character vector of length 1, file name in working directory or path to a data input containing set elements and attributes, or the corresponding "set" list object generated by GTAP_convert(). NULL (default) together with a NULL par_input selects the single-file route.

Integer vector of variable length (default is NULL). For use with temporally dynamic models. Input format is either chronological years of steps including initial reference year corresponding to the database employed or steps from t0 with initial value 0.

Character vector (default is "value"), the weights with which parameters are averaged when their sets are aggregated.

• "value": each member is weighted by the value of its nest, the GTAP aggregation rule; the Armington, intermediate-input and value-added elasticities are weighted with world totals and take one value in every region.

• "share": each member is weighted by the value of its CES or CET nest times one minus the sum of its squared input shares, so that the aggregate elasticity reproduces the members' response to a small relative price change. Members whose input shares cannot move (for example a commodity that is never imported) carry no weight, which can leave an aggregate far below the value-weighted elasticity where those members dominate it.

An unnamed element sets the method for every weighted parameter; elements named after a parameter header (e.g. c("value", ESBM = "share")) override it for that parameter. The CDE parameters (INCP, SUBP) are weighted by value under either method. Has no effect when only dat_input is given, since that route does not aggregate.

A named pairlist assigning set mappings to model sets that are explicitly read (not constructed via any set operation defined in the model file). Set mappings can be selected from a range of internally available options or provided by the user.

• Internal mapping: character vector of length 1 corresponding to an internally available mapping.

• User-provided mapping: character vector of length 1, file name in working directory or path to a CSV file; a data frame or data frame extension (e.g., tibble, data.table).

See teems-mappings for internally available mappings and formatting for user-provided mappings.

A list of data.tables generated by ems_data().

A tibble generated by ems_model().

A shock object or list of shock objects produced by ems_uniform_shock(), ems_custom_shock(), or ems_scenario_shock(). When NULL (default), no shock is applied and input data is returned without change.

A character vector of variable length, list generated by ems_swap(), or combination of the above provided as a list (default NULL). Variables to be made exogenous.

A character vector of variable length, list generated by ems_swap(), or combination of the above provided as a list (default NULL). Variables to be made endogenous.

A character vector length 1 (default NULL). Path to a file with .shf extension representing a fully prepared shock file. No checks or modifications are carried out on this file.

Logical of length 1 (default FALSE). Coefficient values return to R through the solver's binary coefficient dump, read selectively by ems_compose(). Set TRUE to also emit per-coefficient CSV files in ⁠out/coefficients/⁠ via auto-generated File/Write statements in the GEMPACK spreadsheet-style text data file format.

Character vector of length 1, name of model. Options include:

• "GTAPv7": Standard GTAP model (version 7.1)

• "GTAP-RE": Intertemporal GTAP with rational expectations: forward-looking investment, all periods solved at once

• "GTAP-AEZ": GTAPv7 with land use by agro-ecological zone, land entering production as a CES composite of the zones (requires a GTAP-AEZ database)

• "GTAP-E": GTAPv7 with energy substitution and carbon taxes, a capital-energy composite inside value added (requires a GTAP-E database)

• "GTAP-EP": GTAP-E with electricity split into transmission and distribution and generation, and generation into base-load and peak-load technologies (requires a GTAP-Power database)

• "GTAPv6": Classic GTAP model (version 6.2)

Character vector of length 1. Directory where files will be written.

Character vector of length 1, (default is "model_files"). Determines the example output. Options include:

• "model_files": Model file and closure file

• "scripts": Example scripts for the chosen model. dat_input, par_input, and set_input are required.

Character vector of length 1 (default is NULL, only used when type = "scripts"), file name in working directory or path to a data input containing basedata coefficient data, or the corresponding "dat" list object generated by GTAP_convert().

Character vector of length 1 (default is NULL, only used when type = "scripts"), file name in working directory or path to a data input containing parameter coefficient data, or the corresponding "par" list object generated by GTAP_convert().

Character vector of length 1 (default is NULL, only used when type = "scripts"), file name in working directory or path to a data input containing set elements and attributes, or the corresponding "set" list object generated by GTAP_convert().

Character vector length 1, path to a TABLO file with .tab extension. See teems-models for vetted models and compatible Tablo file formatting.

Character vector length 1, path to a closure file with .cls extension. See teems-models for closure file formatting.

Character vector of variable length (default is NULL), variable names to substitute out of the system by backsolving. Unnamed entries resolve their defining equation by the ⁠E_<variable>⁠ convention; use named entries for exceptions (e.g., c(qgd = "E_qgdtot")). Backsolved variables must be endogenous; their values remain available in solve outputs. Each nomination is checked to make sure its equation can be solved for the variable (see GEMPACK manual 14.1.10); a nomination that fails aborts with the reason.

Logical length 1 (default is FALSE). If TRUE, in-TAB Substitute, Backsolve and Omit statements are ignored. Otherwise Substitute statements are executed as backsolves and Omit statements make the omitted variables exogenous where the closure does not already. The solver automatically drops unshocked exogenous variables from the solve, and their zero results remain in the outputs.

A named pairlist assigning values to model coefficients. Name must match a coefficient declared in the model file. Value may be a length-1 numeric, a data frame or data frame extension (e.g., tibble, data.table), or a path to a CSV file.

Name of the option for which to retrieve a value. One of:

• NULL Returns all option values.

• "tempdir" Character. Directory used for temporary file storage during a model run.

• "verbose" Logical. If FALSE, function-specific diagnostics are silenced.

• "ndigits" Integer. Number of digits to the right of the decimal point written to file for numeric type double (at least ndigits significant digits for small values).

• "accuracy_threshold" Numeric. Share of results that must be accurate to at least accuracy_figures figures.

• "accuracy_figures" Integer. Significant figures a result must reach to count as accurate (the default is 4).

• "accuracy_criterion" Character. "solution" (the default), "data" or "both": the accuracy summary judged.

• "required_figures" Integer or NULL (the default). Figures for the convergence code XRA.

• "full_exclude" Character vector. Headers to fully exclude from all aspects of the model run.

• "check_shock_status" Logical. If FALSE, no check on shock element endogenous/exogenous status is conducted.

• "timestep_header" Character. Header written with the time of each period (time_steps of ems_data()).

• "n_timestep_header" Character. Header written with the number of periods.

• "docker_tag" Character. Tag of the teems Docker image to use. "latest" when unset.

• "assertions" Character. "fatal" (the default), "warn" or "off": severity of TAB Assertion failures in ems_solve().

• "range_test_initial" Character. "fatal" (the default), "warn" or "off": severity of declared-range violations on initial values.

• "range_test_updated" Character. "warn" (the default), "fatal" or "off": as "range_test_initial", for updated values.

• "random_seed" Integer. Seed of RANDOM(a,b) (the default is 1).

• "refine" Logical. TRUE (the default): one refinement step per "DBBD" solve (see ems_option_set()).

• "converge" Logical. FALSE (the default); TRUE applies GEMPACK's treatment of poorly converging results (see ems_option_set()).

A character vector length 1. Default is what is returned by tempdir(). Directory where input files, model diagnostics, and output files are written as well as where the model run takes place (via Docker bind mount).

Logical of length 1 (default is TRUE). If FALSE, function-specific diagnostics are silenced.

Integer (default is 6). Number of digits to the right of the decimal point kept when numeric type double data are written to file. Values smaller than 0.1 in magnitude keep ndigits significant digits instead, so small nonzero data are never rounded to zero.

Numeric length 1 (default 0.8). The share of results that must be accurate to at least accuracy_figures significant figures under accuracy_criterion; a warning is generated if the share is lower.

Integer length 1 from 1 to 6 (default 4). The significant figures a result must reach to count as accurate.

Character length 1 (default "solution"). Which accuracy summary is judged: "solution" the levels values of the endogenous results, "data" the values read from data files and updated, "both" the two together. The criteria of GEMPACK's automatic accuracy (GEMPACK manual 26.4), whose default is "data". A run that updates no data is judged on the solution under "data" and "both".

Integer length 1 from 1 to 6 (default NULL, none). Results of a three-solution "Gragg", "Midpoint" or "Euler" run whose two extrapolations agree to at least this many figures get the convergence code XRA in the accuracy summary (GEMPACK manual 26.2.6, RQF). Reporting only.

A character vector of variable length (default is c("DREL", "DVER", "XXCR", "XXCD", "XXCP", "SLUG", "EFLG")). Headers to fully exclude from all aspects of the model run. Failure to designate these headers properly will result in errors. Modify with caution.

Logical of length 1 (default is TRUE). If FALSE, no check on the endogenous/exogenous status of a variable designated for a shock is conducted.

A character vector length 1 (default is "YEAR"). Header written with the time of each period, as given in the time_steps argument of ems_data() (years, or steps from the initial period); the model takes the differences between consecutive periods as interval lengths. For novel intertemporal models — modify with caution.

A character vector length 1 (default is "NTSP"). Header written with the number of periods (the length of time_steps). For novel intertemporal models — modify with caution.

Character length 1 (default "latest"). Tag of the teems Docker image to use.

Character length 1, "fatal" (default), "warn" or "off". Severity of TAB Assertion statement failures: "warn" reports and continues, "off" skips the checks.

Character length 1, "fatal" (default), "warn" or "off". Severity of declared-range violations (e.g. ⁠(ge 0)⁠) on initial values: every coefficient, read or computed, is tested once the initial Reads and Formulas are done.

Character length 1, "warn" (default), "fatal" or "off". As range_test_initial, for updated values (⁠range test updated values⁠).

Integer (default is 1). Seed of the TAB function RANDOM(a,b). The same seed reproduces every draw; each Formula element keeps its draw across steps and extrapolation passes. Change the seed for a new sequence.

Logical length 1 (default TRUE). One step of iterative refinement after every linear solve of matrix_method = "DBBD" in ems_solve(), which brings its accuracy to that of "LU". Refinement holds the system matrix and the block factorizations through each solve, so it raises peak memory; the memory estimate counts it. "LU" and "SBBD" are in practice as accurate as a single LU solve and are not refined; "NDBBD" is not refined, as it cannot yet keep its factorization for a second solve.

Logical length 1 (default FALSE). If TRUE, ems_solve() applies GEMPACK's treatment of poorly converging results (see GEMPACK manual 26.2.5) to a run extrapolated from three multi-step solutions: a component whose three solutions lie very close together or near zero reports their average, one whose solutions do not converge cleanly reports the solution with the most steps, and the rest are extrapolated. Not available with subtotals.

Character length 1, path to the CMF file written by ems_deploy().

Logical length 1 (default TRUE). Also find the simultaneous components of the system, the groups of equations that must be solved together, and the make-up of the largest; needed by plot(x, type = "components").

Integer length 1 or NULL (default). The number of cores the recommendation is made for. NULL reads it from the container the solver runs in (on Docker Desktop, the Resources setting); give a number for another machine.

Numeric length 1 or NULL (default). The memory in GB the recommendation is made for, read from the container when NULL.

Named solver arguments, the same ones ... of ems_solve() accepts: the MA48 workspace guesses (laA, laD, laDi) and the expert solver flags. The Runge-Kutta controls are accepted and ignored.

Character of length 1, the variable to be shocked.

Path to a CSV file, or a data frame or data frame extension (e.g., tibble, data.table), with a Value column of absolute values, a Year column of chronological years including the base year, and one column per remaining set index of the variable in the model-specific format (e.g., REGr). Column order is inconsequential.

Logical of length 1 (default FALSE). If TRUE, input may cover a subset of the variable's aggregated tuples; only those are shocked, and they must be exogenous.

Character length 1, path to the CMF file generated by ems_deploy().

The solution method to be used, default is "Gragg" with steps = c(2L, 4L, 6L). Choices:

• "Gragg": Gragg's method (the smoothed modified midpoint method; Pearson 1991). The shock is applied over a sequence of linearized steps (a Euler first step, midpoint "leapfrog" steps, and a terminal smoothing pass) and the sequence is repeated for each of the three step counts in steps. The three solutions are then combined by Richardson extrapolation, giving rapid error decay as steps increase plus an accuracy estimate from the agreement between levels.

• "Johansen": The one-step Johansen method is fast however it should only be used as a rough approximation due to handling of nonlinear equations.

• "Euler": The forward Euler method, computed for each of the three step counts in steps and combined by Richardson extrapolation. Converges more slowly than "Gragg" (its truncation error shrinks linearly in the step size, so the extrapolated accuracy gains one order per solution instead of two) but it is the most robust of the multistep methods: each step uses only the current state, so it tolerates near-asymptote levels and severe shocks — including exact ⁠-100%⁠ shocks — where the midpoint family can become unstable. Any strictly increasing step counts are permitted.

• "Midpoint": The midpoint method, Gragg's method without the terminal smoothing pass (N passes for N steps), combined by Richardson extrapolation over steps like "Gragg". It never takes the exogenous variables past their end point, so it suits shocks of exactly ⁠-100%⁠, which Gragg's final pass cannot take.

• "RK2", "Heun", "RK4": Explicit Runge-Kutta methods (the midpoint rule, the explicit trapezoid rule and the classic fourth-order method; Schiffmann 2022). A single solution is computed with the one step count in steps — no Richardson extrapolation — with each step built from 2 ("RK2", "Heun") or 4 ("RK4") staged linear solves. "RK4" reaches a given accuracy in far fewer steps than the extrapolating methods.

• "BoSha32", "DoPri54": Embedded Runge-Kutta pairs (Bogacki-Shampine 3(2), 4 stages; Dormand-Prince 5(4), 7 stages). Alongside the solution they compute a component-by-component estimate of the cumulative error — returned as the error_estimate column by ems_compose() and summarized as a face value in the solver log — and they support adaptive step-size control via adaptive and eps_tolerance. "DoPri54" with adaptive = "yes" is the recommended high-accuracy choice.

Character of length 1, matrix solution method (default is "LU"). Choices:

• "LU": Standard LU decomposition, the most robust and potentially slowest for a large model. For use with both static and dynamic models.

• "DBBD": Doubly bordered block diagonal, parallel solution for static models partitioned by their regional set.

• "SBBD": Singly bordered block diagonal, parallel solution for intertemporal models partitioned along the time chain.

• "NDBBD": Nested doubly bordered block diagonal, for intertemporal models whose "SBBD" host copy does not fit the memory available. ems_probe() (experimental) suggests the method and the tasks and threads to run it with for a deployment and a machine, and prints the call to paste (see Details).

Integer length 1 (default is 1L), number of subintervals for the applied shock. More subintervals may alleviate accuracy issues stemming from large shock magnitudes. In a model with active complementarities each subinterval runs its own approximate and accurate run; the Runge-Kutta methods take subintervals only there.

Integer (default is NULL, resolved per method: c(2L, 4L, 6L) for the extrapolating methods, 4L for the Runge-Kutta methods). "Gragg", "Midpoint", "Johansen" and "Euler" take a vector of length 3: the three counts must increase for "Gragg", "Midpoint" and "Euler", and must be all even or all odd for "Gragg" and "Midpoint" (even counts are recommended). "Gragg", "Midpoint" and "Euler" also take a single count, a single multi-step run without Richardson extrapolation, or two increasing counts, extrapolated from two solutions; no extrapolation accuracy estimate is then available. "RK2", "Heun", "RK4", "BoSha32" and "DoPri54" take a single count of 1 or more. A larger number of steps may improve accuracy for some model runs.

Integer length 1 (default is 1L), number of tasks to run in parallel. Must be 1L if "matrix_method" == "LU".

Integer length 1 (default 1L), OpenMP threads per MPI task. "LU", "SBBD" and "NDBBD" give byte-identical results at any thread count; "DBBD" with more than one thread agrees only to rounding (see the solving chapter of the user manual).

Character length 1, "single" (default) or "double": floating-point precision of the solver's coefficient storage. "single" halves memory traffic and suffices for ordinary step counts. "double" selects the double-precision solver binary shipped in the same image, removing the single-precision update-rounding floor that deep extrapolation ladders and many-step large-shock runs otherwise converge onto (per-pass rounding accumulates with step count, so beyond the floor extra steps stop helping). Roughly doubles coefficient-array memory. The effective precision is recorded in sol.stats.json and the model diagnostics solve record.

Integer length 1, 0, 1 (default) or 2. Solver log detail: 0 restricts output to errors, warnings, and the accuracy summary; 1 adds phase progress and timings; 2 adds per-rank and per-block debug detail.

Logical length 1 (default is FALSE). When TRUE solver outputs are not automatically converted into structured data with ems_compose().

Logical length 1 (default is FALSE). When TRUE, the function is exited without running the solver. This allows the user to close any R IDE or other programs prior to running from the terminal. When TRUE solver outputs are not automatically converted into structured data with ems_compose().

Character vector of variable names (default NULL). When given, the accuracy summary of a three-solution "Gragg", "Midpoint" or "Euler" run covers just these variables, exogenous ones included, instead of every endogenous result. Under the "solution" and "both" accuracy criteria (see ems_option_set()) the warning then judges only them, so a run can be held to the results it is about.

Additional named solver arguments; anything else is an error, never a silently ignored flag. Effective values of recorded flags land in sol.stats.json regardless of how they were passed. Three groups are accepted:

Expert solver flags, with the solver default applied when a flag is absent:

• postsim (logical, default TRUE): FALSE skips the TAB's PostSim sections.

• inmemory (logical, default TRUE except for "NDBBD"): keep value arrays and block factors resident in memory rather than in scratch files. The solver falls back to scratch with a warning when the estimated need exceeds the memory available.

• fastrefac (logical, default FALSE): persistent-pivot refactorization; under "DBBD" it helps only small systems, whose block orderings repeat from step to step.

• ma48_cntl2 (numeric in (0, 1], default each library's own: MA48 0.1, HSL_MP48 0.01): MA48/HSL_MP48 pivot threshold CNTL(2), at every factorization including the "DBBD"/"NDBBD" rank probes, so it can also move their block sizes; a calibration knob, not a tuning recommendation.

• ma48_cntl4 (numeric >= 0, default 1e-4): MA48 CNTL(4) in the MA48/MA51 rank probes that size the "DBBD"/"NDBBD" blocks; pivots below it count as zero (0 = MA48's own default, exact zeros only). A calibration knob, not a tuning recommendation.

• nsbbdblocks (integer, default 2): HSL MC66 nblocks, the number of row blocks MC66 partitions "SBBD" into; used only with withmc66 = TRUE.

• withmc66 (logical, default FALSE): MC66 row ordering for SBBD.

• smllthreads (integer, default the run's thread count): OpenMP threads for the "NDBBD" interface factorization and back-substitution.

• nowrites (logical, default FALSE): skip the solver-side output-file dumps; coefficient composition then has nothing to read. Distinct from suppress_outputs, which only skips the R-side composition.

• condest (logical, default FALSE): per-solve quality diagnostics on the "LU" matrix method: componentwise backward error and scaled condition numbers via HSL MA60/MC71, logged per linear solve with run maxima recorded under condest in sol.stats.json. Diagnostic only (solutions are unchanged) and informative only for nonzero shocks.

• jacdump (logical, default FALSE): write the base-point Jacobian of the condensed system over every variable element, before the first step, to sol.jac with its row map in sol.jac.json; the run then solves as asked.

Runge-Kutta step controls: adaptive, eps_tolerance, max_retries and retry_adjust; see ems_RK() for their documentation and RK-tuned defaults.

MA48 workspace initial guesses, integer percents of the system nonzeros. When omitted, a previous run of the same deployment warm-starts them from its recorded la_used in sol.stats.json, else package defaults apply; the solver grows the workspace itself if any guess proves too small.

• laA: "LU"/"SBBD" and the diagonal blocks.

• laD: the "DBBD"/"NDBBD" interface systems.

• laDi: "NDBBD" intermediate interfaces.

Character of length 1, model variable to swap.

Optional named arguments restricting the swap to a subset of variable elements. Each name must use the model-specific set-index format (set name concatenated with its index letter, e.g., REGr, COMMc). Unspecified sets default to all elements. SET corresponds to the generic set name while i is specific to the variable index. Three forms are accepted:

• Single element: SETi = "element"

• Multiple elements: SETi = c("element1", "element2")

• Subset: SETi = "SUBSET"

Character of length 1, the variable to be shocked.

Numeric length 1, value of the shock in the variable's own form (percentage or ordinary change).

Optional named arguments restricting the shock to a subset of the variable's elements. Each name must use the model-specific set-index format (set name concatenated with its index letter, e.g., REGr, COMMc). Value may consist of one or more elements or a subset. In an intertemporal model, ⁠Year = <year>⁠ may stand in for the time set. When omitted, the shock is applied to all variable tuples.

A teems_probe object from ems_probe().

Character length 1: "incidence" (default), "dm", or "components".

Integer length 1 (default 60L). Axis labels are dropped when a dimension exceeds this count.

Unused.

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. No checks or modifications are conducted on input files used in this manner. All model declared input files as well as "model_file", "closure_file", and "shock_file" are required for in-situ model runs.

Character of length 1, base directory where input files will be copied (if not all already present) and model outputs will be written.

Character vector length 1, path to a TABLO file with .tab extension. See teems-models for vetted models and compatible Tablo file formatting.

Character vector length 1, path to a closure file with .cls extension. See teems-models for closure file formatting.

A character vector length 1, path to a file with .shf extension representing a fully prepared shock file. No checks or modifications are carried out on this file.

Logical length 1 (default is FALSE). If TRUE, Substitute and Backsolve statements found in the model file are ignored, as for ems_model() (in-TAB Omit statements are always ignored). Set this to match the ems_model() call that produced the closure and shock files.

The solution method to be used, default is "Gragg" with steps = c(2L, 4L, 6L). Choices:

• "Gragg": Gragg's method (the smoothed modified midpoint method; Pearson 1991). The shock is applied over a sequence of linearized steps (a Euler first step, midpoint "leapfrog" steps, and a terminal smoothing pass) and the sequence is repeated for each of the three step counts in steps. The three solutions are then combined by Richardson extrapolation, giving rapid error decay as steps increase plus an accuracy estimate from the agreement between levels.

• "Johansen": The one-step Johansen method is fast however it should only be used as a rough approximation due to handling of nonlinear equations.

• "Euler": The forward Euler method, computed for each of the three step counts in steps and combined by Richardson extrapolation. Converges more slowly than "Gragg" (its truncation error shrinks linearly in the step size, so the extrapolated accuracy gains one order per solution instead of two) but it is the most robust of the multistep methods: each step uses only the current state, so it tolerates near-asymptote levels and severe shocks — including exact ⁠-100%⁠ shocks — where the midpoint family can become unstable. Any strictly increasing step counts are permitted.

• "Midpoint": The midpoint method, Gragg's method without the terminal smoothing pass (N passes for N steps), combined by Richardson extrapolation over steps like "Gragg". It never takes the exogenous variables past their end point, so it suits shocks of exactly ⁠-100%⁠, which Gragg's final pass cannot take.

• "RK2", "Heun", "RK4": Explicit Runge-Kutta methods (the midpoint rule, the explicit trapezoid rule and the classic fourth-order method; Schiffmann 2022). A single solution is computed with the one step count in steps — no Richardson extrapolation — with each step built from 2 ("RK2", "Heun") or 4 ("RK4") staged linear solves. "RK4" reaches a given accuracy in far fewer steps than the extrapolating methods.

• "BoSha32", "DoPri54": Embedded Runge-Kutta pairs (Bogacki-Shampine 3(2), 4 stages; Dormand-Prince 5(4), 7 stages). Alongside the solution they compute a component-by-component estimate of the cumulative error — returned as the error_estimate column by ems_compose() and summarized as a face value in the solver log — and they support adaptive step-size control via adaptive and eps_tolerance. "DoPri54" with adaptive = "yes" is the recommended high-accuracy choice.

Character of length 1, matrix solution method (default is "LU"). Choices:

• "LU": Standard LU decomposition, the most robust and potentially slowest for a large model. For use with both static and dynamic models.

• "DBBD": Doubly bordered block diagonal, parallel solution for static models partitioned by their regional set.

• "SBBD": Singly bordered block diagonal, parallel solution for intertemporal models partitioned along the time chain.

• "NDBBD": Nested doubly bordered block diagonal, for intertemporal models whose "SBBD" host copy does not fit the memory available. ems_probe() (experimental) suggests the method and the tasks and threads to run it with for a deployment and a machine, and prints the call to paste (see Details).

Integer length 1 (default is 1L), number of subintervals for the applied shock. More subintervals may alleviate accuracy issues stemming from large shock magnitudes. In a model with active complementarities each subinterval runs its own approximate and accurate run; the Runge-Kutta methods take subintervals only there.

Integer (default is NULL, resolved per method: c(2L, 4L, 6L) for the extrapolating methods, 4L for the Runge-Kutta methods). "Gragg", "Midpoint", "Johansen" and "Euler" take a vector of length 3: the three counts must increase for "Gragg", "Midpoint" and "Euler", and must be all even or all odd for "Gragg" and "Midpoint" (even counts are recommended). "Gragg", "Midpoint" and "Euler" also take a single count, a single multi-step run without Richardson extrapolation, or two increasing counts, extrapolated from two solutions; no extrapolation accuracy estimate is then available. "RK2", "Heun", "RK4", "BoSha32" and "DoPri54" take a single count of 1 or more. A larger number of steps may improve accuracy for some model runs.

Integer length 1 (default is 1L), number of tasks to run in parallel. Must be 1L if "matrix_method" == "LU".

Integer length 1 (default 1L), OpenMP threads per MPI task. "LU", "SBBD" and "NDBBD" give byte-identical results at any thread count; "DBBD" with more than one thread agrees only to rounding (see the solving chapter of the user manual).

Character length 1, "single" (default) or "double": floating-point precision of the solver's coefficient storage. "single" halves memory traffic and suffices for ordinary step counts. "double" selects the double-precision solver binary shipped in the same image, removing the single-precision update-rounding floor that deep extrapolation ladders and many-step large-shock runs otherwise converge onto (per-pass rounding accumulates with step count, so beyond the floor extra steps stop helping). Roughly doubles coefficient-array memory. The effective precision is recorded in sol.stats.json and the model diagnostics solve record.

Integer length 1, 0, 1 (default) or 2. Solver log detail: 0 restricts output to errors, warnings, and the accuracy summary; 1 adds phase progress and timings; 2 adds per-rank and per-block debug detail.

Logical length 1 (default is FALSE). When TRUE solver outputs are not automatically converted into structured data with ems_compose().

Logical length 1 (default is FALSE). When TRUE, the function is exited without running the solver. This allows the user to close any R IDE or other programs prior to running from the terminal. When TRUE solver outputs are not automatically converted into structured data with ems_compose().

Character vector of variable names (default NULL). When given, the accuracy summary of a three-solution "Gragg", "Midpoint" or "Euler" run covers just these variables, exogenous ones included, instead of every endogenous result. Under the "solution" and "both" accuracy criteria (see ems_option_set()) the warning then judges only them, so a run can be held to the results it is about.

Named list (default NULL). The named solver arguments ems_solve() accepts through ..., passed as a list because the in-situ ... carries the input files: the MA48 workspace initial guesses (laA, laD, laDi), the expert solver flags (postsim, inmemory, fastrefac, nsbbdblocks, withmc66, smllthreads, nowrites, condest, jacdump, ma48_cntl2, ma48_cntl4) and the Runge-Kutta run controls (rk_chart, rk_norm, rk_controller, rk_scope, rk_h0, rk_guard) and the Runge-Kutta step controls (adaptive, eps_tolerance, max_retries, retry_adjust; see ems_RK()). See the ems_solve() ... documentation for each argument's meaning.