Skip to content

FirecREST#

This guide explains how SCITAS users can use FirecREST to:

  • Upload files to Alps clusters
  • Download files from Alps clusters
  • Submit jobs to Alps clusters

All of this can be done from SCITAS clusters, without directly logging into the Alps clusters.

FirecREST is developed by the Swiss National Supercomputing Centre (CSCS). For more details, refer to the CSCS FirecREST documentation.

FirecREST Deployment on Alps#

FirecREST is available for all three major Alps platforms, with a dedicated API endpoint for each platform:

Platform API Endpoint Clusters
HPC Platform https://api.cscs.ch/hpc/firecrest/v2 Daint, Eiger
ML Platform https://api.cscs.ch/ml/firecrest/v2 Bristen, Clariden
C&W Platform https://api.cscs.ch/cw/firecrest/v2 Santis

Use the API endpoint corresponding to the platform and cluster you want to access.

Accessing FirecREST#

Before using FirecREST, you must create API credentials. Go to the CSCS Developer Portal and follow the instructions.

You need to:

  1. Create an application
  2. Configure production keys
  3. Subscribe to the FirecREST API

After configuring production keys, you will receive:

  1. Client ID (Consumer Key)
  2. Client Secret (Consumer Secret)

Warning

Keep these credentials secure. Do not share them with anyone.

Preparing Python Environment#

To use FirecREST (CLI or Python), you need to install the pyfirecrest package in a Python virtual environment. For more information about Python virtual environments, see here.

Load the required modules:

module load gcc python py-virtualenv

Create a virtual environment:

virtualenv --system-site-packages venvs/firecrest

Activate the environment:

source venvs/firecrest/bin/activate

Install the FirecREST package:

pip install --no-cache-dir pyfirecrest

Using the FirecREST CLI#

Set Environment Variables#

Before running FirecREST commands, export your credentials and URLs:

export FIRECREST_CLIENT_ID=YOUR_ID
export FIRECREST_CLIENT_SECRET=YOUR_SECRET
export AUTH_TOKEN_URL=https://auth.cscs.ch/auth/realms/firecrest-clients/protocol/openid-connect/token

# HPC Platform (Daint, Eiger)
export FIRECREST_URL=https://api.cscs.ch/hpc/firecrest/v2

# ML Platform (Bristen, Clariden)
# export FIRECREST_URL=https://api.cscs.ch/ml/firecrest/v2

# C&W Platform (Santis)
# export FIRECREST_URL=https://api.cscs.ch/cw/firecrest/v2

Replace YOUR_ID and YOUR_SECRET with the values you obtained from the CSCS Developer Portal. Set FIRECREST_URL according to the platform you want to use (see FirecREST Deployment on Alps).

Optionally, you can set a default system (for example, daint):

export FIRECREST_SYSTEM=daint

With this, you no longer need to specify -s daint in every command. In the examples below, we use the daint cluster (HPC platform). Replace it with your target system.

Get Help#

You can explore all available commands and their options using the --help flag. For example:

firecrest --help
firecrest ls --help
firecrest submit --help
firecrest upload --help
firecrest download --help

Status Commands#

These commands let you retrieve information about the FirecREST service and the available CSCS systems.

╭─ Status commands ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ server-version    Provides the exact version of the FirecREST server, when available.                                                                                                                         │
│ systems           Provides information for the available systems in FirecREST                                                                                                                                 │
│ get-nodes         Retrieves information about the compute nodes of the scheduler.                                                                                                                             │
│ get-reservations  Retrieves information about the scheduler reservations.                                                                                                                                     │
│ get-partitions    Retrieves information about the scheduler partitions.                                                                                                                                       │
│ id                Return the identity of the user in the remote system.                                                                                                                                       │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

List Available Systems#

To see which systems you can access through FirecREST:

firecrest systems

To display only the system names:

firecrest systems | grep -w name

Example output:

        "name": "eiger",
        "name": "daint",

These system names correspond to specific platforms (see FirecREST Deployment on Alps). You can use these system names (for example, daint or eiger) with the -s option in other commands.

Check Your Identity on a System#

To verify your username and CSCS accounts on a specific system:

firecrest id -s daint

Utilities Commands#

These commands allow you to perform basic file and directory operations on a remote system.

╭─ Utilities commands ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ ls                List directory contents                                                                                                                                                                     │
│ mkdir             Create new directories                                                                                                                                                                      │
│ mv                Rename/move files, directory, or symlink at the `source_path` to the `target_path` on `system`'s filesystem                                                                                 │
│ chmod             Change the file mod bits of a given file according to the specified mode                                                                                                                    │
│ chown             Change the user and/or group ownership of a given file.                                                                                                                                     │
│ cp                Copy files                                                                                                                                                                                  │
│ compress          Compress files using gzip compression.                                                                                                                                                      │
│ extract           Extract files.                                                                                                                                                                              │
│ file              Determine file type                                                                                                                                                                         │
│ stat              Use the stat linux application to determine the status of a file on the system's filesystem                                                                                                 │
│ symlink           Create a symbolic link                                                                                                                                                                      │
│ rm                Remove directory entries                                                                                                                                                                    │
│ checksum          Calculate the SHA256 (256-bit) checksum                                                                                                                                                     │
│ head              Display the beginning of a specified file.                                                                                                                                                  │
│                   By default the first 10 lines will be returned.                                                                                                                                             │
│                   Bytes and lines cannot be specified simultaneously.                                                                                                                                         │
│ tail              Display the end of a specified file.                                                                                                                                                        │
│                   By default the last 10 lines will be returned.                                                                                                                                              │
│                   Bytes and lines cannot be specified simultaneously.                                                                                                                                         │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

