> For the complete documentation index, see [llms.txt](https://wiki.solids.group/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wiki.solids.group/alamo/zephyr.md). # Getting Started with Zephyr [Zephyr](https://zephyr.solids.group) 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](https://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. {% hint style="warning" %} 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](/research-practices/data-management.md) for large `cell` and `node` datasets. {% endhint %} ## 1. Install `zph` `zph` supports Python 3.7 or newer and has no runtime package dependencies. Install it from the copy hosted by Zephyr: ```bash 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`: ```bash export PATH="$HOME/.local/bin:$PATH" ``` Add that line to `~/.bashrc` if it is needed every time you log in. Confirm the installation: ```bash zph --version ``` Inside an activated virtual environment or Conda environment, omit `--user` from the installation command. To install a newer version later, run: ```bash zph --upgrade ``` ## 2. Connect Alamo to Zephyr Add `--zephyr` to the normal Alamo configuration command. For example: ```bash ./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. {% hint style="info" %} If Alamo is already configured, or if you only need to reconnect the CLI, run `zph login https://zephyr.solids.group` directly. {% endhint %} ## 3. Post a simulation Add the boolean `--post` option when starting Alamo: ```bash ./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: ```bash 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](https://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: ```bash zph import output.481516 ``` To discover and register every Alamo output below a path: ```bash zph add /scratch/$USER/alamo-runs ``` Wildcards are supported: ```bash 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: ```bash 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: ```bash 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: ```bash 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: ```bash 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: ```bash 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. {% hint style="warning" %} 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. {% endhint %} ## 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: ```bash 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: ```bash 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 ```bash 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`: ```bash 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: ```bash 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: ```bash zph put --directory output.481516 /path/to/file.png ``` Use `--dry-run` first when testing a broad wildcard. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://wiki.solids.group/alamo/zephyr.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.