Package Manager: Installing Optional Components
***********************************************

This guide describes how to install optional components of the
Amsterdam Modeling Suite. To reduce the initial download size, the
Amsterdam Modeling Suite does not include all components by default.
This includes features such as

* the Ligand Field DFT atomic database

* the COSMO-RS compound Database

* Quantum ESPRESSO

* Machine Learning potential engines

A full list of packages is available in the FAQ section below.

If the appropriate license is present, these optional components can
be installed through the GUI or the command line. The easiest way
requires an active internet connection, but it is also possible to use
a local copy of our repository downloaded ahead of time. These
instructions assume that you have already successfully installed AMS.

Note:

  AMSpackages behavior changed significantly in AMS2026. This page
  describes the package manager for AMS2026 and later. If you are
  using AMS2025 or an older release, see the documentation for
  previous AMS versions.


What's new
==========

New in version AMS2026.101:

* The default behavior of AMSpackages now installs packages for all
  users.

* The default location for shared packages is now inside "AMSHOME" on
  all platforms.

* A "--single-user"/"-u" flag was added to fall back to the old per-
  user behavior.

The general installation procedure should be simpler, especially for
shared installations. This page now covers the recommended way to
install optional AMS components. Use it for standard installs
(GUI/CLI), and first-line troubleshooting. For advanced configuration
and full command reference, see Appendix D: Advanced package manager
usage.


Breakdown
=========

There are two different install modes:

* **Admin mode (recommended):** Use this when you can write to
  "AMSHOME".

* **Single-user mode:** Use this when you are not allowed to write to
  "AMSHOME".

AMSpackages automatically selects admin mode if you are allowed to
write to "AMSHOME". Otherwise, it falls back to single-user mode.


Recommended Installation
========================

For most users and shared installations, admin mode is recommended:
packages are installed in "AMSHOME", keeping one managed package set
for all users. If "AMSHOME" is not writable, the package manager
defaults to single-user mode.


Pre-checks
----------

Before installing, confirm:

* Your AMS license includes the package(s) you want.

* You have write permissions to "AMSHOME" if you use admin mode.

* The machine can access the package repository (for online installs).


GUI users
---------

In AMSjobs, open SCM -> Packages. The package manager defaults to
admin mode if you have permission to modify "AMSHOME". Otherwise, it
falls back to single-user mode. You can see the active mode in the
AMSpackages window. You can use the GUI to search for the packages you
need, select and install them. It will also show you which packages
are already installed and if there are any updates.

You can find more GUI details in the AMSpackages GUI section of the
documentation.


Command-line users
------------------

When installing packages:

   "${AMSBIN}/amspackages" install lfdft

This installs into "AMSHOME" by default, unless that location is not
writable.

Typical CLI flow is: view available packages, install, and verify:

   "${AMSBIN}/amspackages" list
   "${AMSBIN}/amspackages" install lfdft
   "${AMSBIN}/amspackages" check lfdft && echo "lfdft was installed!"


Single-user mode
----------------

Single-user mode is only recommended when you are not allowed to write
to "AMSHOME". It will be enabled by default if this is the case. If
you want to force single-user mode, you can use the "-u" flag.

   "${AMSBIN}/amspackages" -u install lfdft


Copy-paste commands
-------------------

Use these commands as a quick start:

   # Install one package in default mode
   "${AMSBIN}/amspackages" install lfdft

   # Install multiple packages in default mode
   "${AMSBIN}/amspackages" install lfdft qe

   # Check whether a package is installed
   "${AMSBIN}/amspackages" check lfdft

   # Show install location for a package
   "${AMSBIN}/amspackages" loc lfdft


Offline Usage Guide
===================

Offline or mirrored package installs are useful, for example:

* when the target system cannot access the internet directly

* when computers are behind a firewall

* when you want to reuse one prepared local repository for repeated
  installations

Offline installs are detected automatically when the "AMSHOME"
installation contains a folder named "repository" with "AMS2026.1.yml"
at its top level.

AMSpackages detects and uses it without extra flags in that common
case.

Local mirrors can be prepared with "amsrepomirror", a separate tool
for mirroring the SCM package repository. If you do not use that tool,
a mirror can also be prepared manually.

To verify this on the command line:

   "${AMSBIN}/amspackages" list

In the output header, verify that "Repository:" points to your local
mirror location.

For instructions on creating or updating a local mirror, see Appendix
E: Mirroring the SCM package repository. For advanced repository
configuration in AMSpackages itself, see Appendix D: Advanced package
manager usage.


FAQ and Troubleshooting
=======================


What packages are available?
----------------------------

At the time of writing, the following packages are available:


Available AMSpackages
^^^^^^^^^^^^^^^^^^^^^