List Files in a Directory#

To list files on a remote system:

firecrest ls -s daint /path/on/daint/filesystem

Create a Directory#

To create a directory on a remote system:

firecrest mkdir -s daint /path/on/daint/filesystem/new_directory

Storage Commands#

These commands allow you to transfer files between SCITAS clusters and Alps clusters.

╭─ Storage commands ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ download          Download a file                                                                                                                                                                             │
│ upload            Upload a file                                                                                                                                                                               │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

Download a File#

To download a file from Alps cluster to SCITAS cluster:

firecrest download -s daint --account your_cscs_account \
    /path/on/alps/file.txt \
    /path/on/scitas/

Parameters:

  • --account - your CSCS account
  • First path - the file on Alps cluster
  • Second path - the destination on SCITAS cluster

Upload a File#

To upload a file from SCITAS cluster to Alps cluster:

firecrest upload -s daint --account your_cscs_account \
    /path/on/scitas/file.txt \
    /path/on/alps/

Parameters:

  • --account - your CSCS account
  • First path - the file on SCITAS cluster
  • Second path - the destination on Alps cluster

Compute Commands#

These commands allow you to submit Slurm jobs from SCITAS cluster to Alps cluster and manage them.

╭─ Compute commands ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ submit            Submit a batch script to the workload manager of the target system.                                                                                                                         │
│ job-info          Retrieve information about submitted jobs.                                                                                                                                                  │
│ wait-for-job      Wait for a job to complete. It will return the job information when the job is completed.                                                                                                   │
│ job-metadata      Retrieve metadata for a current job.                                                                                                                                                        │
│ cancel            Cancel job                                                                                                                                                                                  │
│ attach-to-job     Attach a process to a job.                                                                                                                                                                  │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

Submit a Job#

To submit a job from SCITAS cluster to Alps cluster:

firecrest submit -s daint \
    --working-dir /path/on/alps \
    /path/to/your/slurm/script

Parameters:

  • --working-dir - directory on Alps cluster where the job will run
  • script path - local path of your Slurm script on SCITAS cluster

Example output:

{
    "jobId": 2729308
}

Job submission environment

FirecREST submits jobs to the underlying Slurm scheduler. To ensure that your job runs with the same environment as your login shell, your batch script should use the -l option with /bin/bash:

#!/bin/bash -l

#SBATCH --nodes=1
...

This loads system-wide configuration (e.g. /etc/profile) and user environment files (e.g. ~/.bash_profile, ~/.bash_login, or ~/.profile), matching your login shell environment.

Check Job Status#

To check the status of a submitted job:

firecrest job-info -s daint 2729308

Replace 2729308 with your actual job ID.

Using FirecREST in Python#

The example below demonstrates how to upload a file, submit a job, and download a file. Make sure to update the FirecREST API endpoint, system, paths, account, and credentials for your setup.

import firecrest as f7t

# Configuration
account = "your_cscs_account"
client_id = "your_client_id"
client_secret = "your_client_secret"
token_uri = "https://auth.cscs.ch/auth/realms/firecrest-clients/protocol/openid-connect/token"

# Adjust based on platform and system (see FirecREST Deployment on Alps section)
firecrest_url = "https://api.cscs.ch/hpc/firecrest/v2"
system = "daint"

# Paths
local_file_scitas = "/path/to/scitas/file.txt"               # file on SCITAS cluster
remote_dir_alps = "/path/on/alps/"                       # target directory on Alps cluster
remote_file_name = "file.txt"                            # name of the file on Alps
script_local_path = "/path/to/scitas/your_slurm_script.sh" # Slurm script on SCITAS
remote_file_alps = "/path/on/alps/file.txt"              # file on Alps for download
target_file_scitas = "/path/to/scitas/file_downloaded.txt"   # destination path on SCITAS

# Initialize FirecREST client
client = f7t.v2.Firecrest(
    firecrest_url=firecrest_url,
    authorization=f7t.ClientCredentialsAuth(client_id, client_secret, token_uri)
)

# Upload a file from SCITAS cluster to Alps cluster
client.upload(
    system,
    local_file=local_file_scitas,
    directory=remote_dir_alps,
    filename=remote_file_name,
    account=account,
    blocking=True
)

# Submit a job from SCITAS cluster to Alps cluster
client.submit(
    system_name=system,
    working_dir=remote_dir_alps,
    script_local_path=script_local_path
)

# Download a file from Alps cluster to SCITAS cluster
client.download(
    system_name=system,
    source_path=remote_file_alps,
    target_path=target_file_scitas,
    account=account,
    blocking=True
)

Full Python documentation: PyFirecREST.

Support#

If you encounter an issue, please contact the appropriate support based on the origin of the problem:

  • If you suspect a bug in FirecREST or an issue on the CSCS side, please contact CSCS support.

  • If the issue is related to SCITAS infrastructure, access, or environment, please contact SCITAS support.

When reporting an issue, include as much detail as possible (commands used, error messages, and relevant context) to help with debugging.