Guest Occupancy

​

Overview

Guest occupancy analysis calculates how many cages are occupied by guest molecules versus the total number of detected cages. Clavis reports two occupancy fractions used in the clathrate hydrate literature:

• θ_S — occupancy of small cages (5¹²)
• θ_L — occupancy of large cages (5¹²6², 5¹²6⁴)

​

How It Works

After cage detection (TRACE algorithm), Clavis checks whether each detected cage contains a guest molecule. A guest is considered enclathrated if its position falls within the geometric bounds of a cage.

​

Cross-Layer Guest Detection

If you have loaded guest molecules as a separate layer (a .gro file containing only guest species), Clavis automatically collects those guests and combines them with any guests detected in the primary structure file. This allows you to analyze systems where water and guests are stored in separate files.

​

Usage

1. Load your .gro file containing water molecules.
2. Optionally load a guest .gro file as a separate layer.
3. Run TRACE Analysis from the Analysis tab.
4. The results panel will display θ_S, θ_L, and per-cage-type occupancy.

​

Visualization

When the analysis is complete, enable ENCLATHRATED GUESTS in the cage overlay panel to visualize guest molecules as spheres inside cage wireframes. Use the SIZE slider to scale the sphere radius. Only guests that are confirmed enclathrated (i.e., cage_idx is set) are shown. Free (un-enclathrated) guest molecules are not rendered.

​

Output

​

Trajectory Analysis

When running trajectory analysis, occupancy is computed per frame and plotted in the Occupancy chart. This allows you to track guest capture and release events across a simulation.

​

Notes

• Guest detection relies on the residue names in your .gro file. Non-water, non-ice residues are treated as guests.
• Cross-layer guests are identified by their position in the simulation box.
• Clavis uses != null comparison (loose equality) to handle Rust Option::None → JavaScript undefined serialization from WASM.