Tal — Crystallographic Application

1. Introduction

Tal is a sophisticated desktop application for crystallographic visualization and analysis. Built with .NET 8 and MonoGame, it offers a high-performance 3D rendering environment for exploring molecular structures, analyzing intermolecular interactions, and performing advanced computational tasks like cavity detection and Hirshfeld surface analysis.

The application uses a flexible docking interface, allowing you to customize the layout of various tool windows around the central 3D viewport.

Key Features:

• Loading and visualization of common crystallographic file formats (CIF, RES, XYZ, PDB, MOL, MOL2, GJF).
• Multiple display styles: CPK, ball-and-stick, ellipsoids (ORTEP), and polyhedrals.
• Advanced coloring modes, including by element, symmetry, molecule, charge, and hydrophobicity.
• Comprehensive analysis tools for cavities, Hirshfeld surfaces, short contacts, and hydrogen bonds.
• Powerful overlay feature to superimpose multiple structures.
• Tools for creating publication-quality images (screenshots, POV-Ray export).
• Powder X-ray diffraction simulation with 2D fingerprint-style plotting.
• Crystal plane construction (hkl and mean plane via least-squares).

2. File Management

Operations related to opening, saving, and exporting data are found in the File menu.

2.1. Open...

Opens a structure file. Tal supports a wide variety of formats, including but not limited to:

• CIF (*.cif)
• SHELX (*.res, *.ins)
• XYZ (*.xyz)
• PDB (*.pdb, *.ent)
• MOL/SDF (*.mol, *.sdf, *.sd)
• MOL2 (*.mol2, *.ml2)
• Gaussian (*.gjf, *.com, *.gau)

If a file contains multiple structures (e.g., a multi-record CIF), Tal will prompt you to open all of them, only the first one, or none. All loaded structures are added to the Structure List.

2.2. Open Recent

Provides a list of recently opened files for quick access. The list is maintained by RecentFilesManager (singleton) and persisted to %LocalAppData%\Tal\RecentFiles.json.

• Maximum 10 entries (MaxEntries).
• Entries are deduplicated case-insensitively; adding an existing path moves it to the top.
• On load, missing files are silently filtered out.
• Paths that cannot be resolved (e.g. broken UNC) are skipped on load.

2.3. Save As...

Saves the currently selected structure from the Structure List to a new file. The save operation is dispatched by StructureWriter.Save() based on the target extension.

Supported Write Formats

CRYSTAL17 export and standard setting

CRYSTAL17 requires the standard setting of the space group (e.g. P2₁/c, not P2₁/n). Before writing a .d12 file, Tal calls SpaceGroupTransformer.GetTransformToStandard() and, if the structure is non-standard, shows a dialog:

• YES — transform a copy of the structure to the standard setting (the original in StructureStorage is not modified) and save.
• NO — save without transformation. A warning is added to the exported file's comment.
• CANCEL — abort the export.

2.4. Save Screenshot...

Opens the ScreenshotDialog (a fixed-dialog WinForms window) which captures the current 3D viewport and saves it as a high-quality image. The dialog computes a supersampled resolution and reads the final backbuffer at that multiplier.

ScreenshotDialog controls

Final resolution rule: ResultW = round(baseWidth × Scale), then clamped to MAX_DIMENSION = 8192 px per axis. Base dimensions are the current backbuffer dimensions of the active MonoGame document.

Static helper: ScreenshotDialog.ShowSettings(owner, baseWidth, baseHeight, out scale, out fullFrame, out supersample).

2.5. Export to POV-Ray...

Exports the entire scene (atoms, bonds, unit cell, visible cavities, polyhedra, planes) to a POV-Ray scene file (*.pov). Photorealistic rendering can then be done with the external POV-Ray engine. The generator uses the current camera, lighting, background, and display flags.

See section 13 for a detailed description of PovRayGenerator.

2.6. Close / Exit

• Close: Closes the currently active document (3D view window).
• Exit: Shuts down the entire application. The layout and settings are saved automatically on exit.

3. Selection & Manipulation

The Selection menu and the mouse provide several ways to interact with atoms and molecules.

3.1. Mouse Interaction Modes

The main toolbar allows you to switch between different interaction modes:

• Rotate Mode (default): Left-click and drag to rotate the structure. Right-click and drag to zoom. Middle-click and drag to pan.
• Pick Atoms Mode: Click on an atom to select or deselect it. This is used for creating measurements, defining planes, or applying individual colors.
• Lasso Mode: Click and drag to draw a rectangle. All atoms within the rectangle are selected.
• Measure Mode: Click on atoms to perform measurements (e.g., distance, angle, torsion). The specific measurement type is chosen in the toolbar.
• Move Labels Mode: Allows you to click and drag atom labels to reposition them manually.

3.2. Selection Menu

• Select Atoms: Selects all visible atoms in the current structure.
• Select Molecules: (If applicable) Selects all atoms belonging to a single molecule in a crystal packing view.
• Select Unit Cell: Selects the unit cell frame.
• Invert Selection: Selects all unselected atoms and deselects all currently selected atoms.
• Clear Selection: Deselects all atoms.

3.3. Programmatic selection helpers

The class MeanPlaneCalculator (namespace Tal.Core.PowderDiffraction) exposes static helpers used by the plane editor and by external tools:

• CollectSelectedAtomIndices(Molecule) — returns a List<int> of indices of atoms whose selected flag is true.
• CountSelectedAtoms(Molecule) — returns the number of selected atoms.

These are used by the Crystal Planes tool when building mean planes.

4. Visual Display

The Display menu controls all aspects of the visual representation of the structure.

4.1. Style

The main toolbar contains a dropdown to select the global display style for all atoms. This can be overridden for individual atoms through the Atom Display Settings window.

• CPK: Atoms are represented as spheres with radii proportional to their van der Waals radii.
• Balls & Sticks: Atoms are represented as spheres connected by cylindrical sticks representing bonds.
• Sticks (Wireframe): Only bonds are shown as sticks. Atoms are not drawn.
• Ellipsoids (ORTEP): Atoms with anisotropic displacement parameters (ADPs) are drawn as thermal ellipsoids. Isotropic atoms are drawn as spheres.
• Polyhedrals: Coordination polyhedra are drawn for specified central atoms. This style is typically configured in a separate tool window.

4.2. Colour atom

Opens the 🎨 Atom Color window, which allows you to choose a global coloring mode for the entire structure. This is a powerful tool for visual analysis.

Available color modes include:

• Atomic Number (Default): Colors atoms by element (e.g., Carbon = grey, Oxygen = red, Nitrogen = blue).
• Symmetry Equivalent: Assigns a unique color to each symmetry-equivalent position in the unit cell. Useful for identifying pseudo-symmetry or disorders.
• Molecule Number: Assigns a unique color to each distinct molecule detected in the crystal packing.
• Symmetry + Molecule: A combined mode that provides a unique color for each combination of molecule and symmetry operation.
• Individual Color (Selected Atoms): Allows you to pick a specific color and apply it to a pre-selected group of atoms. The selection is cleared after the color is applied.
• Charge: Maps the atomic charge (from the CIF file) to a color scale (blue for negative, red for positive, white for neutral).
• Hydrophobicity: Maps the atomic hydrophobicity value to a color scale. This is useful for studying protein-protein or protein-ligand interactions.

4.3. Labels

Opens the 🏷️ Labels Settings window. Here you can control:

• Whether to show or hide all labels.
• Font properties (name, size, style, color).
• Shadow effect for labels.
• Default X and Y offset for all labels.
• What property to display alongside the atom name (e.g., charge, hydrophobicity).

Labels can also be individually repositioned by enabling Move Labels Mode from the toolbar.

4.4. Background...

Opens the 🎨 Background Colors window. You can choose a solid color or a two-color gradient for the 3D viewport background. Several presets are available, or you can pick custom colors.

4.5. Lighting...

Opens the ⚡ Lighting window. This provides full control over the scene's illumination, including:

• Primary and Secondary Lights: Enable/disable and set the direction, diffuse intensity, ambient intensity, and specular properties (color, power, intensity) for two independent directional lights.
• Per-Pixel Lighting: Toggle this option for higher quality lighting at a potential performance cost. If unchecked, per-vertex lighting is used.

4.6. Atom Display Settings

Opens the 🎨 Atom Display Settings window. This window provides fine-grained control over the size of spheres and sticks, and the appearance of ellipsoids and cell lines.

• Ball Sizes: Adjust the radius for non-metal, metal, and hydrogen atoms.
• Stick Sizes: Adjust the radius and length factor for bonds.
• Unit Cell Lines: Adjust the thickness and length factor for the unit cell edges.
• Ellipsoid Parameters:
  • Probability (%): Sets the probability level for the thermal ellipsoid (e.g., 50% for IUCr standard). This is the single source of truth and is internally converted to a scale factor using a pre-computed table and interpolation based on the χ² distribution.
  • Disk Thickness: Controls the thickness of the elliptical "disks" drawn on the principal planes of the ellipsoid.
  • Base Radius: Adjusts the base size of the ellipsoids.
  • Show Hydrogen as Sphere: If an atom is hydrogen, it is drawn as a simple sphere instead of an ellipsoid, regardless of its ADP data.

4.7. Atom Colors (global)...

Opens the 🎨 Atom Colors window. This is a different tool from the "Colour atom" window. It allows you to edit the global, persistent color palette for each element, indexed by atomic number.

• Click a color cell to open a color picker and change the default color for that element across the entire application.
• Changes are saved to the application's settings (JSON file) and will persist between sessions.
• Rows with a modified color have a cream-colored background.
• Reset Selected and Reset All buttons allow you to revert to the original default colors.

4.8. Short Contacts...

Opens the 📏 Define Short Contacts window. This tool finds all non-bonded contacts shorter than a user-defined threshold.

• Fixed distance: Find contacts within a fixed distance (e.g., 3.5 Å).
• Sum of vdW radii: Find contacts closer than the sum of the van der Waals radii of the two atoms.
• Intermolecular / Intramolecular: Toggle whether to find contacts between different molecules or within the same molecule.

The detected contacts are drawn as red dashed lines in the 3D view.

4.9. Scene Quality...

Opens the 🎚️ Scene Quality window, which controls rendering fidelity and performance.

• SSAA (Supersampling): Renders the scene at a multiple of the screen resolution (1x to 4x) for smoother edges. This is the primary anti-aliasing method.
• Progressive AA: When the camera is static, accumulates multiple frames to further refine the image, producing very smooth results. Can be set to 2, 4, 8, or 16 accumulated frames.
• MSAA (Backbuffer): Hardware multi-sampling. Requires an application restart to take effect.
• Anisotropy: Controls the level of anisotropic filtering for textures.

5. Calculations

The Calculate menu provides tools for geometric analysis of the structure.

5.1. Centroids...

Calculates the centroid of the currently selected atoms. The result is displayed in the status bar. Useful for finding the center of a ring or a group of atoms.

5.2. Planes...

Opens the Planes window. This tool allows you to define and manage crystallographic planes.

• You can define a plane by selecting three or more atoms in the 3D view and clicking "Add Plane from selected atoms".
• You can also define a plane by its Miller indices (h, k, l) and a distance from the origin.
• Planes can be toggled for visibility and their color and transparency can be changed.
• Once defined, you can use the "Measure Distances" tool (with a special mode selected) to measure the distance from a selected atom to a plane.

See section 9 for a detailed description of the plane tool.

5.3. Packing...

Opens the 📦 Packing window. This is the primary tool for generating and exploring crystal packing diagrams. It allows you to apply symmetry operations and translational shifts to create a supercell.

• Symmetry Mode: Choose to display the asymmetric unit, the full unit cell (generated by symmetry), or a specific block of the crystal.
• Repeat Unit (X, Y, Z): Defines the size of the supercell to generate (e.g., 2x2x2).
• Shift Sliders: Fine-tune the origin of the displayed block by shifting along fractional cell axes.

5.4. Contacts...

Placeholder for a future tool for general contact analysis.

5.5. Molecular Shell...

Placeholder for a future tool for calculating and displaying a molecular surface or shell.

5.6. Graph Sets...

Placeholder for a future tool for topological analysis of the hydrogen bond network (graph set analysis).

5.7. Powder Pattern...

Opens the PowderDiffractionWindow. See section 8 for a full description.

5.8. Transform space group...

This powerful tool allows for the transformation of a structure from one setting of a space group to an equivalent setting (e.g., from P2₁/c to P2₁/n, or from a standard to a non-standard setting).

• Tal detects the current space group number and finds all available alternate settings.
• A dialog allows you to select the target setting.
• The transformation modifies the cell parameters, atomic coordinates, ADP tensors, and symmetry operations in-place, using a least-squares refinement to ensure the transformed structure is chemically sensible.

See section 13 for details on SpaceGroupTransformer.

6. Cavity Analysis

Tal includes a powerful and robust engine for the detection and analysis of voids and cavities in crystal structures. This is a key feature for studying porosity, host-guest chemistry, and gas storage potential.

6.1. Cavity Detection & Display Window

This is the main control panel for all cavity-related operations, opened from the Calculate menu.

Detection Parameters

