The configuration file is the machine

The configuration file is the machine. The test class does not name the site.

The configuration file is the machine. The class is portable.

The machine lives in the configuration. The class does not name a cluster.

Questions

• What belongs in the test, and what belongs in the configuration?

• What does the builtin configuration already define?

• Which environment variables stop a site repeating -C and --prefix on every invocation?

What you will be able to do

1. Read a configuration file and name the system, the partitions and the environments it defines.

2. Say what the builtin configuration already provides, and why a site file does not replace it.

3. Set the three RFM_* variables a site actually needs.

Before this page

• The pipeline has six stages, for where the partition is consulted.

Each ReFrame test defines the actions to be executed. Each ReFrame configuration defines the target environment. Combining a test and a configuration forms the portability problem that the config aims to resolve. The page contains the file that separates them. The official tutorial shows the division using STREAM on a single-node container and on a compose-built Slurm cluster, while the test class remains unchanged. EESSI’s documentation uses the same approach: define the system configuration and then direct ReFrame to the suite. CSCS provides config/cscs.py alongside checks/, not within it.

Three lists

A configuration is a Python file that assigns site_configuration, a dictionary. Three keys do most of the work. systems is a list of machines. Each system has a name, a list of hostnames ReFrame matches against socket.gethostname(), a modules system (lmod, envmod, nomod), and a list of partitions. ReFrame 4.10 dropped tmod and deprecated tmod4. A partition is a scheduler plus a launcher plus a list of environments. scheduler = 'slurm' and launcher = 'srun' is the common HPC pair. scheduler = 'local' and launcher = 'local' is the laptop pair. The partition is what a test’s valid_systems matches against, as system:partition. environments is a list of programming environments: a compiler and the modules that provide it. A compile test is tried once per matching environment. A run-only test that sets valid_prog_environs = ['default'] is saying the environment does not matter, and the configuration still has to define a default so the filter has something to match. The builtin configuration is always loaded. It defines the generic system, the default partition, the builtin environment, and a baseline logging setup. A site file adds to that; it does not replace it. reframe -l with no -C lists tests against generic:default+builtin. STREAM on the tutorial page runs against generic:default+builtin with no site file. A site file adds systems. The class does not have to be listed.

A file small enough to read

The documented skeleton of EESSI is reduced to the keys required for this page.

import os
from eessi.testsuite.common_config import (
 common_logging_config, common_eessi_init,
)

site_configuration = {
 'systems': [
 {
 'name': 'example',
 'descr': 'Example cluster',
 'modules_system': 'lmod',
 'hostnames': ['.*'],
 'stagedir': (
 f'/shared/reframe/{os.environ["USER"]}/stage'
 ),
 'partitions': [
 {
 'name': 'cpu',
 'scheduler': 'slurm',
 'launcher': 'srun',
 'environs': ['default'],
 'processor': {
 'num_cpus': 128,
 },
 'max_jobs': 8,
 },
 ],
 },
 ],
 'environments': [
 {
 'name': 'default',
 'modules': [],
 },
 ],
 'logging': common_logging_config(),
}

hostnames = ['.*'] matches any host. A lone \* is not a regex and ReFrame raises ConfigError. A shared configuration used from several login nodes requires this. A tighter list stops ReFrame from loading this system on a machine it does not describe. stagedir is the shared filesystem. The pipeline has six stages. Every node that will run a test must see this path according to EESSI’s comment on the same field. $RFM_PREFIX is the usual way to keep stage, output and perflogs together. The configuration must name a shared prefix instead of /tmp. A portable test learns the node via processor.num_cpus. A test that writes num_tasks = 128 hardcodes this cluster. A test that asks the partition for its CPU count does not hardcode the cluster. A portable test leaves the machine in the config as that hook. max_jobs is the partition’s concurrency cap for the asynchronous policy. Eight is a starting number to measure from. A site that shares a QoS with users sets this from the QoS instead of a tutorial.

Features, extras and the filter syntax

Partitions or environments declare features, a list of tags. Partitions or environments declare extras, a key/value map. Tests request them from valid_systems and valid_prog_environs.

valid_systems = ['+gpu -login %arch=zen2']
valid_prog_environs = ['+foss', '+intel']

Three environment variables

EESSI recommends these rather than repeating flags.

Variable	Flag it replaces	What it names
RFM_CONFIG_FILES	-C / --config-file	the site configuration
RFM_CHECK_SEARCH_PATH	-c	where the tests live
$RFM_PREFIX	--prefix	stage, output, logs, perflogs

The dollar on the third is deliberate in EESSI’s prose. They warn against the command-line --prefix. The environment variable is set once, in the same place the modules tool is initialised. ReFrame 4.3.3 and later, with the common EESSI logging configuration, then writes.

• The debug log is written at $RFM_PREFIX/logs/reframe_<date>_<time>.log.

• Stage files are written at $RFM_PREFIX/stage/<system>/<partition>/<environ>/.

• Output files are written at $RFM_PREFIX/output/<system>/<partition>/<environ>/.

• Perflogs are written at $RFM_PREFIX/perflogs/<system>/<partition>/<environ>/.

A site that sets the three variables has a ReFrame invocation that is just reframe -l or reframe -r. A cron job and a human can both remember that.

EB-ReFrame-41-1 — What belongs where

A colleague’s STREAM test contains num_tasks = 128 and valid_systems = ['snellius:cpu']. The configuration for the new machine has a cpu partition with num_cpus: 64. Which two lines move, and which file do they move to?

Solution

valid_systems stays in the test. It becomes ['*'] (or a feature request, or the new system’s name), not a hostname bound to one cluster. ['.*'] is the hostname regex, not the test filter. num_tasks = 128 leaves the test entirely: 128 is a fact about Snellius, so it belongs in that site’s configuration as processor.num_cpus, and the test reads it from the partition in a hook. Leaving 128 in the test on a 64-core node oversubscribes the node; leaving snellius:cpu in the test means the new machine never schedules it.

sourcesWhere this page comes from

ReFrame 4.10 tutorial, the configuration section, and the configuration reference: systems, partitions, environments, features, extras, max_jobs. The builtin configuration is always loaded.

EESSI test-suite documentation, fetched 2026-09-11: installation and configuration, the configuration file, and the RFM_* variables. CSCS’s layout is config/cscs.py plus checks/ in eth-cscs/cscs-reframe-tests.

What to remember

• The test describes what to run. The configuration describes where. A core count written in the test is a core count on one machine.

• The builtin configuration always defines generic:default and builtin. A site file adds to it.

• A partition is a scheduler, a launcher and a list of environments. valid_systems matches system:partition.

• RFM_CONFIG_FILES, RFM_CHECK_SEARCH_PATH and $RFM_PREFIX are the three variables a site sets once.