.. _model_config_machines: MACHINE_SPEC_FILE ================== .. contents:: :local: Overview -------- CIME looks at the XML node ``MACHINE_SPEC_FILE`` in the **config_files.xml** file to identify supported out-of-the-box machines for the target model. The node has the following contents: Entry ----- The following is an entry for ``MACHINES_SPEC_FILE`` in ``config_files.xml``. Only a single value is required. .. code-block:: xml char $SRCROOT/cime_config/machines/config_machines.xml case_last env_case.xml File containing machine specifications for the target model primary component (for documentation only - DO NOT EDIT) $CIMEROOT/CIME/data/config/xml_schemas/config_machines.xsd You can supplement what is in the MACHINES_SPEC_FILE by adding a config_machines.xml file to your CIME config directory. .. _model_config_machines_def: Contents -------- Schema Definition ````````````````` Version 3 ::::::::: The following is an example of a version 3.0 ``config_machines.xml`` file. Version 3.0 breaks machine definitions into separate directories. .. code-block:: xml docker ... ... For each ``NODENAME_REGEX`` entry, there should be a directory named by the value of the ``MACH`` attribute. In these directories is where the machines ``config_machines.xml``, ``config_batch.xml``, and ``.*.cmake`` are stored. The ``config_machines.xml`` XML will only contain the ``machine`` portion and will omit the ``NODENAME_REGEX`` element. Version 2 ````````` The following is an example of a version 2.0 ``config_machines.xml`` file. This format provides a monolithic file for all machine definitions. .. code-block:: xml Docker LINUX gnu,gnuX openmpi CIME /storage/timings CIME /storage/cases /storage/inputdata /storage/inputdata-clmforc /storage/archive/$CASE /storage/baselines/$COMPILER /storage/tools/cprnc make 4 e3sm_developer none boutte3@llnl.gov 8 8 mpiexec -n {{ total_tasks }} --oversubscribe $CASEROOT/run $CASEROOT/bld 1 1 /opt/conda /opt/conda ... XML Elements ```````````` General ::::::: .. note:: There are some elements; ``SAVE_TIMING_DIR``, ``SAVE_TIMING_DIR_PROJECTS``, ``TESTS`` that are model-specific and are not required. =========================== ================================== Element Description =========================== ================================== DESC A text description of the machine. NODENAME_REGEX A regular expression used to identify the machine. NODE_FAIL_REGEX A regular expression to identify node failures. MPIRUN_RETRY_REGEX A regular expression to identify MPI run retries. MPIRUN_RETRY_COUNT The number of times to retry MPI runs. OS The machine's operating system. PROXY Optional HTTP proxy for internet access. COMPILERS Compilers supported on the machine. MPILIBS MPI libraries supported on the machine. Multiple values may be defined by the compiler attribute. PROJECT A project or account number used for batch jobs. CHARGE_ACCOUNT The charge account for the project. SAVE_TIMING_DIR Directory for archiving timing output. SAVE_TIMING_DIR_PROJECTS Projects whose jobs archive timing output. CIME_OUTPUT_ROOT Base directory for case output. CIME_HTML_ROOT Directory for HTML output. CIME_URL_ROOT URL root for CIME. DIN_LOC_ROOT Location of the input data directory. DIN_LOC_ROOT_CLMFORC Location for CLM forcing data. DOUT_S_ROOT Root directory of short-term archive files. BASELINE_ROOT Root directory for system test baseline files. CCSM_CPRNC Location of the cprnc tool. PERL5LIB Perl library path. GMAKE GNU-compatible make tool. GMAKE_J Number of threads for gmake. TESTS List of tests to run on the machine. NTEST_PARALLEL_JOBS Number of parallel jobs for testing. BATCH_SYSTEM Batch system used on the machine. ALLOCATE_SPARE_NODES Allocate spare nodes. SUPPORTED_BY Contact information for support. MAX_TASKS_PER_NODE Maximum number of tasks per node. Multiple values may be defined by the compiler attribute. MEM_PER_TASK Memory per task. Multiple values may be defined by the compiler attribute. MAX_MEM_PER_NODE Maximum memory per node. Multiple values may be defined by the compiler attribute. MAX_GPUS_PER_NODE Maximum GPUs per node. Multiple values may be defined by the compiler attribute. MAX_MPITASKS_PER_NODE Maximum MPI tasks per node. Multiple values may be defined by the compiler attribute. MAX_CPUTASKS_PER_GPU_NODE Maximum CPU tasks per GPU node. Multiple values may be defined by the compiler attribute. MPI_GPU_WRAPPER_SCRIPT MPI GPU wrapper script. Multiple values may be defined by the compiler attribute. COSTPES_PER_NODE Cost per node. PROJECT_REQUIRED Indicates if a project is required. RUNDIR Directory for running the case. EXEROOT Directory for executable files. TEST_TPUT_TOLERANCE Throughput tolerance for tests. TEST_MEMLEAK_TOLERANCE Memory leak tolerance for tests. MAX_GB_OLD_TEST_DATA Maximum GB of old test data. =========================== ================================== MPI :::: There can be multiple ``mpirun`` elements. The combination of attributes makes them unique. =================== ===================================== Element Description =================== ===================================== mpirun Top-level element can contain ``compiler``, ``queue``, ``threaded``, ``unit_testing``, or ``comp_interface`` attributes. aprun_mode If ``executable`` contains ``aprun`` then this element's value is used to define the aprun mode. executable The executable to run. arguments Arguments to the MPI executable. arg Argument to the MPI executable. run_exe Overrides the ``default_run_exe``. run_misc_suffix Overrides the ``default_run_misc_suffix``. =================== ===================================== .. code-block:: xml Aprun ..... The ```` element can be one of the following. The default value is ``ignore``. * ``ignore`` will cause CIME to ignore its aprun module and join the values found in ````. * ``default`` will use CIME's aprun module to generate arguments. * ``override`` behaves the same as ``default`` except it will use ```` to mutate the generated arguments. When using this mode a ``position`` attribute can be placed on ```` tags to specify how it's used. The ``position`` attribute on ```` can take one of the following values. The default value is ``per``. * ``global`` causes the value of the ```` element to be used as a global argument for ``aprun``. * ``per`` causes the value of the ```` element to be appended to each separate binary's arguments. Example using ``override``: :: aprun override -e DEBUG=true -j 20 Sample command output: :: aprun -e DEBUG=true ... -j 20 e3sm.exe : ... -j 20 e3sm.exe Module System ::::::::::::: =============== =========================================== Element Description =============== =========================================== module_system Top-level element can contain ``type`` and ``allow_error`` attributes. init_path Path to the module system initialization. cmd_path Path to the module system commands. modules Can have multiple where the combination of ``compiler``, ``DEBUG``, ``PIO_VERSION``, ``mpilib``, ``comp_interface``, and ``gpu_type`` make them unique. command Command to run where ``name`` is the action e.g. load, switch, unload and the value is the module to use e.g. netcdf-parallel/3.4 =============== =========================================== .. code-block:: xml Environment Variables ::::::::::::::::::::: =========================== ============================================ Element Description =========================== ============================================ environment_variables Can have multiple where the ``compiler`` and ``mpilib`` attributes make them unique. env Can have multiple where the combination of ``name`` makes them unique. =========================== ============================================ .. code-block:: xml Resource Limits ::::::::::::::: =================== ===================================================== Element Description =================== ===================================================== resource_limits Can have multiple where the ``DEBUG``, ``mpilib``, ``compiler``, and ``unit_testing`` make them unique. resource Defines the resource name and value. Can have multiples where name makes them unique. =================== ===================================================== .. code-block:: xml Schema ------ Version 3.0 ```````````` .. code-block:: xml Version 2.0 ``````````` .. code-block:: xml