> ## 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.

# FAQ

> Frequently asked questions about Clavis

# Frequently Asked Questions

## General

<AccordionGroup>
  <Accordion title="What file formats does Clavis support?">
    Clavis supports `.gro`, `.pdb`, `.cif`, and `.mmcif` text structures. **UPLOAD STRUCTURE** opens an import guide so you can choose **GROMACS**, **LAMMPS**, or **Static Structure** before the system file picker appears. The GROMACS path covers `.gro` plus paired `.gro + .xtc`, `.gro + .trr`, `.tpr + .xtc`, or `.tpr + .trr` sets. The LAMMPS path covers paired `.data + .lammpstrj/.dump/.lammpsdump` inputs and standalone dumps with `ITEM: ATOMS` type rows for mapped dump-frame playback, selected-frame WASM analysis, and sampled TRACE/HTR/GRADE/F3F4 ranges.
  </Accordion>

  <Accordion title="Does Clavis require a backend upload for analysis?">
    Current analysis and visualization workflows are designed around browser-side parsing, WebAssembly analysis, workers, and local rendering. Account, billing, and usage APIs still use hosted services, but structure analysis does not require a Python backend upload path.
  </Accordion>

  <Accordion title="How many frames can I analyze?">
    Free users have a monthly frame quota. Pro subscribers have unlimited frame analysis and Pro export features.
  </Accordion>

  <Accordion title="What is the difference between TRACE, HTR, and GRADE?">
    TRACE finds general face-signature cages with SEC/nSEC/IC quality. HTR uses a fixed 0.35 nm oxygen-only graph for primitive rings and generalized `n4-n5-n6` cages. Native GRADE finds only `5^12`, `5^12·6^2`, and `5^12·6^4` cages and their filled counts; it does not produce a crystal-structure verdict or confidence score.
  </Accordion>

  <Accordion title="Where does CHILL+ fit into the analysis workflow?">
    CHILL+ classifies each cage-forming water into liquid/other, hexagonal ice, cubic ice, interfacial ice, gas hydrate, or interfacial hydrate environments. It is useful for spatial maps and time-series fractions. Use TRACE when you need explicit closed-cage topology and cage types. See [CHILL+ Classification](/analysis/chill-plus).
  </Accordion>
</AccordionGroup>

## Analysis

<AccordionGroup>
  <Accordion title="What H-bond cutoff should I use?">
    The default 3.5 Å (0.35 nm) is a common starting point. Adjust it for pressure, force field, and trajectory-specific behavior.
  </Accordion>

  <Accordion title="Why are some cages labeled incomplete?">
    Incomplete cages are partially formed or imperfect cage-like structures. They are common near interfaces, defects, or hydrate formation fronts.
  </Accordion>

  <Accordion title="Can Clavis analyze guest occupancy?">
    Yes. After TRACE, GRADE, or complete-cage HTR analysis, Clavis reports θ\_S, θ\_L, Overall occupancy, filled/empty cage counts, and per-cage-type guest counts when guest residues are present.
  </Accordion>

  <Accordion title="Can occupied guests be highlighted without showing cage wireframes?">
    Yes. The occupied guest highlight control is independent from cage wireframe visibility, while still using cage assignment data from analysis.
  </Accordion>

  <Accordion title="Why did changing SDS or NA affect my CHILL+ view?">
    In current versions, it should not. CHILL+ class visibility applies only to classified cage-forming waters. Non-water residue channels such as `SDS` and `NA` keep independent visibility and atom/bond styling, and toggling them does not clear CHILL+. Changing the water channel can require a classification refresh because it changes the analyzed water set.
  </Accordion>

  <Accordion title="Can I show H-bonds and CHILL+ together?">
    Yes. CHILL+ class colors, its O–O network, and the H-bond overlay are independent and can be shown together. The H-bond network refreshes when its cutoff or supported trajectory frame changes.
  </Accordion>
</AccordionGroup>

## Files and Sessions

