Installation Guide¶
This section provides a step-by-step guide for installing Acherus package, aimed at both users and developers.
The installation guide is devoted to UNIX-based operating systems Linux and macOS—since they are dominant in scientific computing—from personal basic applications (Linux/macOS-based) to supercomputers, clusters, and high performance computing (HPC) facilities (entirely Linux-based). However, Acherus ecosystem is entirely dependent on Python libraries and modules, hence it can be used in any Linux, macOS, or Windows operating system. In the latter case, there are two approaches. The first one is to give up on Windows and use a UNIX machine instead. The second one is to install a Linux distribution on a Windows machine, which is easy to do following the WSL Guide.
Acherus installation¶
For users¶
Acherus is now part of the PyPI software repository and can be installed as a package using pip:
pip install acherus
Once installed, to upgrade to the latest version simply do
pip install --upgrade acherus
For developers¶
The development and management of Acherus is carried through GitHub. Some developers might prefer to use the GitHub CLI to contribute straight from their terminal.
To start using Acherus and access the various ecosystem files, just clone the repository by choosing one of the two options below:
# SSH (password-protected key):
git clone git@github.com:ismatorresgarcia/acherus.git
# HTTPS (web URL):
git clone https://github.com/ismatorresgarcia/acherus.git
Next, on a previously created Python virtual environment, proceed to install the dependencies. Move to acherus/ project directory and install them by doing:
cd acherus
pip install -r requirements.txt
For testing and experimenting with upcoming features, installing the cloned package in editable mode allows developers to see their new changes without reinstalling the package. It also installs automatically all the dependencies through the pyproject.toml configuration file. Move to acherus/ project directory and install it in editable mode by doing:
cd acherus
pip install -e .
If the developer has any ideas, suggestions, or improvements, and wants to push them to Acherus, the recommended route is to create a fork from Acherus main branch in your own GitHub repository. Then, create a new branch, and submit a pull request (PR). Below are listed the five steps to follow:
Fork the repository: https://github.com/ismatorresgarcia/acherus/fork
Create a new branch:
git checkout -b branch-name
Make your changes and commit them:
git add file-name.py
git commit -m "changes-description"
Push to the new branch:
git push origin branch-name
Submit a pull request: https://github.com/ismatorresgarcia/acherus/pulls
Dependencies¶
As mentioned at the beginning, Acherus is an entirely Python-written code which depends on a few well-established third-party Python libraries:
NumPy: Fundamental package for scientific computing in Python. Specially important for fast operations on arrays of multidimensional shapes.
SciPy: Mathematical algorithms and high-level functions built on NumPy. Specially important for accessing various numerical linear algebra tools.
Matplotlib: Comprehensive library for creating static, animated, and interactive figures in Python. Specially useful for plotting and animating 1D and 2D plots.
h5py: Python interface to the HDF5 binary data format. Specially important for storing laser field intensity and electron density 3D arrays at different propagation steps.
Numba: Performance library that uses JIT compilation to translate on runtime Python and NumPy pieces of code into machine code. Specially important for enhancing the speed of sequential algorithms from explicit numerical schemes.
pyFFTW: Python wrapper around the well-known C subroutine library FFTW for computing the Fastest Fourier Transform in the West. Specially important for implementing the high-speed FFT algorithms and low-level controls in pseudospectral schemes.
These are the dependencies required by Acherus. When installing Acherus from Pip, the dependencies download and installation is done together with the package. Either way, the list of dependencies can be explicitly installed in a chosen Python virtual environment moving to acherus/ project directory and typing in the terminal:
pip install -r requirements.txt
Python installation¶
The first step is to know if the machine does not have a Python installation setup. Not having a system-wide Python installed is incredibly rare, since many low-level tools depend on Python for running scripts. However, some minimal systems might not have Python installed at all. To see if your system has some internal Python version installed, type in your terminal:
# check for modern setups
python3 --version
# check for older setups
python3 --version
If a version number such as
Python X.YY.Z
is shown in the terminal, do not upgrade or replace it manually and move to the version installation section. Otherwise, follow these brief guideline for installing Python 3 in Linux, macOS, and Windows operating systems:
Note
The system-wide version in the machine is not really meant to be used for anything besides basic operating system infrastructure and maybe learning purposes. Furthermore, the version shipped might be deprecated or out of date from the latest official Python release, which is considered the production version for any active user.
Linux¶
Most popular Linux distributions already include Python because the package manager needs it to execute some scripts. If not installed, read the distribution documentation for the basic package manager instructions, commands, and available distribution repositories. Once this is done, simply search in the repository for the latest stable name for Python and pass it as an argument to the package manager system for installation. Here are some examples:
Debian-based (Ubuntu, Debian, Linux Mint)
sudo apt-get install python-version-name
sudo dnf install python-version-name
sudo pacman -S python-version-name
sudo zypper install python-version-name
Then, verify the installation in the terminal:
python3 --version
pip3 --version
macOS¶
Newer versions of macOS may not have Python installed for users (older versions used to have Python 2.X by default). In this case, the simplest approach is to download a recent and stable release from the Python website and follow the installer instructions. In the process, Python should be added automatically to the PATH during the configuration and bundled together with the pip installation.
Then, check both:
python3 --version
pip3 --version
Windows¶
If Python is not installed on a Windows machine (and assuming the user wants to stick with Windows, instead of installing the WSL), install the latest version of Python from the Python website and follow the installer instructions. Remember during installation to add Python to PATH and allow the installer to include pip by checking the corresponding options.
Then, verify the installation:
python3 --version
pip3 --version
Version installation¶
Once verified the machine has installed a system-wide Python version, the next step is to install Pyenv and follow the configuration instructions for your operating system. Pyenv is a simple, lightweight, and easy to use tool that simplifies the management of multiple Python versions on a system. You can install different Python versions and switch between them as needed. Before installing Pyenv, make sure the necessary dependencies, such as Git, are installed.
To show all Python versions within Pyenv, do:
pyenv install --list
To install any of the Python versions available, do:
pyenv install X.YY.Z
One of the main advantages of Pyenv is it downloads, builds, installs, and sets multiple Python versions completely separate from the system Python. This avoid any conflict between previously existing Python versions and the possibility of interfering with the system installation, which would become a nightmare and potentially break the system. For example, let’s say Python 3.12.3 was installed. To set it as the default (global) version of the system, just do:
pyenv global 3.12.3
Another interesting thing, quite useful for developers, is the ability to set one version per project. For example, to set a project-specific (local) Python 3.12.3, do inside the acherus/ project folder:
pyenv local 3.12.3
This simply creates a .python-version file inside the project folder, meaning everything contained in it (without affecting anything outside) use that Python version automatically. It guarantees the Python version being used when running any simulation is restricted to the acherus/ project folder, as well as shifting easily between other versions. Also, Pyenv shims, routes, and unifies every active Python version under the commands python and pip, so there is no need to type python3 and pip3 anymore.
Environment isolation¶
Once installed and selected a Python version using Pyenv, the final strongly recommended step is to create a virtual environment for the project. The reason why virtual environments are crucial is to isolate the installation of Python packages and third-party libraries without interfering with other projects or the system Python. Just as Pyenv avoids conflicts between different Python versions, virtual environments prevent conflicts between different packages and/or their versions. For example, different projects may require different versions of the same package, which is one of the reasons why developers use them on a daily basis.
To create and activate a virtual environment inside your project folder, do (Windows requires giving execution permissions first):
python -m venv .venv-name
source .venv-name/bin/activate
python -m venv .venv-name
.venv-name\Scripts\activate.bat
python -m venv .venv-name
.venv-name\Scripts\Activate.ps1
Instead of creating a virtual environment inside every project, the user might choose to store virtual environments in some centralized location. This can make management easier if you work with many projects. For example, a global folder named virtualenvs/ in your home directory could host a new environment:
python -m venv ~/virtualenvs/venv-name
Once the environment is activated, any pip command installs exclusively inside the virtual environment, separated from the system Python or other project folders:
pip install package-name
For example, to recreate the exact environment used in the acherus/ project:
pip install -r requirements.txt
When finished, to return the shell to the previous state, type:
deactivate
In summary, we deeply encourage users and developers to set a Python 3 version (between 3.10 and 3.13) with Pyenv and create a dedicated virtual environment:
Set one python version with pyenv
pyenv local X.YY.Z # Option 1: project folder
pyenv global X.YY.Z # Option 2: entire system
Set one python virtual environment (Linux & macOS)
source .venv-name/bin/activate # Option 1: project folder
source ~/virtualenvs/venv-name/bin/activate # Option 2: shared folder
Set acherus installation with pip
pip install acherus