Installation

STEPSS comes in two editions, and this page installs either. STEPSS GUI is the desktop application: install it once, then work from windows and menus. STEPSS in Python is the stepss package: pip install it and drive the same engines from a script or a notebook. Both read the same data files, so a case built in one runs unchanged in the other, and installing one does not commit you to it.

The last two sections, the Fortran toolchain and CODEGEN Studio, are for writing your own models. Skip them unless you intend to.

Only want the Python package?

pip install stepss is the whole installation and it needs no Java. Skip to Installing STEPSS in Python.

Watch it

Episode 1 of the video series, Installation and Setup, covers this page.

Installing STEPSS GUI

STEPSS GUI comes as an installer, which brings its own Java, on every release. There is also a package manager on each platform, delivering the same application so that later releases arrive on their own: an APT repository on Debian and Ubuntu, a Scoop bucket on Windows, and a Homebrew tap on macOS.

Which Linux

Debian and Ubuntu are the Linux distributions STEPSS is packaged for, from Ubuntu 24.04 and its Debian contemporary onwards, on x86-64. That is what the .deb and the APT repository are built and tested against, and no package is produced for any other distribution or architecture.

Installer

The installers bundle a Java runtime, so an existing Java on the machine is neither required nor disturbed. On Windows and Linux nothing else needs installing. On macOS the simulation engines also need two Homebrew packages, which the .dmg cannot bring with it.

Go to the latest release

1. Download the one for your system from the release’s assets:
   • Windows: STEPSS-<version>.msi, though the Windows (Scoop) tab is the better route if you can use it: same application, later releases arrive on their own, and it needs no administrator rights.
   • macOS (Apple Silicon): STEPSS-<version>.dmg, and run brew install gcc openblas once, or the application opens normally and the first simulation fails. The macOS (Homebrew) tab is the better route if you can use it: same application, both packages come with it, and later releases arrive on their own.
   • Linux (Debian, Ubuntu): stepss_<version>_amd64.deb, though the Debian and Ubuntu (apt) tab is the better route if you can use it: same package, and later releases arrive on their own.
2. Open it and follow the installer.
3. Launch STEPSS from the Start menu, Applications, or your desktop’s application list.

On Linux, install the .deb with sudo apt install ./stepss_<version>_amd64.deb rather than dpkg -i, so that the libraries it needs are pulled in with it. It requires Ubuntu 24.04 or newer, or a Debian of the same vintage or later.

Uninstall the way you would any other application on your system: Add or Remove Programs on Windows, dragging it to the Trash on macOS, sudo apt remove stepss on Debian and Ubuntu.

Debian and Ubuntu (apt)

STEPSS has an APT repository, so it installs like any other package and every later release arrives through apt upgrade instead of being downloaded by hand. It is the same .deb as the Installer tab, served from apt.sps-lab.org.

Set it up once:

sudo install -d -m 0755 /etc/apt/keyrings
sudo curl -fsSL https://apt.sps-lab.org/sps-l-archive-keyring.asc \
  -o /etc/apt/keyrings/sps-l-archive-keyring.asc

sudo tee /etc/apt/sources.list.d/sps-l.sources >/dev/null <<'EOF'
Types: deb
URIs: https://apt.sps-lab.org
Suites: stable
Components: non-free
Architectures: amd64
Signed-By: /etc/apt/keyrings/sps-l-archive-keyring.asc
EOF

Then install, and from that point on upgrade with the rest of the system:

sudo apt update
sudo apt install stepss

Run it with stepss, or from the Science section of the applications menu. Remove it with sudo apt remove stepss.

If apt update says NO_PUBKEY 3600A756077AD061

That is apt naming the key it wanted and could not find, and it means one of three things, which look identical from apt: the keyring file is not there, because the download failed and curl correctly writes nothing when it does; the Signed-By line is missing from your .sources file; or the file holds some other key.

gpg --show-keys /etc/apt/keyrings/sps-l-archive-keyring.asc

It should print fingerprint 125ABE6917ED2F2965D6545B3600A756077AD061 for SPS-L Packaging <stepss@sps-lab.org>. If it reports no such file, run the curl command again. A different complaint mentioning add_keyblock_resource means the file exists but is empty, and has the same remedy.

