.. _running:

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:

.. code-block:: bash

   conda activate arc_env

Run from YAML
-------------

Create an ``input.yml``:

.. code-block:: yaml

   project: ethanol_demo

   species:
     - label: ethanol
       smiles: CCO

Run it from the repository checkout:

.. code-block:: bash

   python ARC.py input.yml

Or from elsewhere:

.. code-block:: bash

   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 :ref:`arc.main.ARC <main>` are legal top-level input file
keywords. Entries under ``species`` and ``reactions`` define
:ref:`ARCSpecies <species>` and :ref:`ARCReaction <reaction>` objects. See
:ref:`input_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:

.. code-block:: bash

   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:

.. code-block:: python

   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.

__ jupyter_

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.

.. code-block:: python

   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')``:

.. code-block:: bash

   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:

.. code-block:: python

   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`` and ``un``, then
route ESS names to those servers:

.. code-block:: python

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

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

With no ``key`` in the entry, ARC authenticates through a running ssh-agent and
then through the default key paths, so ``ssh-add ~/.ssh/id_ed25519`` is all that is
needed. To point at a specific private key instead, add
``'key': '/home/my_user/.ssh/id_ed25519'``; the path is read on the machine running
ARC and must name the private key.

A host that is absent from ``~/.ssh/known_hosts`` is warned about but still
connected to. Add ``'strict_host_key_checking': True`` to a server entry to refuse
unknown hosts instead. ARC names every such server at startup, before it submits
anything, together with the ``ssh-keyscan`` command that seeds the missing key.

ARC does not read ``~/.ssh/config``, so every connection detail has to be given in
the server entry, and jump hosts (``ProxyJump``/``ProxyCommand``) are not supported.

See :ref:`remote_submission` for authentication, host key verification, and remote
submission from the Docker image.

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:

.. code-block:: bash

   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.

.. include:: links.txt