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

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:

Table 1 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 224
AIMNet2 Environment (CUDA 12.8)	aimnet2-cu128	1.0.0: build 224
Amsterdam Modeling PySuite Environment	amsterdam-modeling-pysuite	1.0: build 224
FAIRChem Environment (CPU Only)	fairchem-cpu	1.0.0: build 224
FAIRChem Environment (CUDA 12.8)	fairchem-cu128	1.0.0: build 224
Infretis Environment	infretis	1.0.0: build 224
LFDFT atomic database	lfdft	1.0: build 0
M3GNet Environment	m3gnet	1.0.0: build 224
MACE Environment (CPU Only)	mace-cpu	1.0.0: build 224
MACE Environment (CUDA 12.8)	mace-cu128	1.0.0: build 224
Subgraph Sigma Profile Estimation (SG1) Database	molsg_sg1db	1.0: build 3
NequIP Environment (CPU Only)	nequip-cpu	1.0.0: build 224
NequIP Environment (CUDA 12.8)	nequip-cu128	1.0.0: build 224
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 224
TorchANI Environment (CUDA 12.8)	torchani-cu128	1.0.0: build 224
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