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 two ways: an installer, which needs nothing else on the machine, or the stepss.jar on its own, which needs a Java runtime you already have. Both are on every release. There is also a package manager on each of the two platforms that has one, delivering the same application so that later releases arrive on their own: an APT repository on Debian and Ubuntu, and a Scoop bucket on Windows.

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.

On anything else, including older Debian and Ubuntu releases, use stepss.jar. It needs a 64-bit Java 11 or later and nothing else, and it carries the same engines. It is not tested there, but nothing in it is Debian-specific.

Installer

The installers bundle a Java runtime, so nothing else needs installing and an existing Java on the machine is neither required nor disturbed.

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
   • 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; on an older release, use the jar.

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.

Just the jar

The jar is a single file that leaves nothing behind: it unpacks what it needs into a temporary folder at launch, and deleting the file removes STEPSS entirely. It needs a 64-bit Java Runtime Environment, version 11 or later already on the machine. Any recent JRE or JDK will do, and there is no need to remove a Java you already have as long as it meets that minimum.

Download stepss.jar

1. Check for Java. At a command prompt:

   java -version

   If that reports a 64-bit Java 11 or later, skip the next step.

2. Install Java if it did not: a 64-bit JDK from Adoptium or oracle.com.

3. Put the jar wherever is convenient. Do not uncompress it.

4. Launch it, by double-clicking or with:

   java -jar stepss.jar

   On Windows, if a double-click does nothing, right-click the jar, choose “Open with”, and point it at Java.

The jar installs nothing alongside itself and needs nothing installed for plotting: STEPSS draws its own curves, during a run and after one.

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

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.