Documentation of modules

Extra functionality for reframe

modules.reframe_extras.patch_launcher_command(job)

Patch the job launcher command for mpirun and mpiexec. We remove -np/-n arguments as we pass them manually inside ReFrame test

modules.reframe_extras.patch_job_names(job, stagedir)

Patch the job name, stdout and stderr to remove special characters injected by fixtures

class modules.reframe_extras.CachedRunTest(*args, **kwargs)

Mixin.

Classes using this can be derive from rfm.RunOnlyRegressionTest Assumes saved output files are in a directory cache/ in same parent directory (and with same directory tree) as the output/ and stage/ directories.

set self.use_cache to True or a path relative to cwd.

NB Any class using this MUST NOT change self.executable in a method decorated with @rfm.run_before('run') as that will override functionality here.

no_run()

Turn the run phase into a no-op

copy_saved_output()

Copy saved output files to stage dir.

class modules.reframe_extras.CachedCompileOnlyTest(*args, **kwargs)

A compile-only test with caching of binaries between reframe runs.

Test classes derived from this class will save self.executable to a ./builds/{system}/{partition}/{environment}/{self.name} directory after compilation. However if this path (including the filename) exists before compilation (i.e. on the next run):

• No compilation occurs

• self.sourcesdir is set to this directory, so reframe will copy the

  binary to the staging dir (as if compilation had occured)

• A new attribute self.build_path is set to this path (otherwise None)

Note that self.sourcesdir is only manipulated if no compilation occurs, so compilation test-cases which modify this to specify the source directory should be fine.

conditional_compile()

Point sourcedir to build_dir if it exists

copy_executable()

Copy executables to build_dir if it compiles

class modules.reframe_extras.NoBuild(*args, **kwargs)

A no-op build system

class modules.reframe_extras.CachedGitCloneTest(*args, **kwargs)

A git clone-only test with caching between the reframe runs.

This test clones the git repository and copies the repository to $PWD/src folder on the first run. Once the $PWD/src is there with repository inside it, it simply sets this directory as self.sourcesdir so new cloning is avoided for the next run.

If a new clone is needed the user simply need to remove $PWD/src before running reframe.

We need to set few variables for this test to work

• repo_name: Name of the repository

• repo_url: URL of git repository

check_req_variables()

Check essential variables if they are defined

set_sources()

Set source dir

set_executable()

Set a noop exe

copy_sources_to_cache()

Copy sources to cache dir

class modules.reframe_extras.FetchSourcesBase(*args, **kwargs)

Fixture to fetch source code

set_conda_prerun_cmds()

Emit conda env prerun commands

set_sanity_patterns()

Set sanity patterns

class modules.reframe_extras.PerfmonMixin(*args, **kwargs)

create_perfmetrics_dir()

Create a dir for storing perfmetrics

create_fake_job_id_local_scheduler()

If scheduler is local, make a fake job ID

patch_job_launcher()

Monkey mock the job launcher command

get_scheduler_env_vars()

Get scheduler specific env variables

export_env_variables()

Make a string of env variables that will be exported to all nodes

get_mpi_launcher_cmd()

Get MPI launcher command with additional options

set_postrun_cmds()

Set postrun commands

class modules.reframe_extras.MultiRunMixin(*args, **kwargs)

This mixin creates a uniquely identifiable ID for tests that are run multiple times. Over all tests that are run with one reframe call, this yields the same unique key.

class modules.reframe_extras.AppBase(*args, **kwargs)

A base test class that includes common methods for application reframe tests.

This base class defines several methods that are common to different reframe tests

property num_tasks_assigned

Get number of job tasks

property run_command_emitted

Get job run command

get_max_nodes_partition()

Get maximum number of available nodes in partition

check_test_feasibility()

Check if test is feasible based on number of nodes requested

set_num_tasks_reservation()

Set number of tasks for job reservation

set_git_commit_tag()

Get git commit hash

class modules.reframe_extras.SpackBase(*args, **kwargs)

A base class that includes common methods for deploying software stack using Spack

check_cluster_var()

