API reference

This page provides an auto-generated summary of the mache API. For more details and examples, refer to the relevant sections in the main part of the documentation.

discover

discover_machine([quiet, package, path])

Figure out the machine from the host name.

permissions

update_permissions(base_paths, group[, ...])

Update the group that a directory belongs to along with the "group" and "other" permissions for the directory

parallel

get_parallel_system(config)

SubmissionResolution(target, ...)	Resolved scheduler target and effective node count.
ParallelSystem(config)	Base class for parallel system resource management.
ParallelSystem.get_parallel_command(args, ntasks)	Get the parallel execution command for the current system.
ParallelSystem.get_scheduler_target(config, ...)	Choose queue/partition/qos metadata target for a node count.
ParallelSystem.resolve_submission(config, ...)	Resolve a scheduler target and effective node count.

LoginSystem(config)

Resource manager for login nodes (no parallel execution).

SingleNodeSystem(config)

Resource manager for single-node parallel execution.

SlurmSystem(config)	SLURM resource manager for parallel jobs.
SlurmSystem.get_slurm_options(config, nodes)	Get Slurm submission options for a requested node count.

PbsSystem(config)	PBS resource manager for parallel jobs.
PbsSystem.get_pbs_options(config, nodes[, ...])	Get PBS submission options for a requested node count.

spack

make_spack_env(spack_path, env_name, ...[, ...])	Clone the spack_for_mache_{{version}} branch from E3SM's spack clone and build a spack environment for the given machine, compiler and MPI library.
get_spack_script(spack_path, env_name, ...)	Build a snippet of a load script for the given spack environment
get_modules_env_vars_and_mpi_compilers(...)	Get the non-spack modules, environment variables and compiler names for a given machine, compiler and MPI library.
extract_machine_config(xml_file, machine, ...)	Extract the machine configuration from the XML file.
config_to_shell_script(config, shell_type)	Convert the machine configuration to a shell script.
extract_spack_from_config_machines(machine, ...)	Extract machine configuration from XML and write it to a shell script.
list_machine_compiler_mpilib()	List tuples of machine, compiler, and MPI library parsed from the name of YAML files in the mache.spack.templates directory.

sync

sync_diags(other[, direction, machine, ...])

Synchronize diagnostics files between supported machines

jigsaw

JigsawBuildResult(channel_uri, channel_dir, ...)
deploy_jigsawpy(*[, jigsaw_python_path, ...])	Build and install jigsawpy in one call.
build_jigsawpy_package(*, python_version, ...)	Build a local conda package for jigsawpy.
install_jigsawpy_package(*, channel_uri, ...)	Install jigsawpy from a local conda channel.
detect_install_backend(*[, backend])	Resolve the jigsaw installation backend.

add_jigsaw_subparser(subparsers)

Add the mache jigsaw command group to the top-level CLI.

deploy

check_call(commands, log_filename, quiet, *)	Wrapper for making a shell call with logging and error management.
build_pixi_shell_hook_prefix(*, pixi_exe, ...)	Build a shell prefix to activate a pixi env in the current shell.
check_location([software])	Ensure that the script is being run from the root of the target software repository.
install_dev_mache(pixi_shell_hook_prefix, ...)	Install mache from a fork and branch for development and testing
main()	Entry point for the configure script

add_deploy_subparser(subparsers)

CliArgSpec(flags, dest, route, kwargs)
CliSpec(meta, args)
parse_cli_spec(rendered_json, *[, source, ...])
merge_cli_specs(base, extra)
routes_include(arg, route)
filter_args_by_route(spec, route)
load_cli_spec_file()
load_repo_cli_spec_file([repo_root])
add_args_to_parser(parser, args)

get_conda_platform_and_system()

Get the conda system name ('linux' or 'osx') and platform (e.g. 'linux-64').

DeployContext(software, machine, repo_root, ...)	A small bundle of state passed to hook functions.
HookRegistry(file_path, entrypoints)	Resolved hooks for a single deploy run.
HookRegistry.run_hook(stage, context)	Run a hook stage if it is defined.
load_hooks(config, repo_root, logger)	Load deployment hooks from a target-software repository.
configparser_to_nested_dict(cfg)	Convert a ConfigParser to a JSON/YAML-friendly nested mapping.

init_or_update_repo(repo_root, software, ...)

Init: Create/refresh the deploy starter kit in a target-software repo.

define_square_bracket_environment()

Define a Jinja2 environment that uses square brackets for delimiters.

get_known_mache_machines(*[, package])	Return the set of machine names known to mache.
get_known_target_machines(*, machines_path)	Return the set of machine names provided by the target software.
get_known_machines(*[, machines_path])	Return the set of machines known to mache or the target software.
get_machine(*, requested_machine[, ...])	Get the selected machine.
get_machine_config(*, machine, ...[, quiet])	Load merged machine config from mache + (optional) target software.

run_deploy(args)

Run the full deployment workflow for the current project.

SpackDeployResult(compiler, mpi, env_name, ...)	Result of deploying a Spack environment for one toolchain pair.
SpackSoftwareEnvResult(compiler, mpi, ...)	Result of deploying a Spack "software" environment.
deploy_spack_envs(*, ctx, toolchain_pairs, ...)	Deploy one Spack environment per (compiler, mpi) toolchain pair.
deploy_spack_software_env(*, ctx, ...)	Deploy an optional Spack "software" environment.
load_existing_spack_envs(*, ctx, toolchain_pairs)	Load pre-existing Spack library environments for load scripts.
load_existing_spack_software_env(*, ctx)	Load a pre-existing Spack software environment for load scripts.

MachineInfo

MachineInfo([machine, quiet])	An object containing information about an E3SM supported machine
MachineInfo.get_account_defaults()	Get default account, partition and quality of service (QOS) for this machine.
MachineInfo.get_queue_specs()	Get queue policy metadata for the machine.
MachineInfo.get_partition_specs()	Get partition policy metadata for the machine.
MachineInfo.get_qos_specs()	Get quality-of-service (QOS) policy metadata for the machine.