Model Independent Details¶
As described in the terminology section of the NK solver description, the NK solver is applied to a model that is comprised of a collections of tracer modules, each of which is comprised of tracers. This section describes details of using the NK solver that are independent of which model the solver is being applied to.
Solver Input¶
Input to the solver consists of:
a comma-separated list of configuration (cfg) files, which contain settings of user-configurable options for the solver and model,
a tracer module definition file, which contains definitions of the solver’s tracer modules and the corresponding Jacobian preconditioner matrices,
domain description files, which contain grid weights (e.g., grid cell volume) and region definitions, and
an initial iterate file, which contains the tracer values for the initial iterate of the Newton solver.
User-configurable options for the solver and the model are in the configuration (cfg) files.
The file is parsed with the configparser module of the python standard library, so it is formatted following the specifications of that parser.
The file basically consists of comment lines and lines of the form varname=varvalue, that specify values for variables.
The variable specification lines are grouped into sections.
The solver’s cfg files utilize 3 sections, named DEFAULT, solverinfo, and modelinfo.
The solverinfo and modelinfo sections contain variables related to configuration of the solver and model respectively.
A key feature of this file format is interpolation, the ability to substitute the value from one variable in another variable’s value.
The DEFAULT section contains variables that are potentially interpolated into variables in both the solverinfo and modelinfo sections.
The default paths of the cfg files are $TOP/input/$model/newton_krylov.cfg and $TOP/input/$model/model_params.cfg, where $TOP is the toplevel directory of the repo and $model is the name of the model to which the Newton-Krylov solved is being applied.
The tracer module definition file is described separately.
Interactive Solver Invocation¶
The NK solver is invoked by running an invocation script, which is generated by the script nk_ooc/gen_invoker_script.py.
While this latter script can be invoked interactively with the command python -m nk_ooc.gen_invoker_script, this is usually not necessary, as there is a setup_solver.sh script that invokes it.
The gen_invoker_script.py script is designed to generate solver’s invocation script for any model for the NK solver.
The default model is test_problem.
The path of the invocation script, which defaults to nk_driver.sh in the work directory, can be modified by changing invoker_script_fname in the cfg files.
The setting of the cfg files paths to ./nk_ooc/gen_invoker_script.py is propagated to the solver’s invocation script.
Invoking the invocation script with the -h option shows what command line options are available, such --resume to resume the solver after it exits, or --rewind to back up the solver one step when resuming.
The --rewind option is useful when resuming after a forward model run aborts.
Otherwise, the solver assumes that the forward model run was successful.
Solver Output¶
Output from the NK solver is written to a work directory.
The location of the work directory is specified by workdir in the cfg files.
As the solver progresses, informational messages are written to a log file.
The path of the log file, which defaults to newton_krylov.log in the work directory, can be modified by changing logging_fname in the cfg files.
Setting logging_level=DEBUG in the cfg files will generate more output in the log file.
This can also be set via the command line option --logging_level DEBUG in the scripts (e.g., nk_ooc/gen_invoker_script.py or the solver’s invocation script).
The solver writes summary statistics for each tracer module being run to a netCDF formatted stats file.
The path of the stats file is Newton_stats.nc in the work directory.
The stats file includes mean and norm of the Newton iterates, their function evaluations, and the increments applied in Newton’s method.
The stats file also includes dimensionally reduced tracers values from history file created from the function evaluation.
The dimensional reduction is model specific.
For example, the cime_pop model generates reductions along (nlat,) and (nlat, nlon) dimension tuples.
There are also tracer module specific variables added to the stats file.
For example, the cime_pop model adds integrated air-sea CO2 gas flux for the abio_dic_dic14 tracer module.