​

Uploading Structure Files

Clavis accepts browser-local structure inputs for hydrate structures, water networks, guest-containing systems, and mixed material systems. Supported text formats:

• GROMACS .gro
• Protein Data Bank .pdb
• CIF/mmCIF .cif and .mmcif

Recognized GROMACS binary formats:

• .xtc and .trr trajectory files
• .tpr run-input/topology files

LAMMPS text inputs with a first-frame visualization preview:

• .data topology files
• .lammpstrj, .dump, and .lammpsdump trajectory dumps

Binary GROMACS trajectories need topology metadata for atom names, residue names, residue numbers, and atom ordering. Select either a matching .gro topology or a supported .tpr topology with the matching .xtc or .trr trajectory in the same upload action. Clavis indexes the paired trajectory locally in a browser worker, opens the first frame in the scene, and decodes only selected frame slices for PREV, NEXT, and JUMP controls instead of materializing every binary frame during session open. Large scenes use a capped instanced-sphere preview and suppress bonds only while a frame load, playback step, or dense analysis visualization commit is active; once settled, the scene expands to full atoms and bonds. Current-frame analysis can request the full selected frame data independently of the transition preview. Direct slider scrubbing is disabled for native binary trajectories; use PLAY, PREV, NEXT, or JUMP, then run current-frame analysis on the selected frame. For exact mixed-residue labels, .gro + .xtc/.trr is the preferred path because the GRO atom table is preserved by atom index. Supported .tpr + .xtc/.trr pairs still open natively, but unsupported mixed TPR layouts fail with guidance instead of being relabeled as generic water. Standalone .tpr files are topology metadata only. Orphan .xtc or .trr files need the matching .gro or .tpr before Clavis can build atom and residue labels for native playback. LAMMPS support is intentionally scoped but no longer limited to display. A paired .data + .lammpstrj/.dump/.lammpsdump upload opens a mapping wizard for unit style and atom-type roles, then worker-loads mapped dump frames into the normal scene for selected-frame playback. Standalone .lammpstrj/.dump/.lammpsdump uploads also open the wizard by reading the first dump frame for atom type ids; dump-only hydrate analysis fails closed unless the dump provides id, type, and mol columns that form valid 1 O + 2 H water groups. When the mapping yields water molecules, the selected frame can run TRACE/HTR/GRADE and F3/F4 through the browser WASM engine; restricted triclinic dump cells use cell-aware analysis paths when available. The mapped LAMMPS worker indexes dump frame ranges and reads requested frame slices from the uploaded file, so sampled TRACE, HTR, GRADE, and F3/F4 time series can run over the selected frame range with cancellable progress and explicit algorithm identity. Mismatched LAMMPS files show guidance instead of opening a scene.

​

File Requirements

Your structure file should contain:

• Water molecules with supported residue names such as SOL, HOH, WAT, H2O, TIP*, SPC*, or hydrate-water aliases such as HSL, ICE, and HYD
• Periodic boundary information where available (.gro box vectors, PDB CRYST1, or coordinates sufficient for a fallback scene box)
• Coordinate records in a supported text format
• Optional non-water guest residues such as methane, cyclopentane, THF, or other guest molecules
• Optional metal/slab or geologic residues such as SLAB, Fe, MMT, or MONT
• One or more .gro frames for browser-local trajectory workflows

​

Upload Process

1. Click UPLOAD STRUCTURE in the app header.
2. Choose an import path in the guide dialog:
   • GROMACS for .gro structures, .gro + .xtc/.trr, or .tpr + .xtc/.trr trajectory pairs.
   • LAMMPS for .data + .lammpstrj/.dump/.lammpsdump sets, or standalone dumps with usable ITEM: ATOMS type rows. This path opens the mapping wizard for units and atom-type roles before loading frames.
   • Static Structure for single .gro, .pdb, .cif, or .mmcif files when no trajectory pairing is needed.
3. Select your file or paired files in the system file picker. LAMMPS .data + .lammpstrj/.dump/.lammpsdump sets, plus standalone dumps with usable ITEM: ATOMS type rows, open a mapping wizard, load mapped dump frames, and support current-frame analysis plus TRACE/HTR/GRADE/F3F4 trajectory ranges after valid water mapping.
4. Wait for parsing or streaming initialization.
5. Confirm the molecule count, frame count, and current frame summary in the app panel.

​

Which import path should I choose?

The guide only narrows the system file picker to reduce wrong-file selections. After you choose files, Clavis still validates the actual file combination and shows GROMACS or LAMMPS-specific guidance if a required topology, trajectory, molecule id, or mapping step is missing. Long-running parsing, streaming, and analysis tasks display a live scene overlay with determinate progress when frame counts are known and indeterminate status when the operation is still preparing. On mobile, the app uses a compact header and stacks the scene above the control panel so uploads, tabs, and scene navigation remain reachable on a phone screen.

​

Normal Files vs. Large Trajectories

Clavis uses two paths depending on file size: Normal-size scenes can be restored after accidental refresh/navigation. Large streaming trajectories are not stored in browser session recovery; re-upload the file if the session is lost.

​

Guest Molecules

Guest molecules can be included in the same structure file as water or loaded as a separate layer. Clavis treats non-water, non-material residues as candidate guests for occupancy analysis and occupied-guest visualization. Hydrate-water aliases such as HSL are treated as cage-forming water, not as guests. Metal/slab and geologic residues are acknowledged as material structures and receive deterministic residue coloring.

​

Troubleshooting