Skip to main content

Installation

This page walks through installing the CHAMPS+ solver from a distribution archive.

Prerequisites​

Before you begin, you should have received a distribution archive from your Whoosh HPC point of contact — either champs.distrib.tar.gz or champs.distrib.zip. This archive is self-contained: it includes the champs+ executable, its supporting libraries, your license file, and a set of ready-to-run tutorial cases.

You will also need a working MPI installation (e.g. OpenMPI or MPICH) already present on your machine. CHAMPS+ does not currently bundle its own MPI runtime — champs+ links against whatever MPI is already installed and discoverable on your system.

Getting Started​

1. Extract the distribution archive​

Unpack the archive to a location of your choice:

tar -xzf champs.distrib.tar.gz

Or, if you received a .zip archive:

unzip champs.distrib.zip

This produces a champs.distrib directory with the following contents:

champs.distrib/
├── champs+        # the solver executable
├── license        # your license file
├── lib/           # supporting libraries used by champs+
└── tutorials/     # ready-to-run tutorial cases

You don't need to interact with the lib directory directly — it just needs to stay alongside the champs+ executable. The license file also doesn't need to be touched: champs+ automatically finds it since it sits next to the executable, so there's no separate licensing step.

2. Add champs+ to your PATH​

Add the champs.distrib directory to your PATH so the champs+ executable can be run from anywhere. Add the following to your shell profile (e.g. ~/.bashrc, ~/.zshrc):

export PATH="/path/to/champs.distrib:$PATH"

Replace /path/to/champs.distrib with the actual location where you extracted the archive in step 1.

Reload your shell profile, or open a new terminal, for the change to take effect.

3. Verify the installation​

Open a new terminal (so your updated profile is loaded) and confirm that champs+ is discoverable on your path:

which champs+

This should print the path to the executable inside your champs.distrib directory. From there, you're ready to move on to the Getting Started tutorial to run your first case — or run one of the cases bundled in champs.distrib/tutorials/ directly.

tip

If champs+ fails to start with an error about a missing shared library such as libmpi.so, it means no compatible MPI installation could be found on your system. Install MPI (e.g. OpenMPI or MPICH) through your system's package manager, or an HPC module system, and make sure it's on your PATH/LD_LIBRARY_PATH before trying again.

Advanced Setup​

The steps above cover the common case: a single champs.distrib install, used by one person, with the bundled license file left where it is. This section covers how to customize that behavior — for example, running a shared/site-wide install where individual users supply their own license, or keeping license and state files outside the distribution directory.

License resolution order​

When champs+ starts, it searches for a license file in the following order, stopping at the first one it finds:

  1. -license <path> command-line flag — an explicit path passed on the command line for that run. This always wins, regardless of any environment variable. See the Command Line Overview for details.
  2. CHAMPS_LICENSE_FILE environment variable — a direct path to a license file.
  3. CHAMPS_HOME environment variable — a directory expected to contain a file named license.
  4. The champs.distrib directory itself — i.e. the license file that ships next to the champs+ executable. This is the fallback used by the Getting Started steps above, and requires no configuration.

This gives you two general ways to organize licensing:

  • Site license — leave the bundled license file where it is in champs.distrib (or point CHAMPS_HOME at a shared directory containing a copy of it). Every user who runs that install picks up the same license automatically, with no per-user configuration. This is the default, out of the box.
  • User license — set CHAMPS_LICENSE_FILE in each user's shell profile to point at their own license file. This lets multiple users share a single read-only champs.distrib install (for example, on a cluster) while each using their own license, and takes precedence over the bundled site license in step 4 above.
tip

You can also override the license for a single run without touching any environment variables, using the -license [path] flag:

champs+ input.sdf -license /path/to/custom/license

The CHAMPS_DATA state directory​

Separately from licensing, champs+ maintains a small per-user directory for settings and persistent state (used, for example, by the command server). By default this is created automatically, in the first writable location from the following list:

  1. CHAMPS_DATA environment variable, if set.
  2. A platform-specific default:
    • Linux: $XDG_DATA_HOME/champs, or ~/.local/share/champs if XDG_DATA_HOME is unset.
    • macOS: ~/Library/Application Support/champs.
    • Windows: %LOCALAPPDATA%\champs.
  3. ~/.champs, as a last resort.

Most users never need to set this — it's only useful if you want to redirect where champs+ stores its state, for example to keep it off a network home directory.

export CHAMPS_DATA=/path/to/state/directory