Checks if cluster name is valid and skips the test if not

check_build_cache()

Checks if mirror name is defined if build cache is provided

set_keep_files()

Keep spack config file in output

export_spack_root()

Modify .bashrc to export SPACK_ROOT env variable

apply_patch()

Apply patches to Spack

emit_spack_installation_cmds()

Commands to check if Spack is installed on the host

set_num_tasks()

Reserve all cores on the node if job is remote

emit_spack_add_mirror_cmds()

Commands to add mirrors to spack if build cache is found

emit_spack_env_rm_cmds()

Commands to removes Spack env if already exists

merge_spack_configs()

Merge all seperate Spack config files into spack.yaml and place it stage dir

emit_spack_env_create_cmds()

Commands to create spack env

get_sys_compiler()

Read system compiler from config files

emit_compiler_install_cmds()

Commands to install GCC 9.3.0 and Intel 2021.4.0 and adds to compiler.yml

set_local_launcher()

Set launcher to be local

set_executable()

Set executable and options

set_postrun_cmds()

Set post run commands that generate module files

set_sanity_patterns()

Set sanity patterns

modules.reframe_extras.slurm_node_info(partition=None)

Get information about slurm nodes. Returns a sequence of dicts, one per node with keys/values all strs as follows:

• “NODELIST”: name of node

• “NODES”: number of nodes

• “PARTITION”: name of partition, * appended if default

• “STATE”: e.g. “idle”

• “CPUS”: str number of cpus

• “S:C:T”: Extended processor information: number of sockets, cores, threads in format “S:C:T”

• “MEMORY”: Size of memory in megabytes

• “TMP_DISK”: Size of temporary disk space in megabytes

• “WEIGHT”: Scheduling weight of the node

• “AVAIL_FE”: ?

• “REASON”: The reason a node is unavailable (down, drained, or draining states) or “none”

See man sinfo for sinfo --Node --long for full details.

Parameters

partition (str) – Name of slurm partition to query, else information for all partitions is returned.

Returns

nodes

Return type

list

modules.reframe_extras.hostlist_to_hostnames(s)

Convert a Slurm ‘hostlist expression’ to a list of individual node names. Uses scontrol command.

Parameters

s (str) – Host list

Returns

Hostnames

Return type

list

class modules.reframe_extras.SchedulerInfo(rfm_partition, exclude_states=None, only_states=None)

Information from the scheduler.

The returned object has attributes:

• num_nodes: number of nodes

• sockets_per_node: number of sockets per node

• pcores_per_node: number of physical cores per node

• lcores_per_node: number of logical cores per node

If rfm_partition is None the above attributes describe the default scheduler partition. Otherwise the following sbatch directives in the access property of the ReFrame partition will affect the information returned:

• --partition

• --exclude

Parameters

• rfm_partition – reframe.core.systems.SystemPartition

• exclude_states – sequence of str, exclude nodes in these Slurm node states

• only_states – sequence of str, only include nodes in these Slurm node states

slurm_info()

Get SLURM scheduler info

oar_info()

Get OAR scheduler info

local_info()

Get info when scheduler is local

Utility functions for SDP benchmark tests

class modules.utils.GenerateHplConfig(num_nodes, num_procs, nb, mem, alpha=0.8)

Class to generate HPL.dat file for LINPACK benchmark

estimate_n()

Estimate N based on memory and alpha

estimate_pq()

Get best combination of P and Q based on nprocs

get_config()

Write HPL.dat file to outfile location

modules.utils.sdp_benchmark_tests_root()

Returns the root directory of SKA SDP Benchmark tests

Returns

Path of the root directory

Return type

str

modules.utils.parse_path_metadata(path)

Return a dict of reframe info from a results path

Parameters

path – ReFrame stage/output path

Returns

ReFrame system/partition info

Return type

dict

modules.utils.find_perf_logs(root, benchmark)

Get perflog file names for given test

Parameters

• root – Root where perflogs exist

• benchmark – Name of the benchmark

Returns

List of perflog file names

Return type

list

modules.utils.read_perflog(path)

