Using Agustina

rlaplaza August 01, 2025 October 08, 2026

Using Agustina

Agustina is a High Performance Computing (HPC) center. There are many such centers in the world (a list of the most powerful supercomputers is available in the Top500, in case you are curious).

The main documentation of Agustina is here, which includes account creation and basic usage. Remember that any changes you make to your .bashrc will be applied once you open a new terminal or run source .bashrc.

Like most HPC centers, Agustina requires users to connect from a local network for security reasons. In other centers you must use a VPN. In Agustina, you can ssh to the login node (agustina.bifi.unizar.es) through a bridge node (bridge.bifi.unizar.es). Setting up these aliases in your .bashrc file will be useful:

alias tob='ssh -X username@bridge.bifi.unizar.es'
alias toa='ssh -J username@bridge.bifi.unizar.es username@agustina.bifi.unizar.es'

That way you can jump over bridge to access Agustina using simply toa.

For Windows users, the usual choice is PuTTY. The Agustina documentation describes the same login pattern: users can connect directly with ssh username@agustina.bifi.unizar.es if the firewall allows it, or use the bridge node with ssh username@bridge.bifi.unizar.es and then ssh username@agustina.bifi.unizar.es once you are inside the bridge. In PuTTY, this means:
1. Open PuTTY and set the hostname to username@bridge.bifi.unizar.es if you are going through the bridge.
2. Save the session with a memorable name and click Open.
3. Log in with your Agustina username and password.
4. Once you are on the bridge, run ssh username@agustina.bifi.unizar.es to reach the login node.
If you are connecting directly and your IP is already authorized by the firewall, you can simply set the hostname to username@agustina.bifi.unizar.es instead. For file transfers, PuTTY’s companion tools (pscp / psftp) or a graphical client like WinSCP are often the easiest alternatives to scp and rsync.
Once in Agustina, you will notice that the command line interface is very plain. To improve it, you can set up a few extras in your .bashrc file (in your Agustina user home!):

export PS1="\[\e[31m\][\[\e[m\]\[\e[33m\]\u\[\e[m\]@\[\e[36m\]\h\[\e[m\]\[\e[31m\]]\[\e[m\]:\[\e[33;40m\]\w\[\e[m\]\[\e[40m\] \[\e[m\]\[\e[32;40m\]\\$\[\e[m\] "
alias wqm="watch squeue --format=\'%.18i %.9P %.30j %.8u %.8T %.10M %.9l %.6D %R\' -u username"

Next step is setting up github and git. To start, go to your github keys setting and then generate a new ssh key in Agustina and add it to your account following the instructions.

Once that is done, you can get the lab’s utility scripts from the group organization page, assuming you have asked for permissions. Clone this directory to a directory (I put it in /home/username/Software/) and add the directory to your path in .bashrc:

export PATH="/home/username/Software/utility_scripts:$PATH"

Now you can use the scripts from this directory in your command line. You can check usage by reading the scripts or, in general, using the help flag, e.g.:

subconda.sh -h

The group also provides a small set of job-submission helpers for Agustina in the utility_scripts repository. The relevant files live under utility_scripts/agustina/, and the two most useful ones are suborca.sh and subconda.sh. In practice, I clone the repository to a stable location, add the agustina/ folder to PATH, and then use the wrappers from anywhere:

git clone https://github.com/rlaplaza-lab/utility_scripts.git ~/utility_scripts
printf '\nexport PATH="$HOME/utility_scripts/agustina:$PATH"\n' >> ~/.bashrc
source ~/.bashrc

After that, you can inspect the built-in usage text:

suborca.sh -h
subconda.sh -h

The idea is simple: the wrapper creates a sbatch job script for you, sets the job resources, activates the chosen environment, runs the job, and writes the logs under a slurm_logs/ folder next to your input files. This saves a lot of boilerplate and reduces the chance of forgetting the --account project or a required environment module.

