Skip to main content

​
Overview

Guest occupancy analysis calculates how many detected cages contain guest molecules. Clavis reports literature-style cage occupancy metrics and an aggregate Overall occupancy value:
  • θ_S — occupancy of small cages (5^12)
  • θ_L — occupancy of large cages such as 5^12·6^2 and 5^12·6^4
  • Overall occupancy — occupied cages divided by all detected cages in the current result
  • By cage type — per-type guest counts for detected cage signatures

​
How It Works

After TRACE, GRADE, or complete-cage HTR analysis, Clavis tests whether candidate guest molecules are enclosed by detected cages. A guest is considered occupied/enclathrated when it is assigned to a cage index. HTR incomplete cages remain visual-only for this calculation because they do not yet expose a reliable occupiable cage body. For multi-atom guest molecules, Clavis uses molecule-level guest information while preserving atom-level rendering for visualization. Single-atom guests use a focused halo marker.

​
Cross-Layer Guest Detection

If guests are loaded in a separate structure layer, Clavis collects non-water guest residues from visible layers and combines them with guests found in the primary structure file. This supports workflows where water and guests are exported separately.

​
Usage

  1. Load a supported structure file containing cage-forming water molecules.
  2. Optionally load a guest structure file as a separate layer.
  3. Run TRACE, GRADE, or HTR analysis. HTR occupancy is calculated from complete HTR cages only.
  4. Review θ_S, θ_L, Overall occupancy, filled/empty cage counts, and the per-cage-type breakdown.
  5. Enable HIGHLIGHT OCCUPIED GUESTS to inspect assigned guests in the scene.

​
Occupied Guest Visualization

Occupied guest controls are independent from cage wireframe visibility. You can hide cages and still keep guest highlights visible. Available controls include:
  • Highlight toggle — opt in before occupied guests are emphasized
  • Size — scales guest atom halos and guest bonds together, including path-traced exports
  • Cage type filter — show guests inside selected cage signatures
  • Structure filter — filter by the current/global GRADE structure bucket when available
  • Single vs. multi-atom rendering — single-atom guests use halo markers; multi-atom guests use atom-level neon ball-and-stick emphasis
When path-traced rendering is enabled, occupied guest highlights are rebuilt with the same cyan neon palette and guest-bond scaling used in the live scene preview so final PNG exports match the selected visualization settings more closely.

​
Trajectory Analysis

For trajectories, occupancy is computed per frame and plotted as Overall occupancy over time alongside small/large cage occupancy where applicable. Use trajectory results to track guest capture, release, and cage population changes over simulation time.

​
Notes

  • Guest detection depends on residue names. Hydrate-water aliases such as HSL are treated as water; metal/slab and geologic residues are categorized as material structures; remaining non-water residues are treated as candidate guests.
  • Periodic boundary handling uses minimum-image conventions where needed for robust visualization.
  • If no guest residues are present, occupancy metrics can still show empty cage counts but no occupied guests.
  • Switching between TRACE, HTR, and GRADE restores each algorithm’s own latest cage, H-bond, guest, and occupancy snapshot instead of reusing the previous algorithm’s overlay state.