What this route requires and what it is not

• Ubuntu 24.04 or newer, or a Debian of the same vintage or later, on x86-64. The package is built on 24.04 and names its dependencies as that release names them, so 22.04 and Debian 12 cannot install it. There is no Linux arm64 build of the engines, which is why Architectures: amd64 is in the snippet: without that line, apt on an arm64 machine looks for an index that does not exist and errors on every apt update.
• The current release only. The repository serves one version. To install a specific older build, take its .deb from the releases page.
• non-free is accurate, not boilerplate. STEPSS is not free software taken as a whole: RAMSES is proprietary and free for non-commercial use only, and Helios and CODEGEN are under Academic Public Licences. Installing through apt agrees to nothing, since the licence appears the first time you launch STEPSS. Read Licensing before you run it, and please do not mirror the repository: the licence granted for RAMSES is non-transferable.
• This is not an official Ubuntu or Debian repository, and nothing in it has been through Canonical’s or Debian’s review.

Windows (Scoop)

STEPSS has a Scoop bucket, so it installs from the command line and every later release arrives through scoop update instead of being downloaded by hand. It is the same application as the .msi, delivered as a portable build.

It needs no administrator rights. Scoop installs into your own profile, so this is the route that works on a managed or locked-down machine where an installer cannot be run at all.

If you do not have Scoop yet, install it in a normal (not elevated) PowerShell:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
Invoke-RestMethod -Uri https://get.scoop.sh | Invoke-Expression

Then add the bucket once and install:

scoop bucket add sps-l https://github.com/SPS-L/stepss-scoop
scoop install stepss

From that point on, upgrade with the rest of your Scoop applications:

scoop update stepss

You get STEPSS on the Start menu under Scoop Apps, an icon on your desktop, and a stepss command on your PATH. Remove it with scoop uninstall stepss, which takes both shortcuts with it.

What this route requires and what it is not

• Windows on x86-64. There is no Windows arm64 build of the engines.
• The current release only. The bucket serves one version. To install a specific older build, take its .msi from the releases page.
• STEPSS is not Apache 2.0 taken as a whole, whatever the interface’s own repository says. RAMSES is proprietary and free for non-commercial use only, and Helios and CODEGEN are under Academic Public Licences. Installing through Scoop agrees to nothing, since the licence appears the first time you launch STEPSS. Read Licensing before you run it, and please do not mirror the bucket’s release assets: the licence granted for RAMSES is non-transferable.
• This is not an official Scoop bucket, and nothing in it has been through the Scoop maintainers’ review. scoop bucket add takes the URL above precisely because the bucket is ours rather than theirs.

macOS (Homebrew)

STEPSS has a Homebrew tap, so it installs from the command line and every later release arrives through brew upgrade instead of being downloaded by hand. It is the same application as the .dmg.

It brings what the engines need. The simulation engines load the gfortran runtime and OpenBLAS from Homebrew, and this route installs both as dependencies. With the .dmg you install them yourself.

brew install --cask sps-l/stepss/stepss

From that point on, upgrade with the rest of your Homebrew applications:

brew upgrade --cask stepss

You get STEPSS in Applications. Remove it with brew uninstall --cask stepss.

If STEPSS is already in Applications from a .dmg, move it to the Trash first: Homebrew does not overwrite an application it did not install, and stops with It seems there is already an App at '/Applications/STEPSS.app'.

What this route requires and what it is not

• Apple Silicon. There is no Intel macOS build of the engines.
• The current release only. The tap serves one version. To install a specific older build, take its .dmg from the releases page.
• A network connection the first time you open it. The application is signed and notarized, and macOS confirms that with Apple on first launch.
• STEPSS is not Apache 2.0 taken as a whole, whatever the interface’s own repository says. RAMSES is proprietary and free for non-commercial use only, and Helios and CODEGEN are under Academic Public Licences. Installing through Homebrew agrees to nothing, since the licence appears the first time you launch STEPSS. Read Licensing before you run it, and please do not mirror the release assets: the licence granted for RAMSES is non-transferable.
• This is not an official Homebrew cask, and nothing in it has been through the Homebrew maintainers’ review. Naming the cask in full, as the command above does, is what tells Homebrew you trust it.

Installing STEPSS in Python