• Enable Cavity Display: Master switch to turn the visualization of cavities on or off.
• Resolution (Å): The voxel size for the underlying grid used in detection. Smaller values give a more accurate result but are computationally more expensive. A value between 0.10 and 0.20 Å is typically a good compromise.
• VdW Multiplier: A scaling factor applied to the van der Waals radii of the atoms. The cavity is defined as the space available outside these scaled atoms. A value near 1.0-1.2 is common.
• Transparency: Adjusts the transparency of the rendered cavity mesh.
• Smoothing: Applies a series of Gaussian blur and Laplacian smoothing iterations to the density grid before the mesh is generated. This results in a smoother, more visually pleasing isosurface. A higher number means more smoothing.
• Use Anisotropic VdW (ellipsoids): If checked, the detector uses the full thermal ellipsoid of each atom instead of a simple sphere, providing a more accurate description of the accessible space.

Actions

• Detect Cavities: Runs the main detection algorithm on the active structure. This process uses a Signed Distance Function (SDF) and a flood-fill algorithm to identify regions of empty space that are not connected to the outside of the crystal.
• Clear Cavities: Removes all detected cavities from the current document, freeing memory and hiding the visualization.
• Export Report: Saves a text file containing a detailed report of the detected cavities, including their volume, surface area, sphericity, and center coordinates.

Display Modes

Once cavities have been detected, you can choose how to visualize them:

• Hidden: Cavities are not shown.
• Normal Cavity: Renders the cavities as semi-transparent isosurfaces (meshes).
• Property Map: Colors the cavity surface based on a molecular property (charge, hydrophobicity, etc.) of the nearby atoms. This is an extremely powerful tool for understanding the chemical environment inside the cavities.
• Topology Map: Colors the cavity surface based on topological features of the SDF (e.g., distance to the surface).
• Channel Paths: Analyzes the cavity network to find and visualize interconnected 1D channels that percolate through the crystal.
• Sphere Fits: Finds the largest spheres that can fit inside each cavity and renders them, giving a quick visual estimate of the cavity's internal dimensions.

6.2. The Cavity Detection Algorithm

Tal's cavity detector is a sophisticated implementation designed for speed and accuracy, even for large and complex structures.

1. Signed Distance Function (SDF) Calculation: The algorithm begins by creating a high-resolution 3D grid (the "voxel grid") over the unit cell. For each point on this grid, it calculates the shortest distance to the surface of any atom. This value is negative inside an atom and positive outside. This creates a smooth field that defines the shape of the atoms.
2. Handling of Anisotropic Displacement (ADPs): When Use Anisotropic VdW is enabled, the SDF is not calculated as a simple distance to a sphere, but as a distance to a more complex ellipsoid surface. The eigen-decomposition of the ADP tensor (U-matrix) is used to determine the principal axes and radii of the ellipsoid for each atom, providing a physically more meaningful representation.
3. SDF Caching and Correction: For performance, Tal can compute a base SDF for a standard van der Waals radius. If you then change the VdW multiplier, the algorithm doesn't recompute the entire SDF. Instead, it uses a mathematically exact correction: SDF_new = SDF_base - delta, where delta is the change in the radius. This is because the SDF represents a distance, so scaling the atomic radii simply shifts the entire field by a constant. This trick makes recalculating with a different VdW scale extremely fast.
4. Periodicity and Flood-Fill: The algorithm handles periodic boundary conditions by extending the grid into a margin around the unit cell. A flood-fill algorithm starts from the outermost boundary of this extended grid (the "exterior") and fills all connected empty voxels. Any empty voxels not reached by this fill are considered to be part of a "buried" cavity.
5. Marching Cubes Mesh Generation: Once the cavities are identified, the Marching Cubes algorithm is applied to the SDF grid to generate a smooth triangle mesh for the surface of each cavity. This mesh can then be rendered as a semi-transparent isosurface. The quality of the mesh can be controlled via the "Smoothing" parameter.

7. Hirshfeld Surface Analysis

This advanced tool, opened from the Advanced menu, is essential for understanding and quantifying intermolecular interactions in molecular crystals. It is based on the Hirshfeld partitioning scheme, which defines a molecule's space in a crystal based on the electron density.

7.1. The Workflow

1. Ensure a full molecule is present in the scene (e.g., by setting Packing to "Symmetry" mode).
2. Open the Hirshfeld Surface Analysis window from the Advanced menu.
3. In the window, select a molecule from the dropdown list (if multiple are present).
4. Choose the type of surface you want to generate (Hirshfeld Surface, Shape Index, Curvature, etc.).
5. Click the "Generate" button. The application will compute the property for every point on the surface and generate a color-mapped mesh.
6. The resulting surface is displayed in the 3D view, colored according to the selected property. The corresponding 2D fingerprint plot is also generated and displayed in the tool window.

7.2. Hirshfeld Surface Properties

• Hirshfeld Surface (di, de, dnorm): A surface that represents the boundary of the molecule's space in the crystal. It is defined by the w(r) = 0.5 isosurface of the Hirshfeld weight function, which is the ratio of the electron density of a promolecule (the selected molecule) to the total electron density of the crystal (procrystal). The surface itself can be colored by various properties.
  • di: The distance from the surface point to the nearest nucleus *inside* the surface.
  • de: The distance from the surface point to the nearest nucleus *outside* the surface.
  • dnorm: A normalized contact distance, calculated as dnorm = (di - rᵢᵛᵈʷ) / rᵢᵛᵈʷ + (de - reᵛᵈʷ) / reᵛᵈʷ. This is a powerful property that highlights close intermolecular contacts. Areas with dnorm < 0 (typically colored red) are regions of strong interaction (e.g., hydrogen bonds, close packing). Blue areas represent longer, weaker contacts.
• Shape Index (S): A measure of the local curvature of the surface. It is defined as S = (2/π) * atan((κ₁ + κ₂) / (κ₁ - κ₂)), where κ₁ and κ₂ are the principal curvatures. It is an excellent tool for identifying complementary shapes: convex "bumps" (like C-H groups) have S > 0 (colored blue), while concave "hollows" (like O or N lone pairs) have S < 0 (colored red). Complementary bumps and hollows indicate a favorable interaction.
• Curvedness (C): A measure of the "flatness" of the surface, defined as C = (2/π) * ln(sqrt((κ₁² + κ₂²)/2)). Flat areas like π-stacked rings have low curvature, while sharp features like lone pairs have high curvature. It is useful for identifying planar stacking interactions.
• Distance from a Plane: Colors the surface based on its distance from a user-defined plane.

7.3. 2D Fingerprint Plots

This is the cornerstone of Hirshfeld analysis. The fingerprint plot is a 2D histogram of the di versus de values for every point on the Hirshfeld surface.

• Each point on the plot represents a point on the 3D surface.
• Areas with a high density of points (shown as "hot" colors) represent a large fraction of the total surface area involved in those specific types of contacts.
• The plot can be "decomposed" or filtered by the chemical element of the atom outside the surface. This allows you to see the contribution of specific interactions, like O···H, C···H, or H···H contacts, to the overall crystal packing.
• The shape and position of the features on the plot provide a detailed signature of the intermolecular interaction network.

7.4. Hirshfeld Window (HirshfeldDocument)

The main 3D view for the Hirshfeld analysis is the HirshfeldDocument — a DockContent that hosts a MonoGame viewport and a right-side control panel. It is created from the Hirshfeld Surface Analysis menu item and reused on subsequent invocations.

Layout

• Left: 3D viewport (_panel, fill). Renders the molecule (or isolated target), the Hirshfeld isosurface, optional wireframe, axes and unit cell. Background color follows Flags.Instance.color1.
• Right: control panel (_controlsHost, 300 px wide, docked Right). A FlowLayoutPanel with all controls, sorted top-down.

Control panel — Target selection

Control panel — Detection parameters

Control panel — Property & display

Control panel — Actions

Progress bar & status label

• _progressBar: ProgressBarStyle.Continuous, 0 – 100. Updated through a thread-safe BeginInvoke adapter.
• _lblStatus: 4-line status text (monospace). Shows "Ready", "Generating…", final vertex/triangle counts, and the current smoothing/blur state.

GenerateAsync — nine-step algorithm

1. KROK 1/9 — Building HirshfeldScene. Calls HirshfeldScene.Build(targetMolId, neighborCutoff). If the target molecule is not found, the operation aborts with a friendly message.
2. KROK 2/9 — Preparing atom entries. Wraps each SceneAtom into an AtomGaussParams via HirshfeldParameters.BuildFromAtomSimple. Isotropic (σ) or anisotropic (ADP eigen-decomposition) parameters are selected based on the Density model dropdown.
3. KROK 3/9 — Building density grid. A cubic grid is created around the target center. Its resolution is n = ceil(2·(r_max + margin) / voxelSize). Fails gracefully if n³ exceeds Flags.MAX_VOXELS.
4. KROK 4/9 — Filling density grid. Parallel per-thread accumulation of Gaussian contributions. Uses the fast path from v2.9: sphere bounds for isotropic atoms, bounding box for anisotropic ones. Hot loop uses HirshfeldExpLut.FastExpNeg.
5. KROK 5/9 — Computing w(r). In-place reduction: W = RhoPro / (RhoPro + RhoProm_Outer) with a strict fallback of 0 for empty voxels. Diagnostic distribution is written to the debug log.
6. KROK 6/9 — Optional blur. BlurDensityField(sigma, iterations) with separable 1-D convolution passes along X, Y, Z. A second pass uses sigma * 1.8 when BlurIterations ≥ 2.
7. KROK 7/9 — Marching Cubes. Calls HirshfeldMarchingCubes.Extract, which delegates to HirshfeldMarchingCubesGenerator.Extract. It reads the flat W array, subtracts isoLevel inline, and produces a triangle mesh. Duplicate vertices are merged with a 27-neighbour hash grid.
8. KROK 8/9 — Metadata. Populates _surface.TargetMoleculeId, TargetAtomCount, OuterAtomCount, Center, UsedAnisotropic, and calls ComputeBoundingRadius().
9. KROK 9/9 — Per-vertex properties. HirshfeldProperties.Compute populates DE, DI, DNorm, and stores the nearest-atom indices and names (used later by the fingerprint plot). The original values are also cloned into DEOriginal, DIOriginal, DNormOriginal so that color smoothing is fully deterministic.

After step 9, the document calls HirshfeldColorSmoothing.Apply(_surface, _colorSmoothingLevel), rebuilds all vertex buffers, resets the camera and raises Flags.Instance.VisualRevision + MarkDirty(). If the fingerprint window is already open, its analysis is rebuilt and pushed.

Mouse & keyboard

• Left drag — rotate the camera (Camera.MouseMove). The scene sorting algorithm is invalidated and the triangles are re-sorted next frame.
• Mouse wheel — zoom the whole scene (multiplicative 1.05 / 0.95, clamped 0.2 – 8.0). This affects the _zoomFactor (scene scale), not the camera zoom.
• Ctrl+S — triggers SavePng().

MoleculeShift compensation

The surface vertices are stored in "raw" Cartesian coordinates (no −MoleculeShift). At render time the document subtracts the current MoleculeShift from each vertex, so the surface always aligns with the atoms rendered by the main viewport. When the user changes the presentation mode (and hence the shift), the buffers are rebuilt automatically — the change is detected via the _lastMoleculeShift sentinel field.

7.5. Hirshfeld Pipeline — Computational Classes

The Hirshfeld surface is produced by a self-contained pipeline that does not depend on the main document's presentation state. It is built on top of the same Molecule data used by the rest of Tal, but with its own cell reconstruction step.

HirshfeldScene

Central coordinator of the pipeline. Given a Molecule and a target molecule ID, it reconstructs a compact unit cell, runs the molecule finder, marks the host atoms and collects all outer (guest) atoms within a neighbour cutoff.

• Inputs: target Molecule, targetMoleculeId, cutoff (Å). Default cutoff = HirshfeldParameters.CUT_OFF = 10 Å.
• Public properties: TargetAtoms, OuterAtoms, Fragments, TargetCenter, TargetBBoxMin/Max, TargetRadius, TargetMoleculeId, LastCutoff, LastNeighborCount.
• SceneAtom struct: stores SymmetryAtomIndex, CellShiftX/Y/Z, FracPosition, CartPosition, AtomicNumber, IsTarget, IsAnisotropic, Un (ADP matrix), Occupancy, Name, MoleculeId, SourceAsymIndex.

HirshfeldUnitCell

Independent representation of the unit cell, built exclusively from Molecule.AsymetricPart and Molecule.SymmetryOperations. It deliberately does not read Molecule.SymetryEquivalents or Molecule.atom[], because those are mutated by the presentation-mode code.

1. For each atom of the asymmetric part and each symmetry operation, generate a raw fractional position.
2. Deduplicate against the growing list with a fractional tolerance DEDUP_TOL_FRAC = 0.005.
3. For each symmetry operation ops[k], k ≠ 0, find the anchor atom (first non-hydrogen of ops[0]) and its counterpart in ops[k]. Compute a single integer translation from the anchor to its counterpart, then apply that same translation to all atoms of ops[k]. This is essential: if you translated each atom independently you would tear molecules apart.
4. Deduplicate again to remove the post-translation collisions.

