Introduction

ATSAS is a comprehensive software package designed for the analysis of small-angle X-ray scattering (SAXS) data of biological macromolecules in solution. It provides a wide array of tools for data processing, analysis, and modeling, enabling researchers to determine structural parameters, perform ab initio shape determination, and reconstruct high-resolution models from scattering data. Widely adopted in the field of structural biology, ATSAS supports various workflows and is compatible with multiple operating systems, making it an indispensable tool for scientists studying macromolecular structures.

ATSAS installer packages are available for multiple Linux distributions, macOS for x86 and arm64 CPUs as well as for Windows.

Prerequisites

System Requirements and Dependencies

ATSAS is designed to run on any contemporary hardware, with no specific system requirements or significant external dependencies. On Windows and macOS, the packages include all necessary components for its operation. On Linux the installer offers the option to automatically install runtime-dependencies via the package manager of the distribution, ensuring a seamless installation process.

While ATSAS does not mandate any particular hardware specifications, it can efficiently utilize multiple cores and hardware threads if available, enhancing performance and speeding up all data processing tasks.

Obtaining a License File

To install and run ATSAS, a personalized license file is required. Academic users can obtain these license files free of charge by visiting https://biosaxs.com/download.

For commercial use, please contact us at info@biosaxs.com to request an offer.

Downloading Installer Packages

Installer packages can be obtained from the following URL: https://biosaxs.com/download.

Installing ATSAS

ATSAS can be installed on Windows, Linux, and macOS platforms. The installation process supports both graphical and command-line options. The overall workflow is identical across all platforms, thus this document will only describe the installation process on Windows in detail as an example. For basic use cases, the graphical installer provides a straightforward, step-by-step setup experience, while advanced users and system administrators can utilize command-line options for automated, silent, and remote installations.

Installations on all platforms are relocatable and the files may be installed anywhere in the system. Common locations include C:\Program Files\ on Windows and the $HOME directory on Linux and macOS. Some locations may require Administrator privileges to install.

Parallel Installation of Multiple Versions

In general it is assumed that only one version of ATSAS exists on any given system. However, it can be convenient to install multiple versions in parallel, for example for evaluation purposes.

If a parallel installation is required, follow the installation steps as outlined for a single version for each of the packages to install. Extra care will be needed when configuring the environment.

If unsure, it is reecommended to uninstall any pre-existing versions of ATSAS before installing the latest version following the directions in the next section.

Single Version

The following sections describe the installation procedure for a single version of ATSAS. If multiple versions of ATSAS shall be used in parallel, refer to section Parallel Installation of Multiple Versions before proceeding.

With Installer Wizard

Locate the downloaded installer with a file manager and double click to start the wizard.

Note that Windows might warn about an .exe downloaded from the internet. You may need to click something like “More Info > Run anyway”.

Follow the steps shown by the wizard. Select the installation directory or accept the default. When prompted, search for the previously obtained license file. Read and accept the individual software licenses. Finally confirm that the installation shall proceed.

From Command-Line

Usage:

% ATSAS-4.0.1-XXX.[exe|run] [OPTIONS] install

where XXX and the extension depends on the platform. Without the install argument , the Installer Wizard will start.

Windows only: to install for all users on one machine, run the installer as Administrator and add AllUsers=True to the command-line:

% ATSAS-4.0.1-XXX.exe [OPTIONS] install AllUsers=True

The following OPTIONS are commonly useful for a non-interactive or headless installation. Additional options are available and documented in the full --help output:

Option Description
--root DIRECTORY If provided, ATSAS will be installed to DIRECTORY, otherwise a platform specific default installation directory will be used (see below).
 --file-query KeyFilePath=FILEPATH  If provided, the FILEPATH must point to the obtained license file. The installer will copy this license file to the correct place within the installation root directory and potentially rename it to atsas.lic if named differently. Otherwise the installer will ask for for the file location during the installation process.
--auto-answer AutomaticRuntimeDependencyResolution=Yes|No Linux only: if ‘Yes’ an attempt is made to install required runtime dependency packages via apt-get or yum, respectively. This may require admin privileges (start the installer with sudo). Note that the answer/value provided is case sensitive; ‘Yes’, not ‘yes’.
--accept-licenses Use this option to automatically accept all software licenses. Otherwise the user will have the option to show and read all license texts and to individually accept them. If any of the licenses is rejected, the installation process stops.
--confirm-command install Use this option to automatically accept the command argument, here install. Otherwise the installer will ask whether or not to proceed with the installation once all other steps are complete. In this case, answer ‘yes’ to install. On ‘no’, the installation process stops.
--help Print the full list of options supported by the Installer.

Default installation directories used if --root is not provided:

Platform Default installation directory
Linux $HOME/ATSAS-4.0.1
macOS $HOME/ATSAS-4.0.1
Windows C:\Program Files\ATSAS-4.0.1

Configuring the Environment

Linux

Due to the high variability between Linux distributions and the lack of a truly default shell, the installer does not attempt to update any configuration files.

