Getting Started with Zephyr

Zephyr is the Solid Mechanics Group's workspace for tracking Alamo simulations. It records where and how a simulation ran, monitors active jobs, keeps the Alamo metadata and thermodynamic history, and provides a place to organize and share selected results.

Zephyr has two parts:

• The web interface at zephyr.solids.group, where you browse runs, monitor jobs, compare results, and organize projects.
• The zph command-line client, which connects Alamo output on a workstation or cluster to Zephyr.

Seeing a run in Zephyr does not mean its large raw dataset has been uploaded or archived. Zephyr stores provenance, monitoring data, and files explicitly uploaded with zph put. Continue to use the group's data-management and archival practices for large cell and node datasets.

1. Install zph

zph supports Python 3.7 or newer and has no runtime package dependencies. Install it from the copy hosted by Zephyr:

python3 -m pip install --user --upgrade \
  'https://zephyr.solids.group/downloads/zph-latest.tar.gz'

If this is a system Python installation, make sure the user-level binary directory is on your PATH:

export PATH="$HOME/.local/bin:$PATH"

Add that line to ~/.bashrc if it is needed every time you log in. Confirm the installation:

zph --version

Inside an activated virtual environment or Conda environment, omit --user from the installation command.

To install a newer version later, run:

zph --upgrade

2. Connect Alamo to Zephyr

Add --zephyr to the normal Alamo configuration command. For example:

./configure --get-eigen --zephyr https://zephyr.solids.group

The configure script asks zph to display a temporary login URL and attempts to open it automatically. Sign in using your group Google account. When working over SSH on a cluster, copy the displayed URL into a browser on your own computer. The terminal will continue automatically after authentication succeeds; there is no token to paste.

Authentication is stored in your user configuration, not in the Alamo source tree or simulation directories. Repeat this step on each workstation or cluster account that needs to post runs.

If Alamo is already configured, or if you only need to reconnect the CLI, run zph login https://zephyr.solids.group directly.

3. Post a simulation

Add the boolean --post option when starting Alamo:

./bin/alamo-2d-g++ --post input

Use the executable and input file appropriate for your build. In a Slurm script, the same option goes on the Alamo command:

srun --mpi=pmix ./bin/alamo-3d-g++ --post input

Alamo starts a lightweight zph sidecar. While the solver runs, the sidecar sends heartbeats and refreshes the run status, metadata, thermo.dat, standard output, Git revision, and Git diff. Zephyr failures do not stop the simulation itself.

Open zephyr.solids.group after the run begins. A Slurm run should appear in Running jobs with its job name, job ID, cluster, partition, resources, output directory, and current standard output. The Runs view retains the record after the job finishes.

4. Add simulations that already exist

To register one completed output directory:

zph import output.481516

To discover and register every Alamo output below a path:

zph add /scratch/$USER/alamo-runs

Wildcards are supported:

zph add 'output*'

zph add recognizes a run by the HASH in its metadata file. It safely skips the large numbered BoxLib cell and node trees during recursive discovery. Its output identifies records as added, updated, skipped, or failed.

To preview discovery without changing Zephyr, use:

zph add --dry-run /scratch/$USER/alamo-runs

5. Record where copies are stored

Use zph sync when a simulation directory has been copied, moved, or changed:

zph sync /scratch/$USER/alamo-runs

This updates Zephyr's inventory of known locations, paths, file counts, and whether a location contains Alamo simulation data. It does not upload the files. Zephyr retains older known locations and the last time each copy was updated.

On shared systems, Zephyr uses SLURM_CLUSTER_NAME when available. You can provide a stable site name yourself:

export ZEPHYR_SITE=nova
zph sync /scratch/$USER/alamo-runs

A normal sync avoids descending into expensive BoxLib data trees. Use zph sync --deep PATH only when you specifically need an exact scan of every file and byte.

6. Upload useful artifacts

Use zph put for selected files that should be viewable and recoverable from Zephyr, such as plots, animations, processed tables, input files, or postprocessing scripts:

zph put output.481516/plot.png
zph put 'output.481516/images/**/*.png'
zph put '*.png' '*.webm' '*.gif'

For each file, zph searches upward for the nearest Alamo metadata file. Artifacts in subfolders retain their relative paths. For example, output.481516/images/frame.png is stored as images/frame.png for the run described by output.481516/metadata.

You can explicitly associate files with a run directory when necessary:

zph put --directory output.481516 figures/summary.png

Images, GIFs, and WebM movies can be previewed in the web interface. In a run's Artifacts view, select a representative image or movie as its thumbnail.

Do not use zph put as a substitute for archiving large raw Alamo output trees. Upload the compact files needed for understanding, comparing, sharing, and reproducing a result; archive large datasets using group storage.

7. Organize runs in the web interface

The main views are:

• Dashboard: recent projects, active jobs, and uncategorized runs.
• Runs: search metadata, paths, and artifact filenames; filter by status, storage site, thumbnail, or uncategorized state.
• Running jobs: monitor active Slurm jobs and inspect their current standard output.
• Compare: compare metadata and overlay compatible run data.
• Projects: arrange runs into folders, browse project artifacts, and share a coherent collection of simulations.

In the Runs view, use Ctrl-click (or Command-click on macOS) to select individual runs and Shift-click to select a range. Choose Add to project to add one or more selected runs. You can create a project or nested destination folder without leaving the dialog.

Inside a project, drag selected runs into folders. Folder open/closed state is remembered in the browser. Project visibility can be private, group-wide, or public; use private visibility until you intentionally want others to have access.

8. Restore a run

Download a run using its original output-directory name, Alamo HASH, or Zephyr run ID:

zph get output.481516

If the directory name is ambiguous, zph presents a list of matching runs. If the destination already exists, it offers safe rename, alternate-path, merge/overwrite, and cancel choices.

For non-interactive use:

zph get output.481516 --rename
zph get HASH --output /work/$USER/restored-run
zph get HASH --dry-run

The restored directory contains the run record and the artifacts that were actually stored in Zephyr. Raw files that were only inventoried with zph sync are not downloaded.

Useful commands

zph list --status running
zph list --search ignition
zph compare HASH_A HASH_B
zph --upgrade

Run zph COMMAND --help for all options.

Troubleshooting

zph: command not found

Check the installation and your PATH:

python3 -m pip show zph
export PATH="$HOME/.local/bin:$PATH"

The cluster cannot open a browser

This is expected on many login nodes. Copy the URL printed by configure or zph login into a browser on your local computer. Leave the terminal command running while you authenticate.

A run does not appear

Confirm that:

1. zph is installed and available on the compute node's PATH.
2. This cluster account has been authenticated.
3. The Alamo command includes --post.
4. The output directory contains a metadata file with a HASH.

You can register or refresh the output afterward with:

zph add output.481516

A file does not upload

The file must either be below a directory containing Alamo metadata, or you must supply the run directory explicitly:

zph put --directory output.481516 /path/to/file.png

Use --dry-run first when testing a broad wildcard.