suborca.sh is meant for ORCA jobs. For writing the input itself (keywords, %pal / %MaxCore, optimizations), see ORCA Basics and Troubleshooting. A typical submission example is:

suborca.sh -n 4 -m 16000 my_calculation.inp
suborca.sh -n 8 -m 32000 -p agustina_thin my_calculation.inp

This will submit an ORCA input file, defaulting to the resources described in the input (%PAL nprocs, %MaxCore) whenever possible. If your input file does not include those directives, you should set them explicitly in the .inp file or use the -n and -m flags carefully. The script also has a -d dry-run option, which is useful to inspect the generated SLURM script before submitting it. One thing to keep in mind: the script uses a default project account value (currently molcat in the local copy), so if your project is different, edit that variable near the top of the script before submitting.

subconda.sh is the equivalent helper for Python jobs that should run inside a specific Conda environment. Typical usage is:

subconda.sh -e my_env -n 4 -m 16000 my_script.py
subconda.sh -e my_env -n 8 -m 32000 -p agustina_thin my_script.py arg1 arg2

The script loads anaconda/2025, activates the requested environment, sets a good default for OMP_NUM_THREADS and related variables, and runs the Python job in a temporary scratch directory by default. This is especially handy when your project writes many files, because it keeps the job isolated and then copies the results back to the submission directory. If you want to stay in place instead of using scratch, add -s.

The job submission scripts are a convenience layer around sbatch, not a replacement for understanding SLURM. The key ideas are still the same: choose the correct project account, request enough memory and CPUs, and keep a close eye on your slurm_logs outputs when debugging a failed run.

The next step is setting up conda or some other package manager.

If you have never used Conda on your own laptop, start with the gentle Local Conda and VS Code Setup guide first, then come back here for the cluster-specific pieces. On Agustina itself, follow the documentation here.

The first time you use conda on Agustina, do not jump straight to editing .bashrc. Load the module interactively and initialize conda in your shell first:

module load anaconda/2025
conda init

conda init modifies your .bashrc so conda can activate environments automatically. Only after that one-time step should you add the usual convenience lines (module load on login, package cache path, env directory, and so on). Personally, I added these:

module load anaconda/2025 > /dev/null # This avoids errors with scp and rsync with host jumping
export CONDA_PKGS_DIRS=/fs/agustina/$(whoami)/.conda-pkgs
export PIP_CACHE_DIR=/fs/agustina/$(whoami)/.pip-cache
export FAIRCHEM_CACHE_DIR=/fs/agustina/$(whoami)/cache
mkdir -p /fs/agustina/$(whoami)/conda-env /fs/agustina/$(whoami)/.pip-cache /fs/agustina/$(whoami)/cache
# To activate or create envs, we now need --prefix=/fs/agustina/$(whoami)/conda-env/my-conda-env-name
# ... other lines you may need
export TERMINFO=/usr/share/terminfo # This makes sure that clear command works

Log out and log back in. On the next login you should see (base) near your prompt, which confirms that the module load and conda init are both working.

The space you have in your /home in Agustina is small, so your conda envs, conda package cache, pip cache, and application caches (for example FairChem) should live under /fs/agustina/username/ (some packages are very big!). Since typing the full path to activate an env is a pain in the derriere, you can add that location to let conda figure out aliases.

conda config --append envs_dirs /fs/agustina/username/conda-env/

You can now activate envs using their names directly.

If downloads or HTTPS calls fail with certificate / SSL errors (for example CERTIFICATE_VERIFY_FAILED from pip, requests, or similar tools), conda’s OpenSSL is often not finding a usable CA bundle. As a workaround, add this to your .bashrc as well (after the module load / conda lines so python resolves correctly):

export SSL_CERT_FILE="$(python -m certifi)"

Then open a new shell (or source ~/.bashrc) and retry. You need the certifi package in the Python that runs at login (usually the base conda env).