<AccordionGroup>
  <Accordion title="Can Clavis open large trajectories?">
    Yes. Large `.gro` trajectories use a streaming worker so the browser can inspect frames without loading the entire trajectory into memory. Choose the **GROMACS** card in the upload guide for paired `.gro + .xtc/.trr` and `.tpr + .xtc/.trr` trajectories; they index frame byte ranges locally in a dedicated browser worker and decode selected XTC/TRR frame slices for dense native sessions. Large scenes temporarily use a capped instanced-sphere preview without bonds during loading, playback, or dense visualization commits, then return to full atoms and bonds when settled. Current-frame analysis can request the full selected frame independently. Use `.gro + .xtc/.trr` when you need exact residue labels from the text topology — it is also the reliable path when a `.tpr` binary is not supported by the browser decoder. Normal/large GRO, mapped LAMMPS, and native XTC/TRR sessions support selected TRACE/HTR/GRADE/F3F4 ranges.
  </Accordion>

  <Accordion title="Can Clavis open LAMMPS trajectories?">
    Partially. Choose the **LAMMPS** card in the upload guide, then select either a paired `.data + .lammpstrj/.dump/.lammpsdump` upload or a standalone dump with atom `type` rows. Clavis asks for unit style and atom-type roles, then can play or jump between mapped dump frames and run current-frame or sampled TRACE/HTR/GRADE/F3F4 analysis when the mapping yields water molecules. Dump-only water analysis fails closed unless mapped water atoms include `mol` grouping and form exactly 1 O + 2 H per molecule. Restricted triclinic dump cells use cell-aware WASM paths when the frame carries that metadata.
  </Accordion>

  <Accordion title="Will my scene survive refresh or clicking NEW/Changelog?">
    Normal-size scenes can recover from session-local browser storage, including layers, settings, analysis overlays, and camera view. Large streaming trajectories intentionally skip this recovery path.
  </Accordion>

  <Accordion title="Is my structure data stored on Clavis servers?">
    Structure workflows are browser-local for analysis and visualization. Session recovery may store normal-size scene text in your own browser session storage; clearing browser storage removes it.
  </Accordion>
</AccordionGroup>

## Account & Billing

<AccordionGroup>
  <Accordion title="How do I upgrade to Pro?">
    Click the account or upgrade entry point in the app. Checkout and subscription management are handled through Lemon Squeezy.
  </Accordion>

  <Accordion title="Can I cancel my subscription?">
    Yes. Use the account or billing portal. Access generally remains available until the end of the paid billing period.
  </Accordion>

  <Accordion title="Do unused free frames roll over?">
    No. Free usage quotas reset on the configured monthly cycle.
  </Accordion>
</AccordionGroup>

## Path Tracer and Export

<AccordionGroup>
  <Accordion title="How do I access path-traced rendering?">
    Path-traced rendering is available to Pro subscribers in the **RENDER** tab.
  </Accordion>

  <Accordion title="Can I choose a custom output size?">
    Yes. The RENDER tab supports custom width/height, aspect presets, Preview Mode, and centered render-frame composition. Standard PNG export and path-traced still export both use the Preview Mode render frame when it is active. The default 16:9 output is 1280 × 720 for faster first path-traced previews; choose the 1080p preset or custom dimensions for larger exports.
  </Accordion>

  <Accordion title="Can I export movies?">
    Yes. Pro video export supports frame ranges, step size, FPS, quality, loop count, and standard or path-traced render modes.
  </Accordion>

  <Accordion title="Why do frame ZIP and movie actions not appear?">
    They are omitted for a single-frame scene because there is no frame range to export. On a multi-frame scene, open the RENDER tab and check the Export Center; an unavailable action displays the trajectory, account, or render requirement that applies.
  </Accordion>

  <Accordion title="Does Clavis export a Blender scene or sync with the Blender extension?">
    The Pro Export Center can download the current displayed scene as a schema-v2 `.claviscage.zip`. The ClavisCage Blender extension imports its structure, available current-frame CHILL+/H-bond data, selected TRACE/HTR/GRADE cage analysis with provenance, and supported editable styles. This is an offline, single-frame handoff—not direct `.blend` generation, a trajectory container, or live synchronization.
  </Accordion>

  <Accordion title="What are the JSON files inside a Blender bundle?">
    Keep the downloaded `.claviscage.zip` intact and import the archive itself through **ClavisCage → Input → ClavisCage Bundle → Import Web Bundle**. `manifest.json` describes the bundle format, schema, originating app version, and warnings. `scene.json` carries the current structure, matching analysis, algorithm/frame/parameter cage provenance, and supported styles. They are extension payloads rather than separate Blender inputs; direct JSON editing is not a supported workflow because the extension validates the complete archive strictly. The extension accepts legacy v1 HTR bundles and current v2 algorithm-owned bundles. If the Input panel shows only Topology, Trajectory, and Guests, that installed extension does not yet include web-bundle import and must be updated first.
  </Accordion>

  <Accordion title="What happens if one frame fails during export?">
    Clavis stops the export rather than silently producing incomplete output or reusing stale TRACE/H-bond geometry. It reports the failed frame or stage, then restores the original frame and the overlay visibility state from before export. Hide HTR ring or occupied-guest overlays if the app reports that they cannot be refreshed safely for a multi-frame capture.
  </Accordion>

  <Accordion title="Why is my path-traced render noisy?">
    Increase sample count or enable denoising. Use lower dimensions and samples for previews, then increase quality for final export.
  </Accordion>
</AccordionGroup>

## Contact

For support, use the channels provided in the Clavis application or documentation.