+-----------------------------------+-----------------------------------+-----------------------------------+
| Package name                      | Package ID                        | Available version                 |
|===================================|===================================|===================================|
| ADFCRS-2018 Database              | adfcrs                            | 2018: build 5                     |
+-----------------------------------+-----------------------------------+-----------------------------------+
| AIMNet2 Environment (CPU Only)    | aimnet2-cpu                       | 1.0.0: build 1207                 |
+-----------------------------------+-----------------------------------+-----------------------------------+
| AIMNet2 Environment (CUDA 12.8)   | aimnet2-cu128                     | 1.0.0: build 1207                 |
+-----------------------------------+-----------------------------------+-----------------------------------+
| FAIRChem Environment (CPU Only)   | fairchem-cpu                      | 1.0.0: build 1207                 |
+-----------------------------------+-----------------------------------+-----------------------------------+
| FAIRChem Environment (CUDA 12.8)  | fairchem-cu128                    | 1.0.0: build 1207                 |
+-----------------------------------+-----------------------------------+-----------------------------------+
| Infretis Environment              | infretis                          | 1.0.0: build 1207                 |
+-----------------------------------+-----------------------------------+-----------------------------------+
| LFDFT atomic database             | lfdft                             | 1.0: build 0                      |
+-----------------------------------+-----------------------------------+-----------------------------------+
| M3GNet Environment                | m3gnet                            | 1.0.0: build 1207                 |
+-----------------------------------+-----------------------------------+-----------------------------------+
| MACE Environment (CPU Only)       | mace-cpu                          | 1.0.0: build 1207                 |
+-----------------------------------+-----------------------------------+-----------------------------------+
| MACE Environment (CUDA 12.8)      | mace-cu128                        | 1.0.0: build 1207                 |
+-----------------------------------+-----------------------------------+-----------------------------------+
| Subgraph Sigma Profile Estimation | molsg_sg1db                       | 1.0: build 3                      |
| (SG1) Database                    |                                   |                                   |
+-----------------------------------+-----------------------------------+-----------------------------------+
| NequIP Environment (CPU Only)     | nequip-cpu                        | 1.0.0: build 1207                 |
+-----------------------------------+-----------------------------------+-----------------------------------+
| NequIP Environment (CUDA 12.8)    | nequip-cu128                      | 1.0.0: build 1207                 |
+-----------------------------------+-----------------------------------+-----------------------------------+
| OLED material database            | oledmatdb                         | 2023.1: build 2                   |
+-----------------------------------+-----------------------------------+-----------------------------------+
| Quantum ESPRESSO (AMSPIPE)        | qe                                | 7.1: build 206                    |
+-----------------------------------+-----------------------------------+-----------------------------------+
| TorchANI Environment (CPU Only)   | torchani-cpu                      | 1.0.0: build 1207                 |
+-----------------------------------+-----------------------------------+-----------------------------------+
| TorchANI Environment (CUDA 12.8)  | torchani-cu128                    | 1.0.0: build 1207                 |
+-----------------------------------+-----------------------------------+-----------------------------------+
| Zacros-post                       | zacros_post                       | 1.02: build 2                     |
+-----------------------------------+-----------------------------------+-----------------------------------+


What are the most common pitfalls?
----------------------------------

The most common installation problems are:

* Assuming a default install is always shared/admin mode. If "AMSHOME"
  is not writable, AMSpackages falls back to single-user mode.

* Trying to install a package that is not included in your license.

* Trying an online install from a machine behind a firewall or without
  internet access. In that case, prepare a local mirror and follow the
  offline setup described above.


Install failed / permission denied
----------------------------------

If installation fails with a permission error, verify whether you are
installing in admin mode. Admin mode requires write permissions to
"AMSHOME". If you cannot get write access, rerun the installation in
single-user mode with "-u" or "--single-user".


Package not found
-----------------

If a package does not appear in ""${AMSBIN}/amspackages" list", check
that:

* The package is included in your license.

* You are using the correct AMS version and repository.

* You are not accidentally using an outdated local offline mirror.


Offline repo not detected
-------------------------

Make sure the folder name is exactly "repository" and that
"AMS2026.1.yml" is directly inside that folder. The "repository"
folder must be inside "AMSHOME" for automatic detection. Then rerun:

   "${AMSBIN}/amspackages" list

and verify that the "Repository:" line points to your local mirror.
Alternatively, you can export the "SCM_AMSPKGS_REPO" variable to point
to the "AMS2026.1.yml" file in an alternative location.


The package manager exits with "Unhandled exception..."
-------------------------------------------------------

The package manager has encountered an unexpected error. To see more
information, the command-line version of AMSpackages has a "--verbose"
option. Using this flag twice yields extra debug output ("-vv"), which
may include more information about the error.

Some errors may disappear after running "amspackages clean" on the
command line. If errors persist, please contact SCM support and
include logs.

Note:

  If you face problems with the package manager, please include the
  log file in your support ticket. The log file is called
  "amspackages.log" and is located under:

  * Linux: "$HOME/.scm/packages/amspackages.log"

  * MacOS: "$HOME/Library/Application
    Support/SCM/packages/amspackages.log"

  * Windows: "%LOCALAPPDATA%/SCM/packages/amspackages.log"

  Alternatively, run the command below and send "debug_info.txt":
  "$AMSBIN/amspackages debug > debug_info.txt"


Where are packages installed?
-----------------------------

By default, AMSpackages will attempt to install packages inside of
"AMSHOME".

In admin mode, packages are installed in the shared installation
inside "AMSHOME" by default.

In single-user mode, AMSpackages uses the following default locations:

* Linux: "$HOME/.scm/packages"

* MacOS: "$HOME/Library/Application Support/SCM/packages"

* Windows: "%LOCALAPPDATA%/SCM/packages"

Every version of AMS has its own dedicated folder inside the
"packages" directory, to allow different installations to appear side-
by-side. Packages themselves are located in uniquely named
subdirectories. If you need the location of a specific package, use:

   "${AMSBIN}/amspackages" loc lfdft

The single-user default location can be changed using
"SCM_AMSPKGS_USERDIR". The shared admin location can be changed using
"SCM_AMSPKGS_SHAREDDIR".


Need more control?
==================

For advanced usage, see Appendix D: Advanced package manager usage,
including:

* advanced CLI commands (install/update/remove and full options)

* persistent configuration and environment variables

* advanced offline mirror creation methods

* admin Python package management details
