> ## Documentation Index > Fetch the complete documentation index at: https://docs.claviscage.app/llms.txt > Use this file to discover all available pages before exploring further. # Uploading Files > How to prepare and upload structure files for analysis # 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? | Guide card | Choose this when | File picker focuses on | | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- | | **GROMACS** | You have a GROMACS coordinate file or a paired native trajectory. Use this for single `.gro` files, exact `.gro + .xtc/.trr` metadata workflows, or supported `.tpr + .xtc/.trr` pairs. | `.gro`, `.xtc`, `.trr`, `.tpr` | | **LAMMPS** | You have LAMMPS text trajectory data and need Clavis to map units plus atom-type roles before playback or analysis. Use this for `.data + dump` sets or standalone dumps with usable `ITEM: ATOMS` rows. | `.data`, `.lammpstrj`, `.dump`, `.lammpsdump` | | **Static Structure** | You only want to visualize one coordinate structure and do not need a paired trajectory workflow. | `.gro`, `.pdb`, `.cif`, `.mmcif` | 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: | Mode | Behavior | Best for | | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | | **Normal scene** | Parses the file into browser memory; multi-frame GRO supports sampled TRACE/HTR/GRADE and F3/F4 ranges | Single structures and moderate `.gro` trajectories | | **Large trajectory** | Streams GRO frame slices through a browser worker; sampled TRACE/HTR/GRADE and F3/F4 ranges use the same algorithm-owned result contract | Very large multi-frame `.gro` files | | **Native binary GROMACS** | Indexes paired topology/trajectory files and decodes selected XTC/TRR frame slices; TRACE/HTR/GRADE, F3/F4, and CHILL+ use the selected Start/End/Step range without algorithm substitution | `.gro + .xtc/.trr` exact metadata inspection and supported `.tpr + .xtc/.trr` inspection | | **LAMMPS mapped playback** | Uses a mapping wizard and file-backed dump slices; current-frame and selected-range TRACE/HTR/GRADE/F3/F4/CHILL+ analysis is enabled after valid water mapping | Selected-frame inspection and algorithm-owned time series for mapped LAMMPS dumps | 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 Use the **UPLOAD STRUCTURE** guide to choose **GROMACS**, **LAMMPS**, or **Static Structure** before selecting files. Clavis accepts `.gro`, `.pdb`, `.cif`, `.mmcif`, `.xtc`, `.trr`, `.tpr`, `.data`, `.lammpstrj`, `.dump`, or `.lammpsdump`. For native GROMACS binary playback, select the matching `.gro` or supported `.tpr` topology and `.xtc` or `.trr` trajectory together. Standalone `.tpr` files and orphan `.xtc`/`.trr` files cannot open a trajectory session by themselves. LAMMPS playback can use either one `.data` topology plus one dump trajectory or a standalone dump whose `ITEM: ATOMS` rows include atom `type` metadata; mapped water analysis additionally requires `mol` grouping. Clavis can map a `.data + .lammpstrj/.dump/.lammpsdump` pair or a standalone dump with type rows, display mapped dump frames from file-backed frame slices, and run current-frame WASM analysis after water mapping. It also runs mapped LAMMPS TRACE, HTR, GRADE, and F3/F4 analysis over a chosen sampled frame range. If no scene opens, confirm that dump-only files include `id`, `type`, and `mol` columns for mapped water grouping, or reselect a matching `.data + dump` set. Load the matching `.gro` structure as the topology with the same `.xtc/.trr` trajectory. The browser TPR reader is a targeted decoder and cannot parse every TPR binary — newer or mixed layouts (for example newer TPX format versions) fail safely with on-screen guidance instead of being relabeled as generic water. The `.gro` topology carries full atom and residue names by atom index and renders identically, so it is the reliable path whenever a TPR is rejected. Verify that cage-forming waters use a supported residue name: SOL, HOH, WAT, H2O, TIP\*, SPC\*, HSL, ICE, or HYD. Confirm that guest residues are non-water residue names and that TRACE, GRADE, or complete-cage HTR analysis has been run for the current frame or trajectory. Recovery is session-local and normal-size only. Private browsing, cleared browser storage, a new device, or large streaming mode can prevent restoration.