Running ARC

ARC can be run from a YAML input file, from Python, or from notebooks. The same configuration concepts apply in all modes: define species and reactions, choose job types and levels of theory, and map electronic structure software to local or remote compute resources.

Activate ARC First

Use arc_env for development and execution:

conda activate arc_env

Run from YAML

Create an input.yml:

project: ethanol_demo

species:
  - label: ethanol
    smiles: CCO

Run it from the repository checkout:

python ARC.py input.yml

Or from elsewhere:

python /path/to/ARC/ARC.py /path/to/input.yml

ARC writes project files under Projects/<project> by default unless project_directory is supplied. All parameters of arc.main.ARC are legal top-level input file keywords. Entries under species and reactions define ARCSpecies and ARCReaction objects. See Input YAML Reference for the full input-key checklist.

Restart a Project

ARC writes restart.yml files that contain the current state of the project, including submitted jobs. To restart, run ARC with the restart file:

python /path/to/ARC/ARC.py restart.yml

In restart mode, ARC can collect finished jobs, keep waiting for jobs that are still running, and continue work that was not completed.

Run from Python

Use the Python API when you want to generate inputs programmatically, integrate ARC into scripts, or work in a notebook:

from arc import ARC
from arc.species import ARCSpecies

ethanol = ARCSpecies(label='ethanol', smiles='CCO')

arc = ARC(
    project='ethanol_api_demo',
    species=[ethanol],
    job_types={
        'conf_opt': True,
        'opt': True,
        'fine': True,
        'freq': True,
        'sp': True,
        'rotors': True,
    },
    level_of_theory='wb97xd/def2svp',
    ess_settings={'gaussian': 'local'},
)

arc.execute()

ARC also accepts species and reaction dictionaries, so YAML-style inputs can be converted into API calls without manually constructing every object.

Running ARC in Jupyter notebooks (which come pre-installed with Anaconda) has the added benefit of displaying “live” and interactive 3D geometries for the species of interest.

Run Locally

Use local mode when ARC and the relevant electronic structure software are on the same machine or cluster login environment. Configure servers with the reserved local key and route software to local: Here, local means ARC does not use SSH for that server. The job is still submitted using the configured scheduler and submit template.

servers = {
    'local': {
        'cluster_soft': 'Slurm',
        'un': 'my_user',
    },
}

global_ess_settings = {
    'gaussian': 'local',
    'orca': 'local',
    'xtb': 'local',
}

Run PySCF In-Core (Queueless)

PySCF is supported as a local, in-core ESS: ARC calls it in-process on the machine ARC runs on, with no external scheduler. This is aimed at workstations that have no queueing system.

Install PySCF into its dedicated pyscf_env environment with the bundled script (also wired into devtools/install_all.sh). ARC discovers the environment via find_executable('pyscf_env'):

bash devtools/install_pyscf.sh            # CPU baseline
bash devtools/install_pyscf.sh --cuda     # additionally install the gpu4pyscf GPU stack

To run PySCF jobs, set the reserved local server’s cluster_soft to 'local' (no queue) and route pyscf to it. When cluster_soft is 'local', the server’s cpus is a single machine-wide CPU budget: it caps the cores any one in-core job may use and bounds the local worker pool. Set it below the physical core count to leave headroom:

servers = {
    'local': {
        'cluster_soft': 'local',   # no queueing system
        'un': 'my_user',
        'cpus': 12,                # machine-wide CPU budget (e.g. on a 16-core box)
    },
}

global_ess_settings = {
    'pyscf': 'local',
}

Supported job types are single-point energy (sp), geometry optimization (opt), and frequencies (freq). A few things to know:

  • GPU: after installing with --cuda, select the GPU globally by setting PYSCF_DEVICE = 'gpu' in settings.py, or per job via the args keyword {'keyword': {'device': 'gpu'}}. The GPU stack (gpu4pyscf) is pinned to a version that avoids a known upstream Hessian regression, so GPU freq jobs are supported.

  • Method and basis always come from the job’s level of theory. If an args keyword tries to set a conflicting method or basis, it is ignored (with a warning) so the computed result matches the level ARC records.

  • If a PySCF job is ever routed to a queue, it transparently falls back to in-core execution.

Run over SSH

Use SSH mode when ARC runs on your workstation but submits jobs on one or more remote servers. Configure each remote server with address, un, and key, then route ESS names to those servers:

servers = {
    'cluster_a': {
        'cluster_soft': 'Slurm',
        'address': 'login.cluster.edu',
        'un': 'my_user',
        'key': '/home/my_user/.ssh/id_rsa',
    },
}

global_ess_settings = {
    'gaussian': 'cluster_a',
    'molpro': 'cluster_a',
}

Run on HPC

On HPC systems, ARC usually runs on a login or workflow node and submits ESS jobs through the scheduler. The important site-specific pieces are:

  • cluster_soft in each server entry;

  • submit command paths in settings.py if the defaults do not match your site;

  • submit script templates in submit.py;

  • scratch paths, queue names, wall time, memory, and CPU limits.

Keep the scheduler template variables such as {memory}, {cpus}, {name}, and {input_file} intact so ARC can fill them at runtime.

Run Arkane Independently

ARC runs Arkane automatically for supported statmech workflows. You can also run Arkane directly:

conda run -n rmg_env python -m arkane input.py

For a source installation, make sure RMG_PY_PATH and RMG_DB_PATH point to valid checkouts before running Arkane.

See the Arkane documentation for input file details.