For the complete documentation index, see llms.txt. This page is also available as Markdown.

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.

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:

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:

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

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:

To discover and register every Alamo output below a path:

Wildcards are supported:

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:

5. Record where copies are stored

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

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:

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:

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:

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.

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:

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:

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

Run zph COMMAND --help for all options.

Troubleshooting

zph: command not found

Check the installation and your 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:

A file does not upload

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

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

Last updated

Was this helpful?