Introduction
************

This document describes the installation of the Amsterdam Modeling
Suite (AMS).

* Quickstart instructions: Windows | Linux | MacOS

* Complete installation guide: Installation

* License information: Set up the license

AMS is bundled as a mostly complete package and all engines are
installed at once. **Your license file determines which of the
functionality will be available after installation**. Some optional
functionality can be installed afterwards, see Package Manager:
Installing Optional Components.

The AMS package is written with a Unix-like environment in mind, but
Unix/command-line knowledge is not needed install or use AMS from the
graphical user interface.

Installing AMS on a shared system, for example a Linux cluster, may
require you to edit shell configuration files such as ".bashrc".

For optimal performance, some system specific tuning may be needed.


Requirements
============


Summary
-------

AMS2026 can be used on anything from a simple laptop to big Linux
cluster environments, and is tested on a wide variety of hardware.

Recommended minimum hardware specification:

* Intel i5 or better 64bit CPU supporting AVX2 instructions

* 8GB RAM

* 250GB SSD

* OpenGL 3.2 graphics

Absolute minimum hardware specification:

* 64bit CPU supporting AVX2 instructions

* 2GB RAM

* 6GB storage for installation

* OpenGL 1.4 graphics

Note that for macOS, we only support Apple Silicon M1 processors and
newer, not Intel. On Windows and Linux ARM64 CPUs such as Qualcomm
Snapdragon are not supported at this time.

Supported Operating Systems:

* Windows 10/11

* macOS 13.2 or newer

* Linux with GLIBC v2.28 or higher, including: Rocky8/Alma8/RHEL8 or
  newer, Debian 10 or newer, SUSE 15.6 or newer, Ubuntu 20.04 or
  newer, etc. AMS is regularly tested on Almalinux 8, Ubuntu 24.04 and
  Arch Linux.

Specific hardware and software requirements for the AMS package depend
on the platform. The list of supported platforms, including
information on the operating system, parallel environment (MPI), and
compilers used is available in the Download section of our web site.


Detailed Hardware requirements
------------------------------

**CPU**

AMS2026 works on modern Intel CPUs with AVX2 or AVX-512 instruction
sets and AMD Zen CPUs (Ryzen, Threadripper, EPYC). Especially the AMD
Zen2/Zen3 processors give very good performance (Ryzen 3000/4000/5000,
EPYC 7**2/7**3). The macOS version of AMS2026 works on Apple Silicon
(arm64) processors. We no longer provide a binary for older intel
(x86) macOS systems. Note that AMS for Windows and Linux does not work
on arm64 processors, such as Qualcomm Snapdragon.

**Memory**

In a parallel calculation, the total amount of memory used by the job
is a sum of that used by each process. Starting from ADF2010, some
large chunks of data are placed in the shared memory so the sum rule
does not strictly hold. In principle, it is more correct to count
memory per process but since AMS is an MPI program it runs most
efficiently when the number of processes corresponds to the number of
physical processors cores. Therefore, all memory amounts below are per
processor core.

The amount of RAM per core needed to run AMS depends greatly on the
kind of calculation you perform. For small calculations, 256 MB will
be sufficient, but if there is a lot of memory available AMS may run
significantly faster. A large amount memory also reduces the load on
the disks, which may speed up your calculation depending on the I/O
sub-system and the operating system.

The memory requirement increases with the system size. For example,
for a molecule containing 100 atoms with a DZ basis set it may be
sufficient to have 256 MB but for a molecule with 1000 atoms up to 8
gigabytes may be required. Also, if you are going to perform TDDFT,
relativistic spin-orbit or analytical frequency calculations then the
amount of memory should be larger. As an indication, an analytical
vibrational frequency calculation of a organometallic complex
containing 105 atoms with a TZP basis set uses up to 1GB of RAM per
process but it can be done with less, even though not as efficiently.

**Disk**

For installation of the package on Linux/Unix you need from about 5GB
(without sources) to 8GB (with sources and compiled objects). The run-
time (scratch) disk space requirements greatly depend on what type of
calculation you perform. For the ADF engine, it may range from a few
megabytes for a small molecule up to a hundred gigabytes for a large
molecule with a large basis set, the amount scaling quadratically with
the system size. Using a Solid State Drive (SSD) helps performance,
especially for bigger calculations.

**Network**

First of all, a network card must be present in the computer as its
hardware MAC address is used as the computer's ID for the licensing.

In order to enable MPI on a standalone Windows computer, one may need
to create a dummy network connection by adding a network "card" called
Microsoft Loopback Adapter. This interface will be assigned an IP
address from a private range.

**Multi-host parallel performance.**

As far as performance concerned, a switched Gigabit Ethernet network
is typically sufficient for good parallel performance on up to four
nodes if the nodes do not have too many CPU cores per node. If you are
going to use more nodes, or nodes with high core count (>16 cores per
node), you may need faster communication hardware, such as Infiniband,
to get good performance. Please note that multi-host execution is not
supported on Windows.

**Graphics**

The AMS GUI requires OpenGL 3.2 to run. For Linux and Windows users
there is an OpenGL software mode available for older hardware, please
read more about it in the Remote GUI documentation.


Software requirements
---------------------

**Operating System**

The package runs on Windows and on the following Unix variants: Linux,
Mac OS.

On the Apple systems the macOS 13.2 (Ventura) and newer is supported
on Apple Silicon hardware.

On linux both the compute engines, python scripting environment and
GUI require a GLIBC version of 2.28 or higher. The main binaries of
AMS are compiled on CentOS 7, the code gets tested daily on Almalinux
8, Ubuntu 22.04 and Arch.

The Windows version of AMS is supported on the desktop editions of
Windows (10 and 11). The Windows Server is **not** supported.

**Additional libraries**

Certain version of AMS will require different libraries to be
installed on the system depending on the MPI library used.

**Graphics**

In order to run the the graphical user interface (GUI) the computer
needs to have an OpenGL-capable graphics subsystem (hardware, drivers
and libraries). Besides that, on Linux the following (or equivalent)
packages must be installed:

   fontconfig
   freetype
   libdrm
   libICE
   libSM
   libstdc++
   libcrypt (part of glibc on many modern systems)
   libX11
   libXau
   libXdmcp
   libXext
   libXft
   libxkbcommon-x11
   libXrender
   libXScrnSaver (Ubuntu users may need to install libXss1)
   libXt
   libXxf86vm
   mesa-libGL
   mesa-libGLU

The GUI will not able to start without shared libraries provided by
these packages.

**NOTE:** If you receive an error about libXss (libXss.so.1: cannot
open shared object file: No such file or directory), you need to
install libXScrnSaver (redhat/centos: yum install libXScrnSaver) or
libxss1 (ubuntu/debian: sudo apt install libxss1).

**Compiler**

If you have a license for the source code, you can compile the source
yourself, with or without your own modifications.

The source consists mainly of Fortran95/2003 code, with some small
parts written in C. Some of the Fortran2003 features are also used so
a compiler supporting it is required. You must use object-compatible
Fortran and C compilers to those we are using on the same platform,
since some parts of the code are available only as object modules. For
all x86 platforms it is currently Intel OneAPI Fortran 2024.1.0 (also
labeled 2021.12.0). It is very unlikely that other compilers, or even
a different major version of the same compiler, will work with these
object modules. We cannot support compilers different from what we are
using ourselves.

To check which compiler to use, see Platform Specific Information.


Important changes since AMS2025
===============================

* No more Centos 7 support: The minimal glibc version requirement for
  AMS on linux is 2.28.

* Package manager installation procedure for administrators has been
  simplified, defaulting to AMSHOME.


Important changes since AMS2024
===============================

* Intel x86 macOS is no longer supported.


Important changes since AMS2023
===============================

* AMS2024 will be the last version of AMS to support Intel x86 macs.

* There is only one Windows version of AMS, using Microsoft MPI and
  Intel MKL. This version should work both on Intel and AMD machines.


Important changes since AMS2022
===============================

* No more Centos 6 support: The minimal glibc version requirement for
  AMS on linux is 2.17.

* The AMD optimized Linux binaries now use AOCL, instead of MKL, for
  better performance on AMD Zen-based processors.

* The AMS Python Stack has been updated to the Enthought Python
  v3.8.12 stack, along with updates of several of the included
  packages.

* The Windows versions of AMS now use Microsoft MPI for
  parallelization, instead of intel MPI.


Important changes since AMS2021
===============================

* The start script has been made more flexible, and most often
  modifications to it are no longer needed. The MPI executable can now
  be supplied via the "SCM_MPIRUN_EXE" variable, and arguments to the
  MPI startup can be supplied via the "SCM_MPIRUN_OPTIONS" variable.
  The autodetection mechanism for cluster queues is working as before.
  If you only want to supply additional MPI arguments and not
  overwrite the ones automatically selected by AMS, use the
  "SCM_MPIOPTIONS" variable. See Appendix A. Environment Variables for
  more details.


Important changes since AMS2020
===============================

* AMS now has a package manager for installing optional components.
  For more details see Installing Optional Components

* Linux binaries for AMD Zen processors now use MKL instead of
  OpenBLAS. These binaries are forced to run in AVX2 mode, and give
  better performance on AMD Zen-based processors.


Important changes since AMS2018
===============================

No major technical changes have been made in AMS2019


Important changes since ADF2017
===============================

Some of the technical changes made since ADF2017:

* No more support for 32-bit Windows: almost all PCs nowadays run on
  64-bit processors and 64-bit Operating Systems. If you need a 32-bit
  version, we advise you to use ADF2017 instead.

* Automated OpenGL fallback mode for GUI on older graphics: available
  on 64-bit Windows and Linux.

* No more support for CentOS 5 on Linux: The Intel ifort 18 compiler
  unfortunately introduces an unavoidable GLIBC 2.11 requirement,
  which means AMS2018/AMS2019 no longer works on older Linux systems.

* Linux binaries for AMD Zen processors: AMS2018/AMS2019 is available
  with OpenBLAS instead of MKL, optimized for the AMD Zen
  architecture. These binaries should be used on AMD Ryzen /
  Threadripper and Eypc CPUs for better performance.

* Updated Python stack: Our python stack is now based on the Enthought
  Python v3.6 stack, most included modules have also been updated.

* AVX-512 support: AMS2018/AMS2019 is compiled with AVX-512
  optimizations for the latest Intel Xeon Scalable Processors (Skylake
  SP).