STEPSS in Python is the stepss package on PyPI. It needs Python 3 and no Java at all:

pip install stepss

That one command brings the engines with it: the package carries pre-compiled RAMSES and Helios binaries for Windows, Linux and macOS, so there is nothing to install alongside it and nothing to point it at. Trajectory plotting is built in, on top of Matplotlib, in place of the DYNGRAPH viewer the GUI launches.

Two things it does not do for you, both covered by the Python API Installation Guide: on Linux and macOS the bundled binaries link against system runtime libraries (OpenBLAS, the gfortran and OpenMP runtimes) that your machine may not already have, and plotting observables while a run proceeds is your own loop over the curve file the engine writes, rather than something the package does for you. That page also covers version pinning, which is how you fix the engine version a script runs against.

CODEGEN is not in this edition

stepss bundles RAMSES and Helios, not CODEGEN, so writing your own models needs STEPSS GUI or the toolchain below. Running a model someone else compiled works from either edition. Two Editions sets out what each one carries.

Installing a Fortran Toolchain

Tip

This step can be skipped unless you intend to compile your own models. Both editions run their bundled engines, and every model already in them, without it.

Compiling a custom model produces a simulator built from the bundled URAMSES kit, which is a gfortran build. You therefore need gfortran, GNU make and OpenBLAS on your machine.

This applies to either edition: URAMSES links custom models into stepss and into STEPSS GUI alike. It is the compiling that needs a toolchain, and it is separate from writing the model in the first place, which is CODEGEN’s job and ships only with the GUI.

Windows

Install MSYS2, or, if you installed STEPSS with Scoop and would rather not run a second installer, scoop install msys2. Then, from an MSYS2 shell:

pacman -S mingw-w64-x86_64-gcc-fortran mingw-w64-x86_64-openblas make

STEPSS looks for the installation in C:\msys64, in Scoop’s applications directory, or wherever the MSYS2_ROOT environment variable points, so the MinGW bin directory does not have to be on the system PATH and there is nothing to configure by hand on either route. It searches every one of those that exists rather than stopping at the first, because scoop install msys2 leaves an MSYS2 already at C:\msys64 alone and only one of the two is likely to be the one you ran pacman in.

Note that the Scoop bucket suggests MSYS2 rather than depending on it, so scoop install stepss does not pull it in. That is deliberate: it is a large download, nothing else in STEPSS needs it, and .mod files are readable only by the gfortran release that wrote them, so installing whatever MSYS2’s rolling repository holds on a given day would not guarantee a matching toolchain anyway.

Linux (Debian, Ubuntu)

sudo apt install gfortran make libopenblas-dev

Installing STEPSS through apt offers these three as recommended packages, so on that route they are already there unless you declined them.

macOS

macOS ships no Fortran compiler, so it comes from Homebrew:

brew install gcc openblas

Installing STEPSS through Homebrew brings both with it, so on that route they are already there.

Apple Silicon only; Intel Macs are not supported.

The compiler must match the kit

Fortran .mod files can only be read by the gfortran release that wrote them. Each platform’s default compiler normally matches its own bundled kit; when it does not, STEPSS reports the exact compiler version to install rather than failing in the middle of a build. See URAMSES for the details.

Installing CODEGEN Studio

CODEGEN Studio is the browser-based visual editor for building models: drag blocks onto a canvas, connect them, and export a DSL file instead of writing one by hand. It is its own Python package, tied to neither edition, and needs Python 3.10 or newer:

pip install stepss-cg-studio
cg-studio

cg-studio starts a local server and opens the editor at http://localhost:8765. If the script is not on your PATH, python -m cg_studio does the same thing. Browser-based here means the interface is a web page, not that anything leaves your machine: the server is local and so is every file it reads.

CODEGEN comes with it

The wheel carries the CODEGEN executables for Linux, Windows and macOS, so Run Codegen generates Fortran on a fresh install with nothing to obtain and no path to set. On macOS, add brew install gcc: that build links against libgfortran, because Apple does not support fully static executables. See User-Defined Models for what happens to the generated file next.

CODEGEN is not Apache 2.0 like the editor around it, so this wheel is mixed-licence: see License.

See CODEGEN Studio for the command-line options, a source install, and how to drive the editor itself.