Quick Start

mache (Machines for E3SM) is a package for providing configuration data related to E3SM supported machines.

Installing mache

You can install the latest release of mache from conda-forge:

conda config --add channels conda-forge
conda config --set channel_priority strict
conda install mache

Example usage

#!/usr/bin/env python
from mache import MachineInfo, discover_machine

machine_info = MachineInfo()
print(machine_info)
diags_base = machine_info.config.get('diagnostics', 'base_path')
machine = discover_machine()

This loads machine info for the current machine, prints it, and retrieves a config option specific to that machine. The mache.discover_machine() function can also be used to detect which machine you are on.

As an example, the result of print(machine_info) is:

Machine: chrysalis
  E3SM Supported Machine: True
  Compilers: intel, gnu
  MPI libraries: impi, openmpi, mvapich
  OS: LINUX

E3SM-Unified:
  E3SM-Unified is not currently loaded
  Base path: /lcrc/soft/climate/e3sm-unified

Diagnostics:
  Base path: /lcrc/group/e3sm/diagnostics

Config options:
  [e3sm_unified]
    group = cels
    compiler = intel
    mpi = impi
    base_path = /lcrc/soft/climate/e3sm-unified

  [diagnostics]
    base_path = /lcrc/group/e3sm/diagnostics

  [web_portal]
    base_path = /lcrc/group/e3sm/public_html
    base_url = https://web.lcrc.anl.gov/public/e3sm/

  [parallel]
    system = slurm
    parallel_executable = srun
    cores_per_node = 36
    account = condo
    partitions = acme-small, acme-medium, acme-large
    qos = regular, acme_high

If you are on the login node of one of the following E3SM supported machines, you don’t need to provide the machine name. It can be discovered automatically:

andes
aurora
chrysalis
chicoma-cpu
compy
dane
frontier
pm-cpu
polaris

If you are on a compute node or want info about a machine you’re not currently on, give the machine name in all lowercase.

Public Functions

The following public functions are available in the top-level mache package:

mache.MachineInfo: Class for querying machine-specific configuration and capabilities.
mache.discover_machine(): Function to detect the current machine name.

MachineInfo attributes

machine: Name of the E3SM supported machine.
config: ConfigParser object with machine-specific options.
e3sm_supported: Whether this machine supports running E3SM.
compilers: List of compilers for this machine.
mpilibs: List of MPI libraries for this machine.
os: The machine’s operating system.
e3sm_unified_mpi: Which MPI type is included in the E3SM-Unified environment.
e3sm_unified_base: Base path for E3SM-Unified and activation scripts.
e3sm_unified_activation: Activation script for E3SM-Unified.
diagnostics_base: Base directory for diagnostics data.
inputdata_base: Base directory for E3SM inputdata.
web_portal_base: Base directory for the web portal.
web_portal_url: Base URL for the web portal.
username: The current user’s name.

Additional utilities

mache.machines.get_supported_machines(): Returns a sorted list of supported machine names.
mache.io.download_file(): Download a file from a URL to a local path.

For more details on these and other features, see the full user’s guide.

JIGSAW note

Most users will not run mache jigsaw install directly. In downstream software repositories, mache deployment is typically invoked from a top-level ./deploy.py script, and that workflow may install jigsawpy as part of deployment when configured by that software.

For advanced/manual JIGSAW usage details, see the dedicated user guide page: JIGSAW.