Return a pandas dataframe from a ReFrame performance log. NB: This currently depends on having a non-default handlers_perflog.filelog.format in reframe’s configuration. See code. The returned dataframe will have columns for:

• all keys returned by parse_path_metadata()

• all fields in a performance log record, noting that: - ‘completion_time’ is converted to a datetime.datetime - ‘tags’ is split on commas into a list of strs

• ‘perf_var’ and ‘perf_value’, derived from ‘perf_info’ field

• <key> for any tags of the format “<key>=<value>”, with values converted to int or float if possible

Parameters

path (str) – Path to log file

Returns

Dataframe of perflogs

Return type

pandas.DataFrame

modules.utils.load_perf_logs(root='.', test=None, extras=None, last=False, aggregate_multi_runs=<function median>)

Convenience wrapper around read_perflog().

Parameters

• root (str) – Path to root of tree containing perf logs

• test (str) – Shell-style glob pattern matched against last directory component to restrict loaded logs, or None to load all in tree

• extras (list) – Additional dataframe headers to add

• last (bool) – True to only return the most-recent record for each system/partition/enviroment/testname/perf_var combination.

• aggregate_multi_runs (Callable) – How to aggregate the perf-values of multiple runs. If None, no aggregation is applied. Defaults to np.median

Returns

Single pandas.dataframe concatenated from all loaded logs, or None if no logs exist

Return type

pandas.DataFrame

modules.utils.tabulate_last_perf(test, root='../../perflogs', extras=None, **kwargs)

Retrieve last perf_log entry for each system/partition/environment.

Parameters

• test (str) – Shell-style glob pattern matched against last directory component to restrict loaded logs, or None to load all in tree

• root (str) – Path to root of tree containing perf logs of interest - default assumes this is called from an apps/<application>/ directory

• extras (list) – Additional dataframe headers to add

Returns

A dataframe with columns: - case: name of the system, partition and environ - perf_var: Performance variable - add_var: Any additional variable passed as argument

Return type

pandas.DataFrame

modules.utils.tabulate_partitions(root)

Tabulate the list of partitions defined with ReFrame config file and high level overview of each partition. We tabulate only partitions that are found in the perflog directory

Parameters

root (str) – Perflog root directory

Returns

A dataframe with all partition details

Return type

pandas.DataFrame

modules.utils.filter_systems_by_name(patterns)

Filter systems based on patterns in the name. If all patterns are found in the name, the system is chosen.

Parameters

patterns (list) – List of patterns to be searched

Returns

List of partitions that match the pattern

Return type

list

modules.utils.filter_systems_by_env(envs)

Filter systems based on valid environments defined for them.

Parameters

envs (list) – List of environments to be searched

Returns

List of partitions that match the envs

Return type

list

modules.utils.git_describe(dir)

Return a string describing the state of the git repo in which the dir is. See git describe –dirty –always for full details.

Parameters

dir (str) – Root path of git repo

Returns

Git describe output

Return type

str

modules.utils.generate_random_number(n)

Generate random integer of n digits

Parameters

n (int) – Length of the desired random number

Returns

Generated random number

Return type

int

modules.utils.get_scheduler_env_list(scheduler_name)

Return the environment variables that stores different job details of different schedulers

Parameters

scheduler_name (str) – Name of the workload scheduler

Returns

Environment variables dict

Return type

dict

modules.utils.emit_conda_init_cmds()

This function emits the command to initialize conda.

modules.utils.emit_conda_env_cmds(env_name, py_ver='3.8')

This function emits all the commands to create/activate a conda environment. This function assumes conda is installed in the system

Parameters

• env_name (str) – Name of the conda env to create/activate

• py_ver (str) – Version of python to be used in conda environment (Default: 3.8)

Returns

List of commands to create/activate conda env

Return type

list

modules.utils.merge_spack_configs(input_file, output_file)

This function merges all spack config files by replacing include keyword with respective yaml file

Parameters

• input_file – Path to input spack.yaml file

• output_file – Path to output merged spack.yaml file

Returns

None