Instead, please locate the configuration files for your shell and set and export the following variables:

Name Value
ATSAS The installation path
PATH The path to the ATSAS binaries, usually $ATSAS/bin.

Example for bash ($HOME/.bashrc), assuming ATSAS was installed in $HOME/ATSAS-4.0.1:

ATSAS=$HOME/ATSAS-4.0.1
PATH=$ATSAS/bin:$PATH
export ATSAS PATH

Adjust to your shell as needed.

Parallel install and use of multiple versions of ATSAS is not yet supported at this time.

macOS

The installer adds the installation information to the configuration file for the default Z shell ($HOME/.zprofile) and sets the ATSAS and PATH environment variables according to the selected installation directory. Restart Terminal.app to take effect.

Parallel install and use of multiple versions of ATSAS is not yet supported at this time.

Windows

The installer adds or updates the global ATSAS variable in the registry, but does not modify the PATH environment.

To update the global PATH settings for a single installation, follow the procedure outlined here, but do not do this for parallel installations. For parallel installation, please see the instructions below.

  • open the Start menu, click Settings;
  • in “Find a setting”, type “environment”
  • click “Edit environment variables for your account”, a dialog opens
  • for “single user” installation, select PATH in the upper panel and click “Edit” (does not require admin privileges)
  • for “all user” installation, select PATH in the lower panel and click “Edit” (requires admin privileges)
  • remove any previous ATSAS-related entries
  • create a new entry, enter: %ATSAS%\bin
  • save and close

For parallel installations of multiple versions of ATSAS we recommend to prepare application shortcuts to cmd.exe, each with their own specific environment instead of adding any one ATSAS installation to the global settings as described above.

For each ATSAS installation, repeat the following, but replace %INSTALLDIR% with the respective installation directory:

  • right click on the Desktop, select New -> Shortcut
  • In the field “Type in location of the item”, enter (note the long line): 
    %comspec% /V /S /K "cd %HOMEDRIVE%%HOMEPATH% && set PATH=%INSTALLDIR%\bin;%PATH% && set ATSAS=%INSTALLDIR%"
  • click “Next”
  • enter a name, e.g. “ATSAS-X.Y.Z”, where X.Y.Z corresponds to the respective version
  • click Finish

Verifying the Installation

The verification procedure is the same for single or parallel install.

On single install of ATSAS, simply open a new command shell for your respective platform (Windows: cmd.exe or PowerShell, macOS: Terminal.app, Linux: terminal, konsole, ….). Then follow the commands below.

For a parallel install of ATSAS, open the pre-configured shells for each version in turn and follow the commands below for each of them.

Platform Command
Linux (bash) echo $ATSAS
macOS (zsh) echo $ATSAS
Windows (cmd.exe) echo %ATSAS%
Windows (PowerShell) $env:ATSAS

Make sure that the output corresponds to the installation directory used.

To verify that all applications are reachable via the PATH variable, type:

> dammif -v
dammif, ATSAS X.Y.Z (....)

Verify that X.Y.Z matches the version of ATSAS previously installed.

Uninstalling ATSAS

With Uninstaller Wizard

Locate the installation directory of the ATSAS version you want to uninstall with a file manager and double-click uninstall to start the uninstall process.

Follow the steps shown by the wizard and confirm that the uninstallation shall proceed.

From Command-Line

Usage:

> %ATSAS%\uninstall.exe [OPTIONS] purge

Without the purge argument , the Uninstaller Wizard will start.

The following OPTIONS are commonly useful for a non-interactive or headless uninstallation. Additional options are available and documented in the full --help output:

Option Description
--confirm-command purge Use this option to automatically accept the command argument, here purge. Otherwise the uninstaller will ask whether or not to proceed with the uninstallation. In this case, answer ‘yes’ to uninstall. On ‘no’, the uninstallation process stops.
--help Print the full list of options supported by the Installer.

Known Issues

  • Windows installer does not remove file associations on uninstall
    The installer framework used for ATSAS does not clean up the registry completely on uninstall. This is in line with Microsoft Documentation:

    […] applications that have taken ownership of a file type (by setting the Default value of the file type’s HKEY….extension subkey to the ProgID of the application) should not attempt to remove that value when uninstalling. Leaving the data in place for the Default value avoids the difficulty of determining whether another application has taken ownership of the file type and overwritten the Default value after the original application was installed. Windows respects the Default value only if the ProgID found there is a registered ProgID. If the ProgID is unregistered, it is ignored.

  • Uninstalling fails on macOS
    The uninstall utility has an incorrect signature and macOS GateKeeper prevents it from being executed (“can not be run”). As a workaround, manually delete the installation directy and remove the ATSAS and PATH variables from $HOME/.zprofile.

Getting Support

Community support for academic users is available at atsas-community, where discussion forums, issue reporting to the ATSAS developers, and a user-editable Wiki are accessible.

Commercial customers have access to the same community resources but may also contact support@biosaxs.com for additional assistance.