​

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

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 decodes the paired files locally in a browser worker, opens the first frame in the scene, and provides selected-frame PREV, NEXT, and JUMP controls for dense native sessions. Native frames render with the full instanced-sphere molecular style — the same appearance as a static .gro of the same system, including bonds at rest. Streaming each frame’s coordinates into the existing geometry keeps frame jumps responsive; during the brief in-flight fetch the viewport is momentarily lightened, then the full structure is shown when the frame settles. Continuous scrubber playback is disabled for native binary trajectories; use the frame controls, 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.

​

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. Select your file, or select a paired .gro + .xtc, .gro + .trr, .tpr + .xtc, or .tpr + .trr trajectory set
3. Wait for parsing or streaming initialization
4. Confirm the molecule count, frame count, and current frame summary in the app panel

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