seams-core v2.14.0
libyodaLib, the C++ engine of d-SEAMS
Loading...
Searching...
No Matches
local_symmetry.hpp
Go to the documentation of this file.
1#ifndef SEAMS_LOCAL_SYMMETRY_H_
2#define SEAMS_LOCAL_SYMMETRY_H_
3
4#include <mol_sys.hpp>
5#include <shell_hot.hpp>
6
7#include <Eigen/Core>
8#include <string>
9#include <vector>
10
11// Local symmetry of ice, hydrate cages and rings.
12//
13// Matching uses IRA (Gunde, Salles, Hemeryck, Martin-Samos, JCIM 2021,
14// 10.1021/acs.jcim.1c00567) when libira is linked, and a Kabsch-Hungarian
15// search otherwise. Point groups use SOFI (Gunde et al., JCP 2024,
16// 10.1063/5.0215689). Space groups use spglib (Togo, Shinohara, Tanaka,
17// STAM Methods 2024, 10.1080/27660400.2024.2384822) when libsymspg is linked.
18//
19// Copyright (c) d-SEAMS developers
20// SPDX-License-Identifier: MIT
21
22namespace symm {
23
24enum class Kind {
25 iceIh = 0,
26 iceIc = 1,
27 iceIsd = 2,
31 ring5 = 6,
33};
34
35inline constexpr int kTemplateCount = 8;
36
37const char *name(Kind kind);
38
39// Ideal oxygen coordinates, rows are atoms, angstrom. The first row of an
40// ice shell is the central oxygen. Cage and ring templates are centered.
41Eigen::MatrixXd points(Kind kind);
42
43struct Overlay {
44 int status = 1;
46 std::string name;
47 double rmsd = 0;
48 double hausdorff = 0;
49 // R and t take the environment onto the template:
50 // template[i] ≈ R * environment[permutation[i]] + t.
51 Eigen::Matrix3d rotation = Eigen::Matrix3d::Identity();
52 Eigen::Vector3d translation = Eigen::Vector3d::Zero();
53 std::vector<int> permutation;
54 std::string backend;
55};
56
57// One row per template with the same atom count, lowest RMSD first.
58// backend is "ira", "kabsch", or nullptr for whichever is linked.
59std::vector<Overlay> score(const Eigen::MatrixXd &environment,
60 const char *backend = nullptr);
61Overlay best(const Eigen::MatrixXd &environment, const char *backend = nullptr);
62
63// In-tree matcher (3x3 SVD Kabsch, bond-graph permutations). backend "kernel".
64Overlay matchKernel(const Eigen::MatrixXd &environment);
65
66// Same matcher on many environments. Independent shells run in parallel.
67void matchAll(const std::vector<Eigen::MatrixXd> &environments, std::vector<Overlay> &out);
68
69// A bond is counted eclipsed when its azimuthal cosine exceeds this value.
70// Both bonds are projected onto the plane perpendicular to the central bond.
71// Ideal eclipsed is cos 0 = 1 and ideal staggered is cos 60 degrees = 0.5.
72// The ideal-cell fast path does not use this cosine. It uses the raw dot
73// product of the second-shell bond with another first-shell bond, which is
74// 1/3 staggered and 7/9 eclipsed, and it compares the square of that number.
75// At 220-270 K the staggered azimuthal cosines of mW ice reach about 0.85
76// while the eclipsed bonds stay at 1, so 0.90 is the gap the second-shell
77// template leaves between them. 0.75 counts those warmed staggered bonds
78// as eclipsed.
79inline constexpr double kEclipsedCosine = 0.90;
80
81// Scale-free ceiling on the second-shell residual. Both clouds are centered,
82// then the RMSD is taken after the optimal rotation and the optimal scale
83// and divided by the template's root-mean-square radius (Horn 1987; Larsen,
84// Schmidt, Schiotz 2016). Zero is a perfect shape. 0.12 is the quenched mW
85// operating point. A TIP4P/2005 shell at the melting point still vibrates:
86// raising the ceiling from 0.12 to 0.15 recovers quench-confirmed crystal,
87// and the next step to 0.18 mostly adds atoms that neither PTM nor CHILL+
88// call ice after the same minimisation.
89inline constexpr double kShellRmsd = 0.15;
90
91// Per-atom ice label. kind[i] is iceIh, iceIc, iceIsd, or -1. shellRmsd is
92// the scale-free residual ceiling. The label is the template with the lowest
93// residual after the bond-graph permutation of the tetrahedron.
94// openFace is the second-shell completion for an under-coordinated neighbour.
95void classifyIce(const Eigen::MatrixXd &cartesian, const Eigen::Matrix3d &vectors,
96 std::vector<int> &kind, double shellRmsd = kShellRmsd,
97 double thermalQ = kThermalQ, double bondRatio = kThermalBondRatio,
98 bool openFace = false);
99
100// Column SoA coordinates. The canon shell is built once. kind is written in full.
101void classifyIceArrays(const double *x, const double *y, const double *z, int n, const double lat[3][3],
102 int *kind, double shellRmsd = kShellRmsd, double thermalQ = kThermalQ,
103 double bondRatio = kThermalBondRatio, bool openFace = false);
104
105// Same labels as classifyIceArrays, packed from a point cloud. On ideal
106// cubic ice the codes match diamondFromCsr (0 hexagonal, 1 cubic, -1 other).
108 std::vector<int> &kind, bool openFace = false);
109
110// Azimuthal cosine of each tetrahedral bond, largest first. The value is
111// the best alignment of an outer neighbour with one of the other three
112// bonds. Ideal eclipsed is 1 and ideal staggered is 0.5. Returns how many
113// of the four bonds were measured, or -1 when the environment is not a shell.
114int bondCosines(const Eigen::MatrixXd &environment, double out[4]);
115
116// Bond-graph RMSD of a 17-atom shell against one ice template. Negative
117// when the shell cannot be aligned. This does not consult the eclipsed count,
118// so a hexagonal shell can be scored against the cubic template.
119double iceTemplateRmsd(const Eigen::MatrixXd &environment, Kind kind);
120
121// Alvarez continuous shape measure of environment against its best template.
122// 0 is a perfect match. Scale, rotation and translation are free.
123double shapeMeasure(const Eigen::MatrixXd &environment);
124
125struct Group {
126 int status = 1;
127 std::string symbol;
128 int nOperations = 0;
129};
130
131// status 2 when SOFI is not linked.
132Group pointGroup(const Eigen::MatrixXd &xyz, double symThr = 0.05);
133
134struct Space {
135 int status = 1;
136 int number = 0;
137 std::string symbol;
138};
139
140// `vectors` has the three cell edges as rows. `cartesian` is n x 3.
141// status 2 when spglib is not linked.
142Space spaceGroup(const Eigen::Matrix3d &vectors, const Eigen::MatrixXd &cartesian,
143 double symprec = 1e-3);
144
145// Space group of one conventional cell when every label is the same ideal
146// ice and the box is a cubic integer supercell of that cell. Returns false
147// when the frame is not that crystal; the caller then uses spaceGroup on
148// the whole cell. The international symbol matches the full-cell call.
149bool conventionalCrystalSpace(const Eigen::Matrix3d &vectors,
150 const Eigen::MatrixXd &cartesian,
151 const std::vector<int> &kind, double symprec,
152 Space &out);
153
154enum class Crystal { iceIh, iceIc, fault };
155
156struct Lattice {
157 Eigen::Matrix3d vectors = Eigen::Matrix3d::Identity();
158 Eigen::MatrixXd cartesian;
159};
160
161// Ideal ice Ih (P6_3/mmc), ice Ic (Fd-3m), and an Ih cell with one
162// bilayer shifted onto the cubic stacking site.
164
165// Central oxygen plus its 16 nearest periodic neighbours, when the 16th
166// neighbour lies inside 5 A. Empty when the atom is not in a bulk ice shell.
167Eigen::MatrixXd iceShell(const Eigen::MatrixXd &cartesian,
168 const Eigen::Matrix3d &vectors, int atom);
169
172// "ira" when libira is linked, otherwise "kabsch".
173const char *matcher();
174
175} // namespace symm
176
177#endif
The main molecular system handler.
void matchAll(const std::vector< Eigen::MatrixXd > &environments, std::vector< Overlay > &out)
const char * matcher()
constexpr int kTemplateCount
double shapeMeasure(const Eigen::MatrixXd &environment)
Eigen::MatrixXd points(Kind kind)
constexpr double kThermalQ
Definition shell_hot.hpp:35
Group pointGroup(const Eigen::MatrixXd &xyz, double symThr=0.05)
void classifyIce(const Eigen::MatrixXd &cartesian, const Eigen::Matrix3d &vectors, std::vector< int > &kind, double shellRmsd=kShellRmsd, double thermalQ=kThermalQ, double bondRatio=kThermalBondRatio, bool openFace=false)
void classifyIceArrays(const double *x, const double *y, const double *z, int n, const double lat[3][3], int *kind, double shellRmsd=kShellRmsd, double thermalQ=kThermalQ, double bondRatio=kThermalBondRatio, bool openFace=false)
constexpr double kShellRmsd
double iceTemplateRmsd(const Eigen::MatrixXd &environment, Kind kind)
Space spaceGroup(const Eigen::Matrix3d &vectors, const Eigen::MatrixXd &cartesian, double symprec=1e-3)
constexpr double kThermalBondRatio
Definition shell_hot.hpp:38
Overlay best(const Eigen::MatrixXd &environment, const char *backend=nullptr)
const char * name(Kind kind)
bool spglibLinked()
constexpr double kEclipsedCosine
bool iraLinked()
Lattice crystal(Crystal which)
void classifyIceCloud(const molSys::PointCloud< molSys::Point< double >, double > &yCloud, std::vector< int > &kind, bool openFace=false)
Eigen::MatrixXd iceShell(const Eigen::MatrixXd &cartesian, const Eigen::Matrix3d &vectors, int atom)
int bondCosines(const Eigen::MatrixXd &environment, double out[4])
Overlay matchKernel(const Eigen::MatrixXd &environment)
std::vector< Overlay > score(const Eigen::MatrixXd &environment, const char *backend=nullptr)
bool conventionalCrystalSpace(const Eigen::Matrix3d &vectors, const Eigen::MatrixXd &cartesian, const std::vector< int > &kind, double symprec, Space &out)
This contains a collection of points; contains information for a particular frame.
Definition mol_sys.hpp:173
This contains per-particle information.
Definition mol_sys.hpp:152
std::string symbol
Eigen::Matrix3d vectors
Eigen::MatrixXd cartesian
std::string backend
std::string name
Eigen::Matrix3d rotation
std::vector< int > permutation
Eigen::Vector3d translation
std::string symbol