The result is a cell where every molecule generated by symmetry is geometrically compact — molecules may stick out of the cell but never straddle two distant locations.

HirshfeldDetector

Detects the surface and returns a HirshfeldSurface. Its main entry point is GenerateAsync, which drives the nine-step algorithm described above. Important public properties:

The detector writes a lot of timestamped diagnostic output ([t=…ms]) to the debug stream, including per-thread parallel configuration, grid dimension, memory estimate and the distribution of w(r) before and after blur.

HirshfeldGrid

Wraps a VoxelScanner.VoxelGrid and holds flat density arrays:

float[] W;                // w(r) = rho_pro / (rho_pro + rho_outer)
float[] RhoPro;           // promolecule (target)
float[] RhoProm_Outer;    // surrounding atoms

Indexing is idx = i + Nx·(j + Ny·k) — the deepest loop index k gives sequential memory access. ComputeRelativeDensity is parallelised and iterates linearly, with the historical fallback of 0 for empty voxels (an earlier version used 0.5 which produced spurious triangles).

HirshfeldParameters & HirshfeldAtomicRadii

HirshfeldParameters.BuildFromAtomSimple converts an atom (position, atomic number, ADP matrix) into an AtomGaussParams:

• Isotropic: ρ(r) = Z_eff / (√(2π)σ)³ · exp(−|r−r₀|² / (2σ²)). The per-element σ comes from HirshfeldAtomicRadii.GetSigma(Z) (0.35 Å for H up to ~0.72 Å for Fr) multiplied by the user's Sigma multiplier.
• Anisotropic: The ADP matrix Un is row-normalized to get the three eigenvectors; the row lengths before normalization are the principal half-axes. Each half-axis is combined with the electronic σ as a_k = sqrt(λ_k² + σ_e²), giving an ellipsoid whose orientation follows the thermal motion.
• Cutoff radius: CUT_OFF × max(σ or a_k) with CUT_OFF = 10.

HirshfeldExpLut

Hot loop replacement for MathF.Exp(-x). A static LUT of 4096 entries over x ∈ [0, 25] with linear interpolation. Maximum relative error around 1e-4, i.e. invisible in the final rendering. Used by every Evaluate and by the fill loop inside HirshfeldDetector.

HirshfeldMarchingCubes & HirshfeldMarchingCubesGenerator

A dedicated copy of Tal's standard Marching Cubes generator, adapted for flat density arrays and Hirshfeld iso conventions. It never modifies the input array; instead the iso offset is subtracted inline. Duplicate vertices are merged with a 27-neighbour spatial hash with tolerance 0.0001.

HirshfeldProperties

For each mesh vertex, computes:

d_e    = min distance to any outer atom
d_i    = min distance to any target atom
d_norm = (d_e − r_vdW(outer)) / r_vdW(outer)
       + (d_i − r_vdW(inner)) / r_vdW(inner)

The d_norm value is clamped to [−1.5, +1.5] for display purposes. The names of the nearest inner and outer atoms are stored so the fingerprint plot can label contact types.

HirshfeldColorSmoothing

A color-only smoothing pass that never changes geometry. It re-runs over the current mesh vertices and:

1. Restores DNorm/DE/DI from the *Original arrays (idempotent, independent of the previous smoothing level).
2. Builds a spatial hash (0.20–0.80 Å radius depending on the level) and accumulates the values with 1/d² weights.
3. Applies 1–3 Jacobi-like iterations per level.

HirshfeldMeshRelaxation

An optional pre-color smoothing step that moves vertices tangentially along the mesh and slightly along their normals to remove the "staircase" artefacts of Marching Cubes without losing the physical shape. It uses a Laplacian average of neighbours, then decomposes the displacement into a tangential and a normal component. The tangential part fixes the staircase, the normal part reduces tiny spikes. The maximum displacement is clamped to 5% of the grid unit to avoid overshooting.

HirshfeldSmoothing

A geometry-only Taubin (λ | μ) smoothing applied to the mesh itself. Unlike a plain Laplacian, the negative μ step compensates the shrinkage, so the surface volume is approximately preserved. The original vertex positions and the adjacency list are cached per HirshfeldSurface, making the slider fully deterministic: level 0 always returns exactly the original mesh.

HirshfeldTargetSelector

Simple helper that lists all molecules in a Molecule by their IndividualMoleculeInCell ID. Used by the _cmbMolecule dropdown and by UseCurrentSelection().

7.6. Fingerprint 2D Window (HirshfeldFingerprintWindow)

A separate DockContent that renders a 2D heat map of the d_e × d_i distribution. Each bin corresponds to a small angular sector of the surface; the number of vertices in a bin is mapped to a log-scaled color ramp.

Bin construction & re-bucketing

• Default range [0.0 Å, 3.4 Å], default bin size 0.005 Å. Both can be changed live from the side panel.
• RebuildHeatmapFromRaw() recomputes a full histogram and a per-vertex (binDe, binDi) table. Vertices outside the range are tagged (−1, −1).
• The new per-vertex bins are sent back to the HirshfeldDocument via the OnVertexBinsUpdated callback, so the 3D highlighting stays in sync even after re-bucketing.
• Range and bin are clamped to safe limits: binsInRange ≤ MAX_TOTAL_CELLS = 8192 and texture bytes ≤ 512 MiB.

Rendering

• Background: Flags.Instance.color1 (same as the 3D viewport).
• Heat map: single Texture2D of size texSize × texSize, drawn with SamplerState.PointClamp (crisp bins).
• Color ramp: 4-segment palette white → cyan → blue → magenta/red, driven by log(1 + count) / log(1 + maxCount) and a intensity^0.6 compression. Minimum visible intensity is 0.15 so isolated bins are still visible.
• Optional overlays: major grid (10°/step), minor grid (5°/step), diagonal d_e = d_i line, axes and (hkl)-style labels for 2θ (hidden since this is a fingerprint, but the labels d_e (Å) / d_i (Å) are drawn).

Mouse interaction

Side panel controls

Highlight sync

When a bin is selected the window calls OnRegionClicked(binDe, binDi). The HirshfeldDocument stores _highlightedBin and rebuilds the vertex buffer. Every vertex whose (binDe, binDi) matches is colored bright yellow (255, 255, 0, alpha). When the user changes the bin size or the range, the new bins are pushed back through OnVertexBinsUpdated so the highlight remains correct.

7.7. Surface Data Model and Diagnostics

HirshfeldSurface

The data container for a computed surface. All vertex-based arrays share the same length.

HirshfeldAnalysisResults

A compact result set that is passed to the fingerprint window. It contains:

• FingerprintHistogram — Dictionary<(int binDe, int binDi), int>.
• FingerprintBinSize, FingerprintRangeMin, FingerprintRangeMax.
• ContactTypes — a string[] of length VertexCount with the type of each contact (e.g. "C···H").
• ContactTypeCounts — a dictionary built by ComputeContactTypeCounts().
• VertexBins — a per-vertex (binDe, binDi) table (v1.3).

HirshfeldAtomDistanceDiagnostics

A diagnostic object built after each generation. It contains:

• Target and outer atom count, min/max/median/p95/p99 of distances from the target center.
• Grid metadata: TargetCenter, RTarget, RGrid, Margin, VoxelSize, GridResX/Y/Z, TotalAtoms.
• A histogram (bin size 0.5 Å) of outer atom distances.
• A cutoff analysis table showing, for several R_target + delta thresholds (2–8 Å), how many atoms would be rejected.

The diagnostic is shown in the DebugWindow via the Show Diagnostics in Debug… button. The formatting is handled by HirshfeldDiagnosticsFormatter, which builds a list of (text, System.Drawing.Color) lines: header (cyan), grid info (white), target stats (light blue), outer stats (light green), histogram (colored bars), cutoff analysis and interpretation hints.

Export formats

• PLY — ASCII, one line per vertex (x y z nx ny nz r g b), then a face list. Compatible with MeshLab, Blender, CloudCompare.
• PNG — a high-resolution screenshot rendered with SSAA = 2. The label/camera matrices are identical to those used by the on-screen view.

8. Powder Diffraction

The Powder Diffraction window simulates the theoretical powder X-ray diffraction pattern for the loaded crystal structure. It is opened from Calculate → Powder Pattern....

The underlying engine (PowderDiffractionEngine) enumerates allowed hkl reflections in the 2θ range, computes the structure factor F(hkl) from the full unit cell, applies Lorentz–polarization and Debye–Waller corrections, groups symmetry-equivalent reflections, and renders the resulting profile in a WinForms plot.

8.1. Window Layout

The window is a DockContent composed of a large plot panel (panelPlot, a BufferedPanel) and a bottom control strip (panelControls) divided into group boxes.

8.2. Controls and Parameters

Range 2θ (groupBoxRange)

Peak parameters (groupBoxPeak)

Debye-Waller (groupBoxDebye)

Radiation source (groupBoxSource)

Available sources (from XRaySource enum):

Display options (groupBoxDisplay)

Info and actions (groupBoxHover, buttons)

8.3. Mouse Interaction

• Wheel: Zooms the 2θ range about the cursor position (factor 0.8 in, 1.25 out).
• Left drag: Rubber-band zoom. The selected pixel range is converted into a new 2θ range.
• Double-click: Resets the range to 0–90°.
• Hover: Updates the readout labels. The "closest peak" tolerance is 2% of the current 2θ span.

8.4. Algorithm and Formulas

1. d-spacing: Computed from the metric tensor of the triclinic cell using the standard reciprocal-lattice formula.
2. Angle: 2θ = 2 · asin(λ / (2d)), rejected if sinθ > 1.
3. Centering prefilter: Determined from the first letter of the actual Hermann–Mauguin symbol (P/A/B/C/F/I/R), not from the space-group number. This is only a fast performance filter — systematic absences from screw axes and glide planes are handled naturally by F(hkl).
4. Structure factor: F(hkl) = Σ_j f_j(s) · exp(−B·s²) · occ_j · exp(2πi(h·x_j + k·y_j + l·z_j)), summed over all atoms in the unit cell (using SymetryEquivalents if available). The atomic scattering factors f_j(s) use the Cromer–Mann 4-Gaussian + constant approximation (International Tables Vol. C, Table 6.1.1.4).
5. Lorentz-polarization correction: L·P = (1 / (2 sin²θ cosθ)) · ((1 + cos²2θ) / 2).
6. Intensity: I = |F|² · L·P.
7. Grouping: Reflections with the same rounded 2θ (4 decimal places) are merged; intensities are summed, multiplicities added. This is valid for every crystal system without hard-coded symmetry tables.
8. Profile: The rendered profile is a sum of pseudo-Voigt profiles centered at each peak 2θ_k with the chosen FWHM:
   • Gaussian: exp(−4 ln 2 · x²) where x = (2θ − 2θ_k) / FWHM.
   • Lorentzian: 1 / (1 + 4x²).
   • Pseudo-Voigt: η · G + (1 − η) · L with η = PseudoVoigtEta (default 0.5).

8.5. Export

The ExportData() dialog offers two paths:

• 📊 CSV data — one row per peak: 2θ(°), d(Å), Q(Å⁻¹), h, k, l, Intensity, Multiplicity, |F|. Written as UTF-8 with a leading comment line.
• 🖼️ Image — saves the current plot bitmap as PNG, JPEG (quality 95, via EncoderParameters), or BMP.

btnCopy places the bitmap on the clipboard as both a DataFormats.Bitmap and a raw PNG stream.

8.6. Settings Persistence

The PowderDiffractionSettings class holds all numeric and boolean values as properties with defaults defined in constants (single source of truth). Clone() and ResetToDefaults() are available for programmatic use. The window synchronizes controls to settings via LoadSettingsToUI() and SaveUIToSettings().

9. Crystal Planes & Mean Planes

Tal can define, edit and visualize two kinds of crystallographic planes:

• Mean plane — the least-squares best-fit plane through a set of selected atoms.
• hkl plane — a crystallographic plane defined by its Miller indices.

9.1. Planes Window (list manager)

Opened from Calculate → Planes... or from the main Planes toolbar button. It is a DockContent named PlanesWindow, docked left/right or floatable.

Controls

The window maintains a color icon cache (_colorImageCache) keyed by ARGB value, so repeated planes of the same color reuse the same ImageList index.

9.2. Plane Properties Window

PlanePropertiesWindow is a modal-ish dialog (border fixed, center-parent) with a tab control for the two plane types and a common options group.

Tab: Mean plane

• Pick atom to select: three radio buttons — Picked atom (default), Picked molecule, Ring.
• Or select: three buttons — All, Non-hydrogen, Hydrogen.
• Selection info: a status label that shows the current count. If fewer than 3 atoms are selected the label turns firebrick and shows "Selected: N atoms (need at least 3)".

When the Mean plane tab is active, the window enters plane selection mode in the main form. A 300 ms timer monitors the selection count and refreshes the label. Atom clicks are routed through HandleAtomPick(int atomIndex) according to the current selection mode:

• Picked atom — toggles the single atom's selected flag and updates SelectionOrder and NumberSelected.
• Picked molecule — selects all atoms with the same IndividualMoleculeInCell.
• Ring — calls RingFinder.FindSmallestRing() with parameters maxRingSize = 12, requirePlanar = true, planarityTolerance = 0.15 Å. If no ring is found, falls back to selecting the single clicked atom.

Tab: hkl

• Numeric up-down controls for h, k, l. Range −20 to +20. Default all zero; if all three are zero the dialog refuses to save and shows a warning.

Common options (groupBoxCommon)

On OK, SaveUIToPlane() copies the UI state to the working plane and calls CalculatePlaneGeometry(). The result is exposed via the Result property.

9.3. Mean Plane Calculation

The least-squares mean plane is computed by MeanPlaneCalculator.CalculateMeanPlane():

1. Collect the selected atom positions in raw Cartesian space. Because Molecule.atom[i].Coordinate is stored with −MoleculeShift applied, the shift is added back so the plane is independent of re-centering.
2. Compute the centroid.
3. Build the 3×3 symmetric covariance matrix of the centered positions.
4. Eigendecompose it with the Jacobi algorithm (max 50 sweeps, ε = 1e-12). Eigenvectors are returned as columns.
5. The eigenvector with the smallest eigenvalue is the plane normal.
6. Corners are built by PlaneGeometry.BuildRectangle(center, normal, size), which constructs an orthonormal (u, v) basis inside the plane and returns the four corners center ± u·size ± v·size.

The plane equation coefficients A, B, C, D are stored (Ax + By + Cz + D = 0). The corners are stored in raw Cartesian (without shift), so the draw layer subtracts the current shift at render time.

9.4. hkl Plane Calculation

PlaneGeometry.CalculateHKLPlane() uses the molecule's fractional-to-Cartesian matrix (transposed, to match Molecule.PrepareUnitCell) to convert intercept points into Cartesian space. The intercepts depend on how many Miller indices are zero:

• All zero — invalid, empty result.
• One non-zero — the plane is a cell face; returns the 4 corners of that face at x = 1/h, y = 1/k, or z = 1/l.
• Two non-zero — the plane is parallel to the axis with the zero index; returns 4 corners that sweep the cut edge along that axis.
• Three non-zero — general case; returns the 3 intercepts with the axes, and a rectangle is built around the centroid with the chosen size (default 10 Å).

9.5. Plane Intersection

PlaneGeometry.ComputeIntersection(p1, p2) returns a PlaneIntersection struct with a point on the line, the normalized direction, and a half-length. The algorithm:

1. Direction = n₁ × n₂ (normalized). If nearly zero, the planes are parallel and the result is invalid.
2. A starting point is found by two Newton-style projections (onto plane 1, then along the projected n₂, then again onto plane 1).
3. For each plane, the line (point + t·dir) is projected into the plane's local (u, v) basis. The u/v extents are computed by scanning all 4 corners, so any corner ordering works. The permitted t-interval is the intersection of the u and v slab constraints.
4. The final point is at the midpoint of the interval; the half-length is half the interval length (minimum 0.1 Å). A bounding-box fallback is used if the precise computation fails.

9.6. Ring Finder

RingFinder finds the smallest ring containing a clicked atom:

1. For each bonded neighbor of the clicked atom, run a BFS back to the clicked atom.
2. The BFS forbids passing through the start atom as an intermediate and forbids the direct neighbor → start edge (which would give a trivial 2-ring).
3. Candidate rings shorter than maxRingSize and free of duplicate atoms are tested for planarity by PCA (smallest eigenvalue of the covariance matrix).
4. The smallest planar ring is returned. If none is planar, the smallest non-planar ring is not returned — the caller falls back to single-atom selection.

9.7. CrystalPlane Data Model

10. Morphology

Opened from the Advanced menu, this tool is used for analyzing and visualizing the macroscopic crystal habit (morphology) based on the internal crystal structure.

The morphology is predicted using the Bravais-Friedel-Donnay-Harker (BFDH) method, which relates the importance of a crystal face to its interplanar spacing (dhkl) and the lattice geometry. The tool allows you to:

• Generate a 3D polyhedron representing the predicted crystal habit.
• Color the faces based on their Miller index (hkl) or other properties.
• Overlay the predicted morphology with the 3D structure of the molecule.

10.1. Morphology Window

The main control window is the MorphologyWindow, a DockContent that can be docked left, right, or floated. It is opened from Advanced → Crystal Morphology.... The window is divided into three vertical zones:

• Top panel — calculation parameters and action buttons.
• Info panel — a summary of the predicted habitus and unit cell.
• Face table — an owner-drawn ListView listing every face that survived the BFDH filtering.

10.2. Calculation Parameters

All parameters are exposed as WinForms controls in the top panel:

10.3. Face Table

The face table is a ListView with View.Details, FullRowSelect, and custom owner-drawing (DrawColumnHeader / DrawItem / DrawSubItem). The columns are:

Clicking a row highlights the corresponding face in the 3D view (all triangles with the same FaceName get a yellow outline). This is implemented via MorphologyDocument.HighlightFace(string faceName), which rebuilds a dedicated VertexBuffer (_highlightVB) containing the face's triangle edges.

10.4. The BFDH Algorithm

The BFDH (Bravais–Friedel–Donnay–Harker) method predicts crystal morphology from the crystal structure by assuming that the growth rate of a face (hkl) is inversely proportional to its interplanar spacing d_hkl:

RelativeGrowthRate(hkl) ∝ 1 / d(hkl)

Faces with large d_hkl grow slowly and therefore dominate the final crystal habit. The algorithm implemented in CrystalMorphologyFinder proceeds as follows:

1. Plane enumeration: All integer triples (h, k, l) with |h|, |k|, |l| ≤ maxIndex are generated. The trivial (0,0,0) is rejected, as are all triples whose GCD is greater than 1 (they represent the same plane as the primitive triple). This is done by GenerateUniquePlanes.
2. d-spacing calculation: For each candidate, the d-spacing is computed from the triclinic metric tensor by CalculateDSpacing. Planes with d < minDSpacing are discarded.
3. Multiplicity calculation: The real multiplicity is computed from the crystal's space group by CountEquivalentPlanesReal, which builds the orbit of (hkl) under the linear parts of all symmetry operations and counts distinct canonical forms. If the space group is unavailable or invalid, the code falls back to a cubic approximation (CountEquivalentPlanesCubic), which is clearly marked as a fallback.
4. Relative growth rate: RelativeGrowthRate = 1 / d.
5. DistFrac computation: DistFrac is defined as RelativeGrowthRate / min(RelativeGrowthRate), so the largest face has DistFrac = 1.
6. Softening (optional): The DistFrac values are compressed according to the selected SofteningMode (see section 10.5).
7. Relative area: RelativeArea = 1 / DistFrac, normalized to the maximum. Note that this is a visual heuristic — the code explicitly does not multiply by multiplicity, because the physical area of a face depends on the depth of the cut (DistFrac), not on the number of symmetry-equivalent planes.
8. Sorting: The face list is sorted by DistFrac ascending, so the largest faces come first.
9. Habitus classification: ClassifyHabitus inspects the relative areas of the {100}, {010}, {001}, {110}, {101}, {011}, and {111} families and returns one of: cubic / octahedral, plate, needle / prismatic, rhombic / dodecahedral, equant (isometric), prismatic, or unknown.

10.5. Softening Modes

Pure BFDH (SofteningMode.None) is physically correct but often produces crystals with many very small, almost invisible faces. The softening modes are visual heuristics that compress the DistFrac distribution to produce more aesthetically pleasing or recognizable shapes. They are not physically based models and should be used with that in mind.

When the mode is changed in the combo box, the numeric up-down is automatically updated to the suggested strength for that mode (via GetSuggestedSoftening). The user can of course override this value.

10.6. Morphology 3D View (MorphologyDocument)

The 3D crystal is displayed in a MorphologyDocument, a DockContent that hosts a MonoGame viewport. It is created automatically the first time "Calculate" is clicked in the Morphology window, and reused on subsequent clicks (the title is updated to reflect the current structure name).

Construction

The polyhedron is built by MorphologyCrystal.Build:

1. Start with a large cube (ConvexPolyhedronFrac.FromBox) of half-edge 3.0 · scale Å in fractional space.
2. Sort the surviving faces by DistFrac ascending (largest faces first).
3. For each face, compute its unit normal in Cartesian space and the scaled plane offset dScaled = DistFrac · ‖g‖ · faceOffset, where ‖g‖ is the norm of the reciprocal-lattice vector of (hkl).
4. Clip the current polyhedron by the half-space defined by this plane (ConvexPolyhedronFrac.ClipByPlane). The clipping is a Sutherland–Hodgman-style operation on each triangle, followed by a cap construction from the intersection points (a fan triangulation of the cap polygon, oriented to match the plane normal).
5. If a clip would destroy the polyhedron entirely, it is rolled back. A maximum of MaxSuccessfulClips = 14 successful clips is enforced to keep the polyhedron manageable.
6. The resulting fractional-space triangles are converted to Cartesian space using the molecule's fractional-to-Cartesian matrix (transposed to match Molecule.PrepareUnitCell).
7. Face colors are assigned deterministically from the face name (NameToColor) using an FNV-1a hash mapped to HSV. The starting cube's "cell-*" faces are rendered in neutral grey.

Rendering and interaction

• Camera: a shared Camera instance; the default position is (0, 0, 100) looking at the origin.
• Rotation: left mouse drag. The rotation matrix is exposed via GetRotationMatrix() so the Wulff plot can follow it.
• Zoom: mouse wheel. The zoom factor is clamped to 0.2–5.0 and applied on top of an automatic scene scale (40 / BoundingRadius) that keeps the crystal nicely framed.
• Reset View: restores the default camera position, identity rotation, and 1× zoom.
• Projection: switches between orthographic (default) and perspective based on Flags.Instance.PerspectiveMode.

Side panel controls

• Alpha (0–255): sets the transparency of the crystal faces. The alpha value is applied to every triangle's color at render time (a TrackBar with a live numeric label).
• Show Edges: toggles the drawing of black edges along the boundaries between faces. The edge buffer is rebuilt whenever the visibility, alpha, or crystal changes.
• Show Face Labels: toggles the drawing of (hkl) labels at the centroid of each face. Uses the shared SpriteFont1 and respects Flags.LabelScale, Flags.LabelColor, Flags.LabelShadow, and Flags.LabelShadowColor. Faces with duplicate names share a single label at their combined centroid.
• Monochrome / Color swatch: enables a single user-selected color for all faces instead of the per-face deterministic colors. Clicking the swatch opens a ColorDialog.
• Reset View: resets the camera and the zoom factor.
• Zoom info label: shows the current zoom factor in the form "Zoom: X.XX× (mouse wheel)".

Edge detection algorithm

Edges are drawn only along the true boundaries between two different faces. The algorithm is deliberately careful about numerical robustness:

1. All triangle vertices are merged into unique positions using a 27-neighbour hash grid with a tolerance EPS_world = BoundingRadius · 1e-4 (in the crystal's original scale, not after any zoom or scale transform).
2. The set of unique raw edges (pairs of vertex indices) is built from all triangles.
3. T-junction removal: for each raw edge, all other unique vertices are tested for lying on the segment (parameter t ∈ (tEps, 1 − tEps), perpendicular distance < 4 · EPS_world). Vertices that pass are sorted by t and the edge is split into a chain. This removes the visual gaps that appear at T-junctions where two triangles of the same face share a boundary with a third triangle of a different face.
4. For each triangle, the chain is walked and each sub-segment is tagged with the face ID of the triangle. If a sub-segment ends up tagged with two or more distinct face IDs, it is drawn once as a boundary edge.
5. Face IDs are computed by GetFaceId: if the triangle has a non-empty FaceName, that name is used; otherwise a synthetic ID is built from the sign of the triangle normal.

Face highlighting

When the user selects a row in the face table, MorphologyWindow calls MorphologyDocument.HighlightFace(faceName) with the selected face name (or null to clear). This rebuilds the highlight vertex buffer by:

1. Collecting all triangles whose FaceName equals the requested name.
2. Merging their vertices into a small local hash grid (tolerance derived from the bounding radius and the current zoom).
3. Emitting a yellow (255, 255, 0, 255) line segment for every edge that appears in exactly one triangle of the selected face.
4. The highlight is drawn with DepthStencilState.None so it always appears on top of the crystal, regardless of depth ordering.

10.7. Wulff Plot (Stereographic Projection)

The Wulff plot is opened by clicking the Wulff Plot button in the Morphology window. It opens a WulffPlotDocument, a DockContent that renders a stereographic projection of the crystal faces. This is the standard graphical tool in crystallography for visualizing the angular relationships between faces and the symmetry of the crystal.

Stereographic projection

Each face is represented by its unit normal vector n in Cartesian space. The projection is defined with the +c axis at the center of the plot:

θ = acos(n.z)                    // polar angle from +c
φ = atan2(n.y, n.x)               // azimuthal angle in the ab plane
r = tan(θ / 2)                    // stereographic radius (gnomonic-scaled)
x_plot = r · cos(φ)
y_plot = r · sin(φ)

The factor tan(θ/2) is the standard Wulff-net stereographic projection (equal-angle). Faces close to +c project near the center; faces in the ab plane (θ = 90°) project onto the outer circle. Lower-hemisphere faces (n.z < 0) are mirrored onto the upper hemisphere for display (their z component is negated before projection), and are drawn as hollow circles; upper-hemisphere faces are drawn as filled circles.

Plot layout

• The plot area is always square-ish: the effective radius is min(screenW, screenH) / 2 · 0.85, multiplied by the current zoom factor. This keeps angular relationships correct regardless of the window aspect ratio.
• The outer circle (the θ = 90° equator) is drawn in light grey.
• An optional polar grid (every 10° of θ, plus radial lines every 30° of φ) is drawn in a dark blue-grey.
• An optional bold cyan equator is drawn on top of the grid when Show Equator is enabled.
• Each face is drawn as a small filled circle (upper hemisphere) or a ring (lower hemisphere). The size is controlled by the Point Size slider (4–24 px, default 10).
• Face labels (hkl strings) are drawn above each point using the shared SpriteFont1, respecting the global label settings from Flags.

Side panel controls

• Follow 3D Rotation: when checked, the plot rotates in sync with the 3D crystal view. The rotation matrix is obtained from MorphologyDocument.GetRotationMatrix() and multiplied by the same view matrix used by the 3D renderer (Matrix.CreateLookAt((0,0,100), Zero, Up)) so that the two views are visually consistent.
• Show Labels (hkl): toggles the (hkl) text labels.
• Show ALL faces: when unchecked (default), only faces present in the current 3D crystal polyhedron are shown. When checked, every face from the BFDH calculation is shown, including those that were clipped away during polyhedron construction. This is useful for understanding which planes the algorithm considered.
• Show Grid (10°): toggles the polar grid.
• Show Equator (θ=90°): toggles the bold equator circle.
• Color by d-spacing: when checked, replaces the deterministic per-face color with a rainbow gradient from red (large d) to blue (small d). The gradient is computed from t = d / maxD as (255·t, 100 + 100·(1 − |2t − 1|), 255·(1 − t)).
• Hemisphere group: three radio buttons — Upper only, Lower only, Both (default). Filters the projected points by the sign of n.z.
• Point Size: a slider (4–24, default 10) controlling the radius of the plotted points.
• Zoom info label + Reset Zoom: shows the current zoom factor; the reset button sets it back to 1.0.
• Refresh: forces a re-extraction of plot positions and a rebuild of the vertex buffers. Useful when the underlying crystal or its visibility has changed outside the Wulff plot.

Mouse interaction

The only mouse interaction is the wheel: scrolling up multiplies the zoom factor by 1.15, scrolling down by 0.87. The zoom factor is clamped to 0.3–5.0.

Vertex buffer strategy

Three separate VertexBuffers are maintained and rebuilt whenever the plot needs to be refreshed:

• _circleVB — the outer circle (128 segments, LineList).
• _gridVB — polar grid, radial lines, and equator (LineList).
• _pointsVB — the face markers, drawn as triangle fans (upper hemisphere) or triangle strips (lower hemisphere rings) (TriangleList).

The plot background is taken from Flags.Instance.color1, matching the 3D viewport so that screenshots and the on-screen plot have consistent backgrounds.

11. Structure Overlay

Opened from the Advanced menu, the 🔬 Structure Overlay window is a powerful tool for comparing multiple molecular structures.

Key Features:

• Add Structures: You can add any of the structures from your Structure List to the overlay.
• Manual Alignment: Each structure in the overlay can be independently translated and rotated using sliders, allowing you to manually superimpose them.
• Automatic Alignment: A powerful algorithm can automatically align the structures based on a common substructure or by minimizing the Root Mean Square Deviation (RMSD) between their atoms.
• Visualization: Each structure in the overlay can be given a unique color to easily distinguish them. You can also change their display style (e.g., show one as balls & sticks and another as a wireframe).

This tool is invaluable for comparing different conformations of a flexible molecule, or comparing a calculated structure with an experimental one.

11.1. Overlay Manager Window

The main control window is the MoleculeOverlayWindow (a DockContent named "🧬 Overlay Manager"), opened from Advanced → Overlay Manager.... It can be docked left, right, or floated, and holds an OverlayManager instance that is the shared data model for the whole overlay feature. The window is laid out as three vertical panels:

• Top panel — buttons for adding/removing molecules, the list of overlay entries, the visibility checkbox, and the atom counter.
• Middle panel — the ListBox of overlay entries (custom owner-drawn so each entry can be colored with the molecule's actual color).
• Bottom panel — the transformation radio buttons (None, Mirror, Inversion) and the status label.

11.2. The Overlay Data Model

Every entry in the overlay is an instance of OverlayMoleculeData, which holds:

The class exposes two important methods: InitializeWorkingData() (deep-copies OriginalAtoms into WorkingAtoms and stores the original ADP matrices) and ResetToOriginal() (reverses the process, restoring the working atoms from the originals while preserving the current color and style).

11.3. The Overlay Manager (OverlayManager.cs)

OverlayManager owns the list of OverlayMoleculeData entries and exposes a small API used by the window. The public surface is:

• IReadOnlyList<OverlayMoleculeData> OverlayMolecules — read-only view of the current entries.
• int TotalAtomCount — sum of WorkingAtoms.Count across all entries.
• event EventHandler MoleculesChanged — raised whenever the list or any entry's state changes, so the window and any overlay views can refresh.
• AddSelectedMolecule(doc, mode) — adds the whole molecule containing the selected atoms as a single entry.
• AddSelectedAtoms(doc, mode) — adds just the selected atoms as a single entry (marked IsSelection = true).
• AddSelectedStructure(doc, mode) — adds every atom of the document's molecule (including symmetry-generated ones) as a single entry (marked IsStructure = true).
• RemoveMolecule(id) — removes an entry by ID and raises MoleculesChanged.
• ClearOverlayMolecules() — removes all entries.
• ToggleVisibility(id) — flips the IsVisible flag.
• SetMoleculeColor(id, color) — sets the per-entry color and propagates it to every CustomColor field of the working atoms.
• SetMoleculeStyle(id, styleIndex) — sets the per-entry style (0 = CPK, 1 = Sticks, 2 = Balls & Sticks, 3 = Ellipsoids).
• SetTransformationForMolecule(id, mode) — the main transformation entry point (see below).
• FitMoleculeToPoints(source, sourcePoints, targetPoints) — the fitting entry point (see below).
• IsBaseMolecule(id) / GetBaseMoleculeId() — helpers for the "base molecule" concept (see section 11.6).

11.4. Adding Molecules — Workflow

The Overlay Manager exposes three "Add" buttons, each backed by a different method of OverlayManager. All three share the same underlying extraction logic, but differ in which atoms are collected:

1. Add Molecule (AddSelectedMolecule): collects all atoms of the molecule that contains the currently selected atoms. The molecule ID is taken from IndividualMoleculeInCell. If the source document has no molecule numbering (single-molecule file), all atoms are added as one entry. This is the most common case.
2. Add Selection (AddSelectedAtoms): collects only the currently selected atoms. This produces an entry marked IsSelection = true and is useful for comparing, e.g., just a ring system or a metal coordination sphere. Note: the current version of the Molecule Overlay window does not expose a button for this method — the button is commented out in the source, but the API remains available for programmatic use.
3. Add Structure (AddSelectedStructure): collects every atom of the source document's molecule, including all symmetry-generated atoms. This produces an entry marked IsStructure = true. Use this when comparing two whole crystal packings.

In all three cases, the first 3 selected atoms are stored as reference points. If fewer than 3 atoms are selected, the entry is still created, but HasReferencePoints is false and the automatic fitting (section 11.5) is skipped.

11.5. Automatic Fitting (3-Point Rigid-Body Superposition)

The core of the overlay feature is the automatic fitting algorithm, implemented as OverlayManager.IterativeFit(sourceMolecule, sourcePoints, targetPoints). Despite the name "iterative", the current implementation is a single-pass, closed-form rigid-body transformation that maps a source reference frame (defined by the 3 source points) onto a target reference frame (defined by the 3 target points).

The algorithm

1. Build a local orthonormal basis for the source points:

   xs = normalize(P1_source − P0_source)
   zs = normalize(cross(xs, P2_source − P0_source))
   ys = cross(zs, xs)   // already unit length

   The three vectors (xs, ys, zs) form a right-handed orthonormal frame anchored at P0_source.
2. Build the corresponding local basis for the target points using the exact same construction (same cross-product order, same sign conventions), anchored at P0_target. Because the construction is identical, the two bases have the same handedness, and the map between them is guaranteed to be a proper rotation (determinant +1, no reflection).
3. Compute the rigid-body transformation as a change of basis. For any atom at position p (in the source frame), its new position is:

   v = p − P0_source
   a = dot(v, xs), b = dot(v, ys), c = dot(v, zs)
   p_new = P0_target + a · xt + b · yt + c · zt

   This is the classic "re-express in the source basis, then rebuild in the target basis" trick. It implements a pure rotation + translation, with no scaling and no reflection. The three source points are mapped exactly onto the three target points by construction.
4. Apply the same mapping to every working atom and to the working reference points.
5. Recalculate bonds via RecalculateBondsForMolecule, which rebuilds the per-atom bond lists, distances, angles, and precomputed bond matrices from the new coordinates. This is necessary because the overlay atoms are rendered with the same bond-drawing code as regular molecules.
6. Report the fit quality: the initial and final sum of distances between the three source points and the three target points is logged, along with the improvement (in Å and as a percentage). For a successful rigid-body fit, the final error should be 0.0000 Å (to floating-point precision) — any non-zero residual indicates either that the three source points were collinear (in which case the fit is aborted with a "punkty współliniowe" error) or that the fit was called on a degenerate reference frame.

When is fitting triggered?

• Automatically on add: when a new molecule is added to an overlay that already contains at least one other entry, AddSelectedMolecule (and its siblings) calls AutoFitMolecule at the end. The new molecule is fitted onto the base molecule (the first entry in the list).
• Automatically on transformation change: when the user changes the transformation radio button for a non-base molecule, RbTransformation_CheckedChanged calls AutoFitSelectedMolecule(), which re-fits the molecule onto the base using the (possibly mirrored) reference points.
• Manually: the user can re-trigger a fit at any time by re-selecting the same transformation or by removing and re-adding the molecule. There is no dedicated "Fit" button in the current UI.

11.6. Base Molecule and Locked Operations

The first entry in the overlay list is special: it is the base molecule (marked with ⭐ BASE in the list). All subsequent molecules are fitted onto the base. To preserve a stable reference, the following operations are disabled for the base molecule when the overlay contains more than one entry:

• Remove — the base cannot be removed (it would invalidate all fits).
• Center — the base is already at the origin by construction.
• Transformation radio buttons — mirror/inversion on the base would invalidate the reference frame.

The only operation that remains enabled for the base is Color: changing the color of the base is purely cosmetic and does not affect any fit.

When the overlay contains exactly one entry, all operations are enabled for that single molecule (it is not yet "base" in any meaningful sense). When the overlay is empty, all operations are disabled.

11.7. Transformations (Mirror and Inversion)

Before fitting, the user can apply one of three transformations to a non-base molecule. These are exposed as radio buttons in the bottom panel:

Transformation is applied before the automatic fit. The workflow is:

1. The user selects a transformation radio button.
2. RbTransformation_CheckedChanged verifies the molecule is not the base (otherwise it restores the previous radio state and shows a "Cannot transform BASE molecule" status).
3. SetTransformationForMolecule(id, mode) is called. It resets the working atoms from the originals, preserves the current color and style, and applies the appropriate transform matrix.
4. AutoFitSelectedMolecule() is called, which re-fits the (now transformed) molecule onto the base using the reference points.
5. Both the list and the Overlay View are refreshed.

11.8. Colors and Styles

Each overlay entry has its own color, chosen from a random hue at creation time (via GetRandomColor, which picks a random hue and converts to RGB with a sine-based palette). The color is applied to every atom's CustomColor field, so the whole molecule is rendered in a single, distinct color.

To change the color of the selected molecule, click the colored button in the top panel (its background is the current molecule color). A standard ColorDialog opens; on OK, the color is applied via SetMoleculeColor and the list is refreshed. Color can be changed even for the base molecule — it is the only operation that remains enabled for the base.

The style of an overlay entry can be changed programmatically via SetMoleculeStyle(id, styleIndex), but this is not currently exposed as a UI control in the Overlay Manager window. The available styles are 0 = CPK, 1 = Sticks, 2 = Balls & Sticks (the default), 3 = Ellipsoids.

11.9. Overlay View Window

The Show button in the Overlay Manager opens (or brings to front) the OverlayViewWindow, a DockContent hosting a MonoGame viewport that renders all visible overlay atoms. The window is subscribed to OverlayManager.MoleculesChanged, so any change to the overlay (add, remove, transform, color change, visibility toggle) is reflected immediately.

Rendering

OverlayViewWindow.UpdateDisplay() collects the WorkingAtoms of every visible entry and passes them to the underlying GameWindow via SetOverlayAtoms(). The atoms are rendered with the same pipeline as regular molecules, so all display styles (CPK, balls & sticks, ellipsoids) and per-atom colors work as expected. Bond detection is done per-molecule (the overlay does not merge bonds across molecules), so an intermolecular contact in the overlay is not drawn as a bond — this is intentional, since the overlay is meant for comparing molecular geometries, not crystal packings.

Lifecycle

• The window is created lazily: the first time the user clicks "Show", a new OverlayViewWindow is created with the current OverlayManager and docked as a document.
• If a window already exists (e.g., after a layout save/restore), FixExistingOverlayView() detects it and injects the current manager if the existing one is null. This prevents the classic "Overlay View is empty after reloading the layout" bug.
• On close, the window unsubscribes from MoleculesChanged and clears its atom buffer.

11.10. Typical Workflow — Step by Step

1. Load the base structure. Open a CIF/RES/etc. file. The structure appears in the main 3D view.
2. Pick 3 reference atoms on the base. Switch to Pick Atoms mode (or use the default rotate mode with Ctrl+click). Click three atoms that define a unique, non-collinear frame — for example, three atoms of a phenyl ring, or a central atom plus two substituents. You should see them highlighted in yellow.
3. Open the Overlay Manager (Advanced → Overlay Manager...). The list is initially empty.
4. Add the base as the first entry. Click Add Molecule. The molecule containing the 3 selected atoms is added as the first entry, marked ⭐ BASE. Its 3 reference points are stored.
5. Load the target structure. Open a second file. The main 3D view switches to the new structure.
6. Pick 3 corresponding atoms on the target. These must be the "same" 3 atoms as on the base — same chemical environment, same relative geometry. For example, the equivalent three atoms of the same ring.
7. Add the target. Click Add Molecule again. The new molecule is added to the list and automatically fitted onto the base using the 3+3 reference points. The fit status is shown in the status label ("Fitted to base").
8. Inspect the overlay. Click Show to open the Overlay View. Both molecules should overlap at the 3 reference atoms; any deviation elsewhere is a real conformational or symmetry difference.
9. If the fit is wrong, try a mirror. If the two molecules are related by reflection (e.g., enantiomers), select the target entry in the list and click the Mirror radio button. The molecule is re-fitted with the mirror applied first, and should now overlap correctly.
10. Try a different set of reference atoms if needed. Remove the target entry (❌ Remove), pick a different set of 3 atoms, and re-add. The fitting is deterministic — the same 3+3 pair always produces the same result.
11. Color and style. Use the color swatch button to distinguish the molecules. Use Show All to toggle visibility of the whole overlay.
12. Clear when done. Click 🗑️ Clear to remove all entries, or close the Overlay Manager — the overlay state is kept in memory as long as the window is open.

11.11. Limitations and Notes

• Rigid-body only. The fit is a pure rotation + translation. It does not allow bond stretching, angle bending, or torsional flexibility. If the two molecules differ in conformation, the overlay will show a real, unfittable discrepancy at the flexible parts.
• Exactly 3 reference points. The algorithm requires exactly 3. Using more points would require a least-squares (Kabsch) fit, which is not implemented. If you need to fit on more atoms, pick the 3 that best define the rigid core.
• Handedness matters. If the two structures are related by reflection, the direct fit will fail (the fit will be "correct" in the sense of a rigid transform, but the molecule will appear inside-out). Use the Mirror transformation to pre-reflect the source.
• Symmetry-generated atoms. "Add Molecule" uses the atoms as they are in the document, which may include symmetry-generated copies (depending on the current packing mode). If you want just the asymmetric unit, set the packing mode accordingly before adding.
• No persistence. The overlay list is not saved to disk. Closing the Overlay Manager and reopening it starts from an empty list.

12. Advanced Tools

12.1. H-Bond Settings

Opened from the Display menu (right-click on the H-Bond checkbox) or the main menu, this window provides detailed control over hydrogen bond detection and display.

• Distance Modes: You can define H-bonds based on an absolute distance range (e.g., 1.5 - 3.5 Å) or a VdW-based criterion (e.g., distance is less than the sum of vdW radii minus a tolerance).
• Angle Criterion: Set the minimum D-H...A angle (typically > 120°).
• Atom Selection: Choose which elements can act as hydrogen bond donors and acceptors. This is crucial for getting chemically meaningful results.
• Display Options: Customize the color, and draw style (solid or dashed) of the H-bonds.

12.2. Atom Display Settings

Refer to section 4.6 for a detailed description of this window.

12.3. Debug Window

Opened from the Window menu, this window shows a detailed log of symmetry operations found in the loaded structure. It's a diagnostic tool for developers and advanced users to troubleshoot issues with symmetry or file parsing.

12.4. BufferedPanel (helper control)

Tal.Forms.BufferedPanel is a System.Windows.Forms.Panel subclass that enables DoubleBuffered plus AllPaintingInWmPaint, OptimizedDoubleBuffer and UserPaint control styles. It is used wherever smooth custom drawing is required (e.g., the powder diffraction plot).

12.5. Structure Info Window

Opened from Tools → Structure Info. The StructureInfoWindow is a dockable panel (a DockContent) that acts as the central, always-available reference for every numeric and textual property of the currently loaded structure. It replaces the need to dig through the raw file or the debug log to find a specific value: every quantity the parsers extracted (cell parameters, symmetry operations, refinement statistics, atomic coordinates with uncertainties, contacts, H-bonds, measured distances, etc.) is laid out in a clean, scrollable table.

12.5.1. Window Layout

The window is divided into four regions:

• Top panel (panelTop): a read-only txtCurrentStructure showing the identifier of the structure currently loaded into the window (e.g., the CIF data block name or the file name), plus a btnCustomise button reserved for future per-window customization.
• Left panel (panelButtons): a vertical stack of section-switching buttons. Exactly one is highlighted (back-coloured with a light blue) at any time to indicate the active section.
• Center panel (panelTableScroll): an auto-scrolling container hosting a single TableLayoutPanel (table). The panel is a BufferedPanel, so the table redraws without flicker when the user switches sections.
• Bottom panel (panelBottom): a Close button.

12.5.2. Section Buttons and Tables

Each button populates the table with a dedicated Section object (a small inner class that holds a list of column headers and a list of string rows). The current sections are:

12.5.3. Error Estimation

For every geometric quantity, the window reports an estimated standard uncertainty (e.s.d.). The formulas are consistent with the ones used by the Measure tool, and propagate the per-atom positional errors stored in Coordinate_error (which already include the cell-parameter contribution):

• Bond length error: if the two atoms have positions p1, p2 with errors e1, e2 and d = |p1 − p2|, then

  σ_d² = (dx/d)²·(e1x² + e2x²)
       + (dy/d)²·(e1y² + e2y²)
       + (dz/d)²·(e1z² + e2z²)

  where (dx, dy, dz) = p1 − p2.
• Angle error: an upper-bound estimate

  σ_angle ≈ √2 · mean(|e1|, |e2|, |e3|) / min(l1, l2)   [rad]
         → σ_angle · 180/π                                  [deg]

  clamped to [0.001°, 10°] to avoid absurd values for near-degenerate geometries.
• Torsion error: an upper-bound estimate

  σ_torsion ≈ √2 · mean(|e1|, |e2|, |e3|, |e4|) / l_BC · 180/π

  where l_BC is the length of the central bond, clamped to [0.001°, 30°]. This reflects the fact that torsions are most sensitive to errors when the central bond is short.

When an error is too small to be meaningful (or the source file did not provide positional errors), the cell shows an em-dash (—) instead of a number.

12.5.4. Torsion Angle Formula

The dihedral angle A-B-C-D is computed by:

a = A − B
b = C − B
c = D − C
d = B − C

n1 = normalize(cross(a, b))
n2 = normalize(cross(c, d))

angle = acos(clamp(dot(n1, n2), -1, 1))

if dot(cross(n1, n2), normalize(b)) < 0:
    angle = −angle

The sign convention matches IUPAC: a positive torsion is a clockwise rotation of the far bond when looking along the central bond from B to C. The result is in radians internally, and converted to degrees for display.

12.5.5. Dynamic Behaviour

• The window caches Section objects in a Dictionary<string, Section>. When the structure changes (a new file is loaded or the active document switches), LoadStructure re-populates every section from the new Molecule, then re-fills the currently visible table.
• The Angles and Torsions sections are special: they are populated lazily, only when the corresponding button is clicked. This avoids the cost of enumerating up to 50,000 rows when the user is only interested in, say, the unit cell parameters.
• Switching between sections does not re-run the parsers — all data is extracted once in PopulateSections and simply re-displayed.

12.5.6. Number Formatting

The window uses the classic crystallographic "value(esd)" notation. For example, a cell parameter a = 5.6789 with a_e = 0.0012 is rendered as 5.6789(12). The number of decimal places is chosen from the magnitude of the e.s.d.: if error < 1, the number of decimals is the position of the first significant digit of the error. Volume is computed from the cell parameters and its e.s.d. is propagated analytically from the partial derivatives with respect to a, b, c, α, β, γ.

12.5.7. Source of the Populated Data (CIF / RES)

All quantities displayed by the Structure Info Window are extracted by the parsers from the source file. The mapping is fully deterministic — a value appears in the table only if the corresponding field is present in the CIF (or RES/INS) file. Missing fields are silently omitted; the window never invents data.

Cells, symmetry and atoms

• Unit cell a, b, c, α, β, γ and their e.s.d.'s — from the CIF _cell_length_* and _cell_angle_* tags, or from the RES CELL/ZERR cards.
• Cell volume — from _cell_volume if present; otherwise computed from a, b, c, α, β, γ.
• Space group number, H-M name — from _space_group_IT_number, _space_group_name_H-M_alt / _symmetry_space_group_name_H-M; RES reads TITL and LATT.
• Symmetry operations — from the _space_group_symop_operation_xyz loop; RES reads the SYMM cards. The full list is displayed verbatim in the Symmetry section.
• Atoms — from the _atom_site_* loop (label, type symbol, fractional x/y/z, x/y/z esd's, occupancy, U_iso, ADP type, disorder group, and the six U^ij components when _atom_site_adp_type = Uani); RES reads the atom cards with the SFAC mapping.

Refinement statistics

• _refine_ls_R_factor_gt → R1 observed.
• _refine_ls_R_factor_all → R1 all.
• _refine_ls_wR_factor_ref / _refine_ls_wR_factor_all → wR2 (all / observed).
• _refine_ls_goodness_of_fit_ref → GooF.
• _refine_ls_number_reflns, _refine_ls_number_parameters, _refine_ls_number_restraints → reflection/parameter/restraint counts.
• _refine_ls_shift/su_max, _refine_ls_shift/su_mean → shift/su max and mean.
• _refine_diff_density_max, _refine_diff_density_min, _refine_diff_density_rms → residual electron density.
• _refine_ls_weighting_scheme and _refine_ls_weighting_details → weighting scheme.
• For RES files the same values are read from the REM lines (R1, wR2, GooF, Nref, Npar, Nres, shift/su max/mean, Δρ max/min).

Reflection statistics

• _diffrn_reflns_number → total reflections.
• _diffrn_reflns_av_R_equivalents and the _reflns_number_gt / _reflns_number_total tags → observed reflections and threshold.
• _diffrn_reflns_theta_min, _diffrn_reflns_theta_max → θ_min, θ_max.
• _diffrn_reflns_resolution_high (or _reflns_d_resolution_high), _diffrn_reflns_resolution_low → resolution limits d_min, d_max.
• _reflns_threshold_expression → the threshold column.

Experiment

• _diffrn_radiation_wavelength, _diffrn_radiation_type → wavelength and radiation type.
• _diffrn_measurement_device_type → measurement device.
• _diffrn_ambient_temperature → temperature (K).
• _exptl_crystal_colour, _exptl_crystal_description → crystal colour and shape.
• _exptl_crystal_size_max, _exptl_crystal_size_mid, _exptl_crystal_size_min → crystal size.
• _exptl_absorpt_coefficient_mu → absorption coefficient μ.
• _exptl_absorpt_correction_type, _exptl_absorpt_correction_T_min, _exptl_absorpt_correction_T_max → absorption correction type and transmission range.
• _exptl_crystal_density_diffrn → calculated density.
• _chemical_formula_sum, _chemical_formula_weight, _chemical_name_common / _chemical_name_systematic → formula, formula weight and compound name.
• _cell_formula_units_Z, _cell_formula_units_Z' → Z and Z'.
• _exptl_crystal_F_000 or _cell_formula_units_Z × _chemical_formula_weight → F(000) if present.

Audit and publication

• _audit_creation_date, _audit_creation_method → audit lines.
• _publ_section_title → publication title.
• _journal_name_full / _journal_name_abbrev → journal name.
• _journal_volume, _journal_page_first, _journal_year → journal reference.
• _journal_doi or _publ_doi → DOI.
• _chemical_melting_point, _chemical_compound_source etc. — read if present; otherwise omitted.

13. Export & Format Integration

13.1. StructureWriter — dispatcher

StructureWriter.Save(structure, path) inspects the file extension and dispatches to the appropriate writer. Returns true on success. Exceptions are caught and logged.

13.2. CifWriter

Writes a StructureData to a CIF file using the IUCr data-name rules. It emits: data_ block, audit lines, chemical metadata, cell parameters (with esd where available), _space_group_IT_number, H-M name, symmetry-operation loop (never guessed — via SymmetryHelper.GetOperationStrings), atom-site loop (label, type, fract coords, occupancy, U_iso, adp_type, optional disorder group), and an anisotropic displacement loop when any atom has AdpType == "Uani".

Number formatting uses CultureInfo.InvariantCulture. The file is written as UTF-8 without BOM.

13.3. ResWriter

Writes a SHELX-format .res file: TITL, CELL, ZERR, LATT, SYMM cards (identity excluded; inversion sign of LATT inferred from SymmetryHelper.ContainsInversion), SFAC/UNIT, atom lines, HKLF 4, END. Occupancy is written as occ + 10 (SHELX free-variable convention). Anisotropic atoms emit the full 6-element U line with the second-line convention.

13.4. XyzWriter

Writes atom count, comment line (structure name), and one Element x y z line per atom. Coordinates are written as stored (Cartesian for non-crystal formats). UTF-8 encoding.

13.5. PdbWriter

Writes HEADER, TITLE, an optional CRYST1 record (when a cell is present, with the H-M name truncated to 11 chars and the space-group number), one HETATM record per atom (serial, 4-char name, "UNK" residue, residue 1, x/y/z, occupancy, B-factor derived from U_iso as B = 8π²·U, element), and END.

13.6. MolWriter

Writes an MDL molfile V2000: header (title truncated to 80 chars, " TAL 3D", blank), counts line (atoms, bonds = 0), atom lines in fixed format (%10.4f%10.4f%10.4f %-3s + zeroed flags), and M END.

13.7. Mol2Writer

Writes a Tripos MOL2 file with @<TRIPOS>MOLECULE, @<TRIPOS>ATOM, and optionally @<TRIPOS>CRYSIN when a cell is available (a, b, c, α, β, γ, space-group number, setting 1). Charges are not written (charge type NO_CHARGES).

13.8. GaussianWriter

Writes a Gaussian input file with a %chk= link, a #p B3LYP/6-31G(d) Opt route, the structure title, a default charge/multiplicity line 0 1, and the Cartesian atom block. ASCII encoding.

13.9. CrystalWriter (.d12)

Writes a CRYSTAL17 geometry + SCF input deck. The writer performs the non-standard-setting check via SpaceGroupTransformer.GetTransformToStandard() and, on user confirmation, transforms a deep copy of the structure (the original in StructureStorage is untouched). The output includes the title line, CRYSTAL, the geometry flag 0 0 0, the space-group number, the cell line, the number of atoms, and one atom line per atom (Z, x, y, z, optional label). The settings block emits OPTGEOM / FULLOPTG / ENDOPT, BASISSET POB-TZVP, DFT B3LYP-D3 XLGRID, SCFDIR, memory sizes, SHRINK 8 8, LEVSHIFT 6 1.0, and TOLINTEG 7 7 7 7 25.

CrystalSpaceGroupValidator.Validate(structure) returns a warning string when the structure is not in the standard setting; otherwise null. The comparison is always done on the normalized H-M name.

13.10. PovRayGenerator

PovRayGenerator(Molecule) produces a complete POV-Ray 3.7 scene file.

Scene structure

• Header: commented metadata (author, date, molecule, atoms, cell, style), POV-Ray version, global_settings { assumed_gamma 2.2; max_trace_level 10 }.
• Camera: position, look-at, up, fixed right, and an angle converted from XNA's vertical FOV to POV-Ray's horizontal angle via angle = degrees(2·atan(tan(vFov/2)·aspect)). The CAMERA_FOV_STRETCH constant (1.0) is applied after conversion.
• Lights: up to two parallel light sources with direction and diffuse intensity taken from Flags; a global ambient is declared as #declare GlobalAmbient.
• Background: a screen-aligned quad placed far behind the scene (quadDist = 500, halfSize = 400) with a vertical gradient between color2 (bottom) and color1 (top). A sky_sphere fallback is used if no camera is available.
• Atoms: style-dependent. CPK spheres scale with the vdW radius / RuntimeIcosphere.BASE_RADIUS. Balls & sticks draw two cylinders per bond (each half colored by its atom). Ellipsoids are drawn as a unit sphere transformed by Transformation · Un · Scale(probability) · Translation(position), with the model scaled by rModel.
• Ellipsoid disks: three thin ellipsoids aligned with the principal axes of the ADP tensor. Disk thickness is constant in Å; the radius scales with the ellipsoid.
• Hydrogen: if ShowHydrogenIsoSpheres is false, H atoms are drawn as small isotropic spheres; otherwise as full ellipsoids.
• Hydrogen bonds: solid or dashed cylinders, colored from Flags.HBondColor; dash/gap lengths are read from flags.
• Unit cell: cylinders along the cell edges, with the edge direction reconstructed from AngleZ and AngleXY and the color saturated by _saturationBoost.
• Polyhedrals: when Presentation == 4, each Polihedrals.VertexesList entry is written as a mesh2 with per-vertex normals, transparent faces, and an inside_vector.
• Crystal planes: visible planes from Molecule.Planes are written as double-sided mesh2 quads (two triangles) with thin cylinder edges. Corners are shifted by −MoleculeShift to align with the atom coordinates.
• Cavities: each rendered cavity with a valid marching-cubes mesh is written as a mesh2. If the draw mode is CavityColorMap and per-vertex colors are available, the mesh uses texture_list and per-face texture indices; otherwise a single transparent pigment is used.
• World transform: the XNA world matrix Scale(cam.OneOverZoom) · Rotate · Translate is emitted once at the end of the union.

Safety guards

• IsValidSegment rejects any cylinder shorter than MIN_SEGMENT_LENGTH = 1e-4 to avoid POV-Ray "degenerate cylinder" errors.
• IsFiniteVector rejects NaN/Inf coordinates.
• Sphere radii smaller than 1e-4 are clamped to 0.01.

Contrast / saturation constants

13.11. SpaceGroupTransformer

Transforms a StructureData from one setting of a space group to another equivalent setting (e.g. P2₁/c ↔ P2₁/n).

Public API

• TransformTo(structure, targetSettingName) — main entry point. Returns a TransformResult with success flag, applied transform, target setting name, and message.
• ApplyTransformToStructure(structure, transform, targetName, wrapAtoms = false) — applies the transform in place: fractional coordinates, ADP tensors (U' = R·U·Rᵀ), cell parameters (M' = M·P), symmetry operations (regenerated for the target setting) and the space-group name.
• ApplyTransform(structure, transform) — low-level version; atoms + ADP + cell only, no symmetry/name update.
• ResolveTransform(structure, targetSettingName) — finds the transform matrix. It first tries a hard-coded lookup and verifies it against the operation sets; if that fails it falls back to a brute-force search over 3×3 integer matrices with determinant ±1 and 27 candidate shifts.
• GetStandardName(group) — returns the standard H-M name for a space group number (first entry with orientation 0).
• GetAvailableSettings(group) — returns all distinct setting names for a group.
• GetCurrentSetting(structure) — returns the setting name currently stored in the structure (matched by normalized name against the internal table).
• GetOperationStringsForSetting(group, settingName) — returns the list of operation strings for a given setting.

Algorithm

1. Resolve the source and target operation sets (ReadSymm) from the internal SymmetryElements table.
2. If the sets are already equivalent, return null (nothing to do).
3. Try a hard-coded transformation; verify it by conjugating the source set and comparing with the target set (3 test points, tolerance 1e-3).
4. If verification fails, brute-force over all integer matrices with determinant ±1 (cached) and a small set of candidate shifts (0, ¼, ½). The first matrix that maps the source set onto the target set is used.
5. Apply the transform to the atoms (optionally wrapping to the unit cell), rotate the ADP tensors, update the cell by M' = M · P where P = Q⁻¹, regenerate the symmetry operations, and set the new name.

Refinement after transform

RefineMoleculePositionsAfterTransform(structure, bonds, maxIterations) performs an iterative relaxation of atoms around their covalent bonds (minimum-image convention), followed by an "attractor" step that pulls smaller connected fragments toward the largest one using integer fractional shifts of up to ±2. Finally, each molecule is translated so that its heaviest non-hydrogen anchor sits near (0.5, 0.5, 0.5) — a whole-molecule translation, not a wrap.

Helper methods: DetectBondsInStructure (minimum-image covalent-bond detection with element-pair thresholds), DetectMoleculesSimple (BFS over bonds), and VerifyRoundTrip (round-trip diagnostic for A→B→A).

13.12. Parsers

The application exposes a set of parsers, each of which populates a data container and then converts to a StructureData:

All parsers call a Clean() method on their container before populating it, and set a completed flag on success.

13.13. CifDivider

CifDivider.Divide(content, filePath) splits a multi-block CIF into a list of CifBlock objects (Name, RawData). It preserves empty lines to keep line numbering intact, scans for lines whose trimmed form starts with data_, and falls back to a single block named after the file when no data_ directive is found.

13.14. RecentFilesManager

Singleton that maintains the recent-files list persisted in %LocalAppData%\Tal\RecentFiles.json. See section 2.2.

13.15. Complex (Tal.Utils)

A lightweight struct Complex (double-precision) used by the powder-diffraction structure-factor calculation. It provides the standard arithmetic operators, Magnitude, MagnitudeSquared, Phase, Conjugate, and a FromPolar factory. The BCL System.Numerics.Complex is intentionally not used to avoid name clashes and to keep the operations minimal.

14. Appendix: Technical Details

14.1. Rendering Pipeline

Tal uses a modern rendering pipeline with the following key stages:

• Geometry Pass: The scene is rendered to a high-resolution off-screen render target (RT). This is where Supersampling Anti-Aliasing (SSAA) takes place. The size of this RT is determined by the Scene Quality settings (e.g., 2x means the RT is twice the width and height of the window).
• Progressive AA Pass: If enabled, the previous frame is blended with the current frame when the camera is stationary. This accumulation of frames acts as a temporal anti-aliasing filter, producing a very clean and smooth final image.
• Sprite Layer Pass: All 2D elements, such as atom labels, measurement annotations, and the color scale legend, are drawn directly onto the high-resolution RT. This ensures that they are perfectly integrated with the 3D scene and benefit from the same anti-aliasing.
• Final Composite Pass: The high-resolution RT is then downsampled and drawn to the screen. This is where the SSAA algorithm performs its final filtering, averaging the sub-pixels to create the final, smooth image.

14.2. Supersampling (SSAA)

Supersampling is the primary method of anti-aliasing in Tal. By rendering the scene at a higher resolution (e.g., 2x, 4x) and then scaling it down, the jagged edges of polygons are smoothed. The SSAASamples flag determines the multiplier. A value of 2 means the scene is rendered at 2x resolution, a value of 4 at 4x, etc. This technique provides excellent image quality, especially for thin features like bonds and ellipsoid disks.

14.3. Progressive Accumulation AA

This technique builds upon SSAA. When the user is not interacting with the scene (i.e., the camera is not moving), the application renders the scene multiple times with a sub-pixel jitter on the camera's projection matrix. The results of these jittered frames are accumulated (averaged) into a single buffer. This effectively multiplies the number of samples per pixel, producing an extremely smooth, high-quality final image. The number of accumulated frames is controlled by the ProgressiveAASamples flag (e.g., 16 frames). This method is perfect for producing publication-quality screenshots.

14.4. Van der Waals Radii and Color Tables

The VdwParameters static class is the single source of truth for all van der Waals radii and the default color palette used in the application. It contains a comprehensive, hardcoded table of radii for elements 1 through 118, along with a default color for each. The Atom Colors (global)... window allows the user to modify the color palette at runtime, and these overrides are stored in the application's settings file (Flags) and applied on startup.

14.5. Settings and Persistence

All application settings, window layouts, and user preferences are managed by the Flags singleton. Key settings are saved to a JSON file on application exit and loaded on startup. This includes window positions, lighting settings, background colors, atom color overrides, and camera parameters. The Flags.Instance.MarkDirty() method is used to flag that settings have changed and need to be saved.

14.6. Camera and POV-Ray FOV Conversion

XNA's Matrix.CreatePerspectiveFieldOfView takes a vertical field of view. POV-Ray's angle parameter is the horizontal angle. The conversion used by PovRayGenerator is:

halfV = radians(fovVertical) / 2
halfH = atan(tan(halfV) * aspect)
angle = degrees(2 * halfH)

The POV-Ray right vector must remain constant (1.0) — POV-Ray scales the image itself from the render resolution (+W/+H), and setting right = aspect would squeeze the image horizontally. The render resolution must therefore have the same aspect ratio as the TAL viewport.

14.7. Powder Diffraction: Cromer–Mann Form Factors

Atomic form factors in StructureFactorCalculator use the 4-Gaussian + constant approximation from International Tables for Crystallography, Vol. C, Table 6.1.1.4:

f0(s) = Σ aᵢ·exp(−bᵢ·s²) + c      (i = 1..4)
s = sinθ / λ

Coefficients are stored as 9-element arrays { a1, b1, a2, b2, a3, b3, a4, b4, c } keyed by atomic number. Elements without tabulated coefficients fall back to a carbon-like default.

14.8. Hydrogen U_iso Recaclulation (SHELX AFIX)

In SHELX RES/INS files, a negative U_iso value on a hydrogen atom encodes an AFIX multiplier: the hydrogen's U_iso is to be derived from its bonded neighbor's equivalent isotropic displacement as

U_iso(H) = |AFIX| · U_eq(neighbor)

ResParser performs a second pass over the parsed atoms. For each hydrogen with afix_multiplier > 0, it finds the nearest non-hydrogen atom within 1.3 Å (minimum-image convention, using the cell's fractional-to-Cartesian matrix), computes U_eq = (U11 + U22 + U33) / 3 for anisotropic neighbors or uses U_iso for isotropic ones, and writes the resulting value into iso. Hydrogens without an AFIX multiplier keep the value given directly by SHELX.

15. Advanced Cavity Analysis (VdW Scaling)

The VdW Scaling analyzer performs a systematic sweep of cavity detection at multiple van der Waals radii. For each scale it collects geometric, electrostatic and channel information, and then derives a set of QSPR descriptors that summarize the structural stability of the framework, its porosity and its potential for host-guest chemistry. This is the tool to reach for when you want to move beyond a single "static" cavity picture and characterize a porous material.

15.1. How to run the analysis

1. Open a crystal structure (CIF, RES, etc.) so that a valid unit cell with symmetry is available.
2. Run one normal cavity detection (Calculate → Cavity Detection) so that a base SDF is computed and cached in CavityDetector.HasBaseSDF. The VdW analysis reuses this base SDF and applies the cheap SDF_new = SDF_base − delta correction for every scale — without a base SDF the analysis cannot run.
3. Invoke the analysis from the GUI (Calculate → VdW Scaling Analysis...) or programmatically via VdWScaleAnalyzer.RunAnalysisAsync(molecule, detector, scales).
4. Optionally provide a custom scale list. If none is given, the default list is used:

   2.00, 1.95, 1.90, 1.85, 1.80, 1.75, 1.70, 1.65, 1.60, 1.55,
   1.50, 1.45, 1.40, 1.35, 1.30, 1.25, 1.20, 1.15, 1.10, 1.05, 1.00

   Larger scales first (aggressive shrinking of the pores), then down to 1.00. This ordering is important for the "collapse scale" descriptor.
5. Watch the progress events (ProgressChanged, StatusChanged) or the status bar. Each scale reports its cavity count and (when available) the largest fitted sphere.
6. When the loop finishes, the analyzer restores the original VdW multiplier and SDF flag state. The VdWAnalysisResults object is stored in VdWScaleAnalyzer.CurrentResults and can be saved as a TXT or HTML report.

15.2. VdWAnalysisResults — data model

The result object is the single source of truth for the report. Its main fields are:

15.3. Per-cavity snapshot (VdWAnalysisResult)

For every (cavity, scale) pair the analyzer stores both geometric and electrostatic data in a single VdWAnalysisResult:

• Geometric: Volume, VolumeError, SurfaceArea, SurfaceAreaError, Sphericity, VolumeToSurfaceRatio, RatioError, TriangleCount, VoxelCount, WallConnections.
• Electrostatic: MeanCharge, ChargeVariance, MeanHydrophobicity, HydrophobicityVariance, MeanZEffective, DipoleMomentX/Y/Z, DipoleMomentMagnitude. The dipole is computed as the charge-weighted first moment of the cavity voxels.
• Channel information: HasChannelsAtThisScale, ChannelDirections. This reflects the channel state at VdW = 1.0 (channels are only analyzed at that scale to keep the runtime manageable).

The most important derived quantity is VolumeToSurfaceRatio (V/S), which behaves like a generalized radius: it grows with the cavity size and shrinks when a cavity becomes rough or fragmented.

15.4. Cavity tracking and critical events

After the sweep, the analyzer builds a CavityTrackData for every cavity ID it saw at least once. The tracking object contains one CavitySnapshot per scale, with the volume/surface/electrostatic data frozen at that point. The DisappearanceScale is the first scale at which the volume drops below EPSILON after having been positive earlier.

CriticalEvent records all interesting transitions:

• Disappearance: a cavity that existed at scale s_i is absent at scale s_i+1.
• ChannelOpen / ChannelClose: the channel state (present vs. not present) changed for a given cavity between two consecutive scales.
• Merge / Split / TopologyChange: reserved for future use.

15.5. QSPR descriptors

Six descriptors summarize the whole sweep:

15.6. Sphere packing analysis (SphereFitAnalyzer)

For each cavity detected at VdW = 1.0 the analyzer builds a SpherePackingResult. The sphere fits themselves are found by SphereFitAnalyzer, which operates entirely on the Cavity object and does not need a graphics device.

Small cavities

If the cavity has fewer than MIN_VOXELS_SMALL = 50 voxels, the analyzer runs a FindSingleMaximum routine: a coarse grid scan (step = min(resX,resY,resZ)/20) locates the maximum of the SDF, then a local refinement over a radius of 2·step voxels finds the true apex. A single SphereFitResult is created with MaxSphereRadius = SDF_max.

Large cavities

For larger cavities the analyzer enumerates all local maxima of the SDF in parallel and then selects a non-overlapping subset:

1. FindLocalMaximaParallel: scan with step = min(resX,resY,resZ)/15, test the 6 face neighbours, and refine each candidate over a 3-voxel cube.
2. Filter: discard every local maximum whose SDF is below MIN_SDF_VALUE_LARGE = 0.5 Å.
3. SelectSpheres: sort by descending SDF; add a candidate to the selected set only if its distance to every already-selected sphere is at least max( (rcand + rsel) · SEPARATION_FACTOR / 10, MIN_DIST_FRAC = 0.05 ) in fractional coordinates. This yields a maximal packing of spheres.
4. Result: one SphereFitResult per selected sphere, with the cavity ID, sphere radius, sphere center, fractional coordinates, wall flag, and distance to the cavity center.

The center used for the Cavity.SphereCenter property is chosen from the non-wall spheres (i.e. spheres whose fractional coordinates are all in [0.01, 0.99]) when possible, and from the overall maximum otherwise.

SpherePackingResult

15.7. Gas compatibility

For every cavity the analyzer cross-checks the fitted spheres against a fixed library of gases. Each gas is a GuestMolecule with a kinetic diameter, polarizability, dipole moment, and a flag IsGas = true. The library includes:

• H₂ (2.9 Å), He (2.6 Å), CH₄ (3.8 Å), CO₂ (4.2 Å), N₂ (3.6 Å), O₂ (3.7 Å), Ar (3.9 Å), NH₃ (4.0 Å).

For each gas the result is a GasGuestResult:

• CanFit: gasRadius ≤ 0.95 · maxSphereRadius.
• VolumeRatio: gasVolume / cavityVolume.
• Score: 0.70 · sizeMatch + 0.30 · polarityMatch, where sizeMatch = 1 − |gasRadius / maxRadius − 0.5|·2 and the polarity match depends on whether a suitable non-wall sphere is available.
• Status: GOOD (score ≥ 0.7), FAIR (score ≥ 0.4), POOR.
• BestSphereLocation: textual reference to the closest-sized sphere (index + fractional coordinates).
• RecommendedCount: floor(usableVolume / gasVolume).
• IsDiffusionLimited: true if the cavity has wall connections but no channel (the gas can enter, but diffusion is restricted).

15.8. Solvent compatibility

The same library (with IsGas = false) is used to score solvents. For each solvent the analyzer builds a SolventGuestResult whose score combines four indicators:

• sizeMatch — how well the solvent radius matches the local sphere radius.
• polarMatch — closeness of the solvent polarizability to a reference value of 0.5.
• chargeMatch — penalizes strongly polar solvents when the cavity is not particularly polar.
• hydroMatch — closeness of the solvent hydrophobicity to zero.

The final score is a weighted sum (0.25 size + 0.15 polar + 0.15 charge + 0.15 hydro + 0.10 shape + 0.10 voxel) and VoxelClusterMatch is a derived 0.5–1.0 confidence that the solvent fits the shape of the cavity's voxel cloud, not just the largest sphere.

15.9. Semi-periodic channels (CavityPathFinder)

Channel analysis is run at VdW = 1.0 for every cavity that touches at least one cell wall (WallConnections > 0). The CavityPathFinder performs a semi-periodic A* search along the three cell axes and stores its results in cavity.CrystalChannelResults.

Path result

Algorithm

1. Setup: the density grid, the periodic grid and the inverse fractional-to-Cartesian matrix are flattened into contiguous arrays. The maximum SDF value inside the cavity volume is recorded for the heuristic.
2. Start points: up to MaxStartPoints = 20 candidates are enumerated in expanding shells around the center of the periodic cell. A candidate is accepted only if the local voxel is not a wall and has at least 2 units of free space in the 6 axis directions. If fewer than 3 candidates are found, random sampling is used as a fallback.
3. A* search: for each start point, two separate A* searches are run — one toward the minimum wall (e.g. x = 0) and one toward the maximum wall (x = nx−1). Each search uses a 26-neighbour stencil and a cost function distance + distance · (1 − SDF / SDF_max) · SDFWeight so that the path prefers to stay near the center of the cavity.
4. Path assembly: the two half-paths are concatenated. Paths with fewer than 3 points are discarded.
5. Measurement: total length, helicity (angle between the first and second half), cell crossings, and the diameter at each of up to 20 sample points. The local diameter is found by casting rays outward from the current voxel until a wall is hit.
6. Smoothing (optional): a Laplacian smoothing pass (iterations controlled by SmoothingIterations, default 3). The RMS displacement is reported as SmoothingError.
7. Statistics: the analyzer aggregates the results of all start points into a ChannelPathStatistics object (min/max/avg length, diameter, helicity). The BestPath is the widest path whose average width exceeds 0.8 Å, or the widest overall if none exceeds the threshold.
8. XNA conversion: WorldPathXna is filled from WorldPath so the renderer can consume it directly.

When the analysis completes, each cavity receives a CrystalChannelResults dictionary keyed by "XX", "YY", "ZZ". The HasCrystalChannels property then returns true and the renderer can draw the channel paths as thick tubes.

15.10. Reports

VdWAnalysisReport.GenerateTxtReport(results) produces a plain-text report; GenerateHtmlReport(results) produces a self-contained dark-theme HTML report; SaveReport(results, path) dispatches to the right one by extension. Both reports are composed of the same sections:

• Header (cell parameters, analysis parameters, summary).
• QSPR descriptors.
• Scale summary (cavity count, total volume/surface, V/S, Vol/Voxels, Vol/Atom, channels per scale).
• Scale dependence (dV/dscale, dS/dscale, ΔV%, ΔS%, V/S).
• Sphere packing (per-cavity table + a detailed sphere list for the largest packing).
• Gas compatibility (the top 5 gases).
• Solvent compatibility (the top 8 solvents, with all four match metrics).
• Electrostatic & hydrophobic summary (mean/variance of charge and hydrophobicity, dipole, surface area, per scale).
• Critical events (disappearance, channel open/close).
• Cavity survival tracking (Volume and Surface at 1.0, 1.1, 1.2, 1.3, 1.4, 1.5).
• Channel analysis (channel summary, statistics per direction, network type: 1D / 2D / 3D).

16. Atom Visibility Manager

The AtomVisibilityManager is a small static helper class in Tal.DrawMethods that centralizes the "show / hide" operations for atoms. It is not bound to any particular tool window; any command that needs to hide or show atoms should go through it so that all the ancillary structures (contacts, hydrogen bonds, etc.) stay consistent.

The class is stateless: it does not cache any data, it just manipulates the Molecule.Atom.show flag and the atomic contact arrays. This follows the same pattern as ShortContactsFinder and HBondFinder.

16.1. Hide operations

16.2. Hanging contacts cleanup

Contacts in Tal are stored twice — once on each of the two atoms that participate in the contact. If one end is later hidden or removed, the other end is left with a dangling reference to an atom that is no longer visible. RemoveHangingContacts(molecule) walks every atom, filters its Contact* arrays, and drops every entry whose target atom is out of range or has show == false. The filtered arrays are:

• ContactDistance
• ContactAtom
• ContactAngleZ
• ContactAngleXY
• PrecomputedContactMatrix
• ContactIsNew

ContactCount is updated to match the new list length. The method returns the total number of contacts removed and writes a single line to the debug log.

16.3. Statistics

• CountVisible(molecule) — number of atoms with show == true.
• CountHidden(molecule) — NumberOfAtoms − CountVisible(molecule).

16.4. Typical workflows

Isolate a single molecule in a packing view:

1. Pick one atom of the target molecule (Pick Atoms mode).
2. Call HideReverseSelected(molecule) first (so that only the picked atom's selection is kept), then HideMolecule(molecule, atomIndex) to hide every copy of that molecule except the selected one.
3. Call RemoveHangingContacts(molecule) to clean up dangling contacts.

Hide all copies of a single symmetry-equivalent atom:

1. Pick one atom.
2. HideSymmetryEquivalent(molecule, atomIndex).

Undo all hides:

1. ShowAll(molecule).