Sylphium Plexus — Wiki

Short guide for researchers and volunteers: how to package jobs and campaigns, what parameters mean, and how to deploy clients.

---

Roles

Role	Capabilities
Volunteer	Attach nodes, pick researches, enable/disable engines
Researcher	Create researches, submit own jobs and campaigns, track progress
Admin	Everything above + quotas, research moderation, network inventory tokens / mint overlay keys, remove workers

Default role after registration is volunteer. An admin promotes researchers.

---

Research projects

1. Open Research → create a project (slug, title, description).
2. Description and public posts support Markdown (headings, lists, code, tables).
3. Link jobs and campaigns to a research so volunteers see progress and attribution.
4. Public page: /research/{slug} (after admin moderation when required).

---

Single job

Via UI

The usual path does not ask for JSON or a container image name.

1. Sign in as a researcher or admin.
2. Open Campaigns → New campaign.
3. Pick a checked example (docking or electronic structure). The cluster lists only examples it is willing to run.
4. Set a title, how many copies, and — only if you need to — memory and time limit. Those start from the example.
5. Review the task ids, then submit. One unchanged task uses the single-job form. Several copies, or a changed memory/time limit, are packed for you and checked with Validate before submit.
6. Track one task under Jobs, or the batch under Campaigns.

Submit still accepts one example or a ZIP if you already have an archive. Attach a research project on either screen; that field is optional.

Catalog ids are the example input folders, not image tags. Checked against the example tree: vina/ethanol_dock/input (job_id vina-ethanol-dock) and orca/water_sp/input (job_id water_sp_001). The screen shows whatever /api/examples returns for your account.

Archive layout

my-job.zip
├── job_spec.json
├── receptor.pdbqt
└── ligand.pdbqt

job_spec.json must match packages/schemas/job_spec.schema.json.

Required job_spec.json fields

Field	Purpose
job_id	Unique id; S3 keys jobs/{job_id}/…
engine	smina, vina, orca, cp2k, nwchem, qe, bigdft, xtb, crest, gromacs, psi4, opencosmo
engine_version	Engine/image version
entrypoint	Main input file relative to input/
resources.ram_mb	RAM requirement (min 256)
resources.walltime_sec	Container time limit (min 60)
required_outputs	Files required for a successful result

Useful optional fields

Field	Purpose
log_file	Engine log under output/ (or output/work/). Live logs on the job page stream this file's contents (any engine).
resources.cpus	CPU limit
resources.disk_mb	Scratch disk hint
research_id	Link to research (or set in the UI form)
compress_outputs	Gzip large outputs
Engine block (vina, orca, …)	Engine-specific options

Example

This is the job_spec.json shipped at packages/examples/vina/ethanol_dock/input/job_spec.json. The guided screen copies that file and the sibling receptor.pdbqt / ligand.pdbqt. It is a spec, not a record of a completed run.

{
  "job_id": "vina-ethanol-dock",
  "engine": "vina",
  "engine_version": "1.2",
  "entrypoint": "receptor.pdbqt",
  "resources": { "ram_mb": 1024, "walltime_sec": 900, "cpus": 1, "disk_mb": 512 },
  "required_outputs": ["docking.log", "out.pdbqt"],
  "log_file": "docking.log",
  "vina": {
    "receptor": "receptor.pdbqt",
    "ligand": "ligand.pdbqt",
    "exhaustiveness": 4,
    "center_x": 0,
    "center_y": 0,
    "center_z": 0,
    "size_x": 18,
    "size_y": 18,
    "size_z": 18
  }
}

Researcher quotas

Limit	Effect
max_parallel_jobs	Cap on pending + assigned
max_cpu_hours	CPU-hour budget
max_ram_mb	Per-job RAM ceiling

Before heavy jobs, open Capacity to see how many nodes can accept your ram_mb / walltime / engine.

Example archives by engine

At the bottom of this page — ready ZIP files for each engine.

• Only runnable examples are listed (mock / ALLOW_MOCK are hidden).
• Archive format matches Submit: job_spec.json at ZIP root.
• Download ZIP and upload via Submit → ZIP, or pick the same example under Campaigns → New campaign or Submit → Example.
• Catalog ids end in /input. Files on disk include vina/ethanol_dock/input, smina/ethanol_dock/input, orca/water_sp/input, cp2k/water_energy/input, nwchem/water_sp/input, qe/water_scf/input, bigdft/water_lda/input. Mock folders are omitted from the public list.

Common input pitfalls

• job_id must be unique — resubmit of the same id is rejected; add a suffix for retries.
• walltime_sec: long DFT Opt of organics often needs ≥7200 s; XTB2 Opt then SP is a safer chain.
• Smina: score ≈ −0.0002 usually means the ligand left the pocket — start geometry inside the box; check minimizedAffinity.
• Meeko → smina 2017: atom types CG0/G0 often cause rc=1 — remap to C/H in the PDBQT.
• ORCA: an extra * after * xyzfile … → rc=55.
• Details: docs/SUBMIT_JOB.md (Field notes).

---

Campaigns

A campaign is several tasks submitted together.

When to use

Mode	When
One task	A single copy of a checked example
Campaign	Several copies of that example, or a zip you packed yourself
Own archive	Tasks that are not copies of one example (different ligands or inputs)

Guided flow

Campaigns → New campaign builds the archive in the browser:

1. Choose a checked example.
2. Title, number of tasks (1–24 in this screen), memory, time limit, optional research.
3. Review the generated task ids. A batch is sent to POST /api/campaigns/validate before submit. One unchanged task uses POST /api/jobs with example_id.
4. After submit, open the campaign or the job. Results stay for 72 hours unless you pin them on the job page.

There is no separate “assemble from example” API. If the example download is missing, one unchanged task can still be submitted; a batch cannot be built until that download works. Larger or mixed inputs stay on I already have a campaign archive.

campaign.zip layout

campaign.zip
├── manifest.json
└── jobs/
    ├── dock_lig001/
    │   ├── job_spec.json
    │   └── …
    └── dock_lig002/
        └── …

manifest.json

Field	Purpose
campaign_id	Unique campaign slug
title	Human-readable title
research_id	Research (can override in UI)
description	Notes

Archive path: Campaigns → New campaign → I already have a campaign archive → Validate → Submit. Progress is on the campaign page. Export is a ZIP plus index.csv.

Visibility: only the creator and admins can see a campaign. Other researchers cannot see each other’s campaigns (API and UI).

---

Engines

The task form lists orca, cp2k, smina, vina, nwchem, qe, bigdft, xtb, crest, gromacs, psi4, and opencosmo. Only ORCA stays gated. Campaigns → New campaign still lists the examples the API returns.

xtb, crest, gromacs, psi4, and opencosmo are in job_spec.schema.json. Specs under packages/examples/ were checked against that schema (JSON Schema draft 2020-12). A schema pass is not a finished calculation. On 2026-10-20 the tags below were built on a local Docker Desktop (amd64) and were not pushed to a registry. Ubuntu 24.04 bases already use uid 1000; those Dockerfiles rename that account to sylphium instead of useradd.

Engine	Packaged version	Check
ORCA	Pin stays 6.0.1. 6.1.1 was not packaged (license forbids redistribution).	Schema pass for orca/water_sp. Container not started.
CP2K	2026.2	Schema pass for cp2k/water_energy_2026_2. Image not built.
Smina	2017.11.9 (no newer release)	Schema pass for smina/ethanol_dock. Not started.
AutoDock Vina	1.2.7	Schema pass for vina/ethanol_dock_1_2_7. Local tag sylphium/vina:1.2.7 prints AutoDock Vina v1.2.7. The worker pin stays on the older biocontainers image.
NWChem	7.3.1	Schema pass for nwchem/water_sp_7_3_1. Image not built.
Quantum ESPRESSO	7.6 (CPU)	Schema pass for qe/water_scf_7_6. Image not built.
BigDFT	1.9.6	Schema pass for bigdft/water_lda_1_9_6. Image not built.
xtb	6.7.1	Local tag sylphium/xtb:6.7.1. Water GFN2 single point finished: total energy −5.070318052192 Eh.
CREST	3.0.2	Local tag sylphium/crest:3.0.2 starts and prints the CREST banner. The image also contains xtb 6.7.1. A conformer search was not run.
GROMACS	2026.4	Local tag sylphium/gromacs:2026.4. gmx --version prints 2026.4 (mixed precision, SSE2, no GPU). The Dockerfile renames uid 1000 and caps cmake --build jobs by free memory. A trajectory was not run. The image was not published.
Psi4	1.11 (image tag 1.11.0)	Local tag sylphium/psi4:1.11. psi4 is on PATH via /opt/conda/bin. Water HF/STO-3G finished: total energy −74.96340594386264 Eh.
openCOSMO-RS	Parameterization 24a	Local tag sylphium/opencosmo:24a. Open COSMO-RS model (LGPL-3.0), not commercial COSMOtherm and not BIOVIA COSMO-RS. openCOSMORS24a().name prints 24a. The image installs the Python runtime that package imports (including plotly).

Worker pins in clients/worker/engine-images.env already name sylphium/xtb:6.7.1, sylphium/crest:3.0.2, sylphium/gromacs:2026.4, sylphium/psi4:1.11, and sylphium/opencosmo:24a. Those tags exist only on the machine that built them. A worker elsewhere cannot pull them until they are loaded there or published. Pins for CP2K, Vina, NWChem, Quantum ESPRESSO, and BigDFT were not switched. This site does not point a worker at a new Dockerfile by itself.

---

Client deployment scenarios

Install claim tokens are created on Volunteer (time-limited). Use a unique --host-id on every machine.

Bootstrap vs overlay URL

URL	Purpose
PUBLIC_API_URL / bootstrap_api_url	Download installer before mesh join (internet)
WORKER_API_URL	--cluster-url and runtime after join (tailnet)

The Volunteer UI already splits public download vs overlay --cluster-url. The update one-liner still downloads from the public URL; after join, idle auto-update uses the overlay manifest.

Inventory network tokens (Admin → Network tokens) are DB labels only — not mesh auth keys. Real --auth-key: Tailscale/Headscale console, or Admin → Mint overlay auth key when TAILSCALE_* / HEADSCALE_* are set.

1. Rootless Podman (recommended)

Pros

• No sudo after packages are installed
• Good for shared / lab machines
• Container isolation without a root daemon

Cons

• Needs podman, python3, linger (loginctl enable-linger)
• Rootless setup can be harder on some distros
• Slightly more steps than one sudo command

# Download from PUBLIC_API_URL; --cluster-url = WORKER_API_URL
curl -fsSL https://api.example.com/installers/install-compute-worker.sh -o "$HOME/icw.sh"
bash "$HOME/icw.sh" --rootless --runtime podman \
  --cluster-url http://central.tailnet:8888 \
  --claim-token <TOKEN> \
  --host-id worker-$(hostname)-01

1b. Full rootless + overlay in container (no host Tailscale)

In UI: Volunteer → enable Overlay in container → paste a real mesh --auth-key → Get install command.

bash "$HOME/icw.sh" --non-interactive --rootless --runtime podman \
  --network-in-container \
  --network-backend tailscale \
  --auth-key tskey-auth-... \
  --cluster-url http://central.tailnet:8888 \
  --claim-token <TOKEN> \
  --host-id worker-$(hostname)-01

Do not combine --join-network and --network-in-container. Details: NETWORK.md, CONNECT_NODE.md.

2. Docker (with sudo)

Pros

• Familiar runtime
• Easier on servers that already run Docker
• Good for dedicated VPS / bare metal

Cons

• Needs sudo / docker group
• Larger attack surface on shared hosts
• Avoid on others' lab machines without admin approval

sudo bash icw.sh \
  --cluster-url http://<api-host>:8888 \
  --claim-token <TOKEN> \
  --host-id worker-$(hostname)-01

3. Multiple nodes per account

Pros

• One claim token, many machines
• Research opt-in and quotas are per user
• Attribution per node_uid

Cons

• Keep --host-id unique
• CPU/RAM limits are set per node at install time

4. Windows (Podman Desktop → WSL)

Podman/Docker on Windows always use a Linux VM (WSL2 by default). There is no native Win32 worker.

1. Install Podman Desktop and complete onboarding (Podman + machine).
2. Install a regular WSL distro (e.g. Ubuntu).
3. Inside WSL, run the Linux rootless or Docker install above.
4. Or from PowerShell: download /installers/install-compute-worker.ps1 (Volunteer UI prints this for OS=Windows).

After install

1. Node appears under Volunteer (or waiting to link).
2. Enable the needed engines.
3. Choose research opt-in — preferences apply to all your nodes.
4. Online status: Workers; coverage estimate: Capacity.

---

Useful UI links

• Capacity — how many online / all nodes fit the resources
• Submit / Campaigns — submit work
• Example ZIPs (below) — ready archives per engine
• Research — projects and Markdown posts
• Volunteer — install command and engines