|
occ
|
Crystal energy evaluator for rigid molecule assemblies. More...
#include <crystal_energy.h>
Classes | |
| struct | MoleculeCache |
| Cached per-molecule data to avoid redundant recomputation. More... | |
| struct | MoleculeGeometry |
| Cached molecule geometry (atom positions in body frame). More... | |
Public Member Functions | |
| CrystalEnergy (CrystalEnergySetup setup) | |
| Construct crystal energy evaluator. | |
| CrystalEnergy (const crystal::Crystal &crystal, std::vector< MultipoleSource > multipoles, double cutoff_radius=20.0, ForceFieldType ff=ForceFieldType::BuckinghamDE, bool use_cartesian=true, bool use_ewald=true, double ewald_accuracy=1e-6, double ewald_eta=0.0, int ewald_kmax=0, bool defer_setup=false) | |
| Legacy constructor from Crystal + MultipleSources. | |
| ~CrystalEnergy () | |
| Destructor (defined in .cpp for unique_ptr with forward-declared type). | |
| CrystalEnergy (CrystalEnergy &&) noexcept | |
| Move operations (defined in .cpp where EwaldLatticeCache is complete). | |
| CrystalEnergy & | operator= (CrystalEnergy &&) noexcept |
| CrystalEnergyResult | compute (const std::vector< MoleculeState > &molecules) |
| Compute energy and gradient for given molecular states. | |
| CrystalEnergyResultWithHessian | compute_with_hessian (const std::vector< MoleculeState > &molecules) |
| Compute energy, gradient, and Hessian for given molecular states. | |
| bool | can_compute_exact_hessian () const |
| Returns true when compute_with_hessian provides an exact Hessian for the current configured energy model. | |
| double | compute_energy (const std::vector< MoleculeState > &molecules) |
| Compute energy only (faster, for line search). | |
| std::vector< MoleculeState > | initial_states () const |
| Get initial states from crystal geometry. | |
| void | update_lattice (const crystal::Crystal &strained_crystal, std::vector< MoleculeState > new_states) |
| Update the crystal lattice for strained evaluation. | |
| int | num_molecules () const |
| Number of molecules in asymmetric unit. | |
| const std::vector< MoleculeGeometry > & | molecule_geometry () const |
| Access molecule geometry (body-frame atom positions). | |
| const std::vector< NeighborPair > & | neighbor_pairs () const |
| Get neighbor list. | |
| ForceFieldParams & | force_field () |
| Access force field parameters. | |
| const ForceFieldParams & | force_field () const |
| void | set_typed_aniso_params (const std::map< std::pair< int, int >, AnisotropicRepulsionParams > ¶ms) |
| Set/query anisotropic repulsion parameters (typed). | |
| bool | has_aniso_params (int type1, int type2) const |
| AnisotropicRepulsionParams | get_aniso_params (int type1, int type2) const |
| bool | has_any_aniso_params () const |
| void | set_buckingham_params (int Z1, int Z2, const BuckinghamParams ¶ms) |
| Get/set Buckingham parameters for atom pair. | |
| void | set_typed_buckingham_params (int type1, int type2, const BuckinghamParams ¶ms) |
| void | set_typed_buckingham_params (const std::map< std::pair< int, int >, BuckinghamParams > ¶ms) |
| void | clear_typed_buckingham_params () |
| void | set_short_range_type_labels (const std::map< int, std::string > &labels) |
| BuckinghamParams | get_buckingham_params (int Z1, int Z2) const |
| bool | has_buckingham_params (int Z1, int Z2) const |
| bool | uses_williams_atom_typing () const |
| bool | uses_short_range_typing () const |
| bool | has_typed_buckingham_params (int type1, int type2) const |
| BuckinghamParams | get_buckingham_params_for_types (int type1, int type2) const |
| std::string | short_range_type_name (int type_code) const |
| const crystal::Crystal & | crystal () const |
| Get the underlying crystal. | |
| double | cutoff_radius () const |
| void | set_cutoff_radius (double cutoff) |
| void | update_neighbors () |
| Update neighbor list (called if molecules move significantly). | |
| void | update_neighbors (const std::vector< MoleculeState > &states) |
| Update neighbor list using current molecule states. | |
| void | build_neighbor_list_from_positions (const std::vector< Vec3 > &mol_coms, bool force_com_cutoff=false, const std::vector< MoleculeState > *orientation_states=nullptr) |
| Build neighbor list from explicit molecule COM positions. | |
| void | set_neighbor_list (const std::vector< NeighborPair > &neighbors) |
| Set neighbor list directly (e.g. to reuse a list from another CrystalEnergy). | |
| const std::vector< NeighborPair > & | neighbor_list () const |
| Get the neighbor list. | |
| void | set_molecule_geometry (std::vector< MoleculeGeometry > geometry) |
| Set molecule geometry directly (bypasses Crystal's molecule detection). | |
| void | set_initial_states (std::vector< MoleculeState > states) |
| Set initial molecule states directly. | |
| void | set_ewald_dipole (bool enable) |
| Enable/disable dipole Ewald (charge-dipole + dipole-dipole). | |
| bool | use_ewald () const |
| void | set_max_interaction_order (int max_order) |
| Set maximum interaction order for electrostatics (rankA + rankB <= max). | |
| int | max_interaction_order () const |
| void | set_elec_site_cutoff (double cutoff) |
| Set per-site cutoff for electrostatic interactions (Angstrom). | |
| double | elec_site_cutoff () const |
| void | set_use_com_elec_gate (bool enable) |
| Enable COM-based gate for electrostatic interactions. | |
| bool | use_com_elec_gate () const |
| void | set_buckingham_site_cutoff (double cutoff) |
| Set a separate per-site cutoff for Buckingham (default: same as neighbor cutoff). | |
| double | buckingham_site_cutoff () const |
| void | set_electrostatic_taper (double r_on, double r_off, int order=3) |
| Set DMACRYS-style electrostatic spline taper. | |
| void | clear_electrostatic_taper () |
| const CutoffSpline & | electrostatic_taper () const |
| void | set_electrostatic_taper_in_hessian (bool enable) |
| When false, the electrostatic taper is applied to energy and gradient but NOT to the pair Hessian. | |
| bool | electrostatic_taper_in_hessian () const |
| void | set_short_range_taper (double r_on, double r_off, int order=3) |
| Set DMACRYS-style short-range spline taper. | |
| void | clear_short_range_taper () |
| const CutoffSpline & | short_range_taper () const |
| std::vector< std::vector< bool > > | compute_buckingham_site_masks (const std::vector< MoleculeState > &states) const |
| Compute which atom-atom pairs are within the Buckingham cutoff for each neighbor pair at the given molecular states. | |
| void | set_fixed_site_masks (std::vector< std::vector< bool > > masks) |
| Set frozen site-pair masks. | |
| void | clear_fixed_site_masks () |
| Clear frozen site-pair masks (revert to distance-based cutoff). | |
| int | max_multipole_rank () const |
| Get maximum multipole rank across all sites. | |
| size_t | num_neighbor_pairs () const |
| Get number of neighbor pairs. | |
| std::vector< PairEnergyDebug > | debug_pair_energies (const std::vector< MoleculeState > &molecules) |
| Compute per-pair debug breakdown at current states. | |
| std::vector< int > | neighbor_shell_histogram () const |
| Neighbor shell histogram for quick sanity checks. | |
| size_t | num_sites () const |
| Get total number of multipole sites. | |
Static Public Member Functions | |
| static const char * | short_range_type_label (int type_code) |
| Convert a Williams/NEIGHCRYS type code to a short label (e.g. 512 -> C_W3). | |
| static int | short_range_type_atomic_number (int type_code) |
| Map a Williams/NEIGHCRYS type code to element Z, or 0 if unknown. | |
| static std::map< std::pair< int, int >, BuckinghamParams > | williams_de_params () |
| Williams DE Buckingham parameters (built-in). | |
Crystal energy evaluator for rigid molecule assemblies.
Computes electrostatic energy using multipole interactions and short-range repulsion-dispersion using Buckingham or LJ potentials.
Usage:
|
explicit |
Construct crystal energy evaluator.
| crystal | Crystal structure (provides geometry and symmetry) |
| multipoles | Body-frame multipoles for each symmetry-unique molecule |
| cutoff_radius | Neighbor cutoff in Angstrom (default 20.0) |
| ff | Force field for short-range (default BuckinghamDE) |
| use_cartesian | Use Cartesian T-tensor engine (default true) Construct from explicit molecule data. No Crystal molecule assembly. This is the preferred constructor. |
| occ::mults::CrystalEnergy::CrystalEnergy | ( | const crystal::Crystal & | crystal, |
| std::vector< MultipoleSource > | multipoles, | ||
| double | cutoff_radius = 20.0, |
||
| ForceFieldType | ff = ForceFieldType::BuckinghamDE, |
||
| bool | use_cartesian = true, |
||
| bool | use_ewald = true, |
||
| double | ewald_accuracy = 1e-6, |
||
| double | ewald_eta = 0.0, |
||
| int | ewald_kmax = 0, |
||
| bool | defer_setup = false |
||
| ) |
Legacy constructor from Crystal + MultipleSources.
| occ::mults::CrystalEnergy::~CrystalEnergy | ( | ) |
Destructor (defined in .cpp for unique_ptr with forward-declared type).
|
noexcept |
Move operations (defined in .cpp where EwaldLatticeCache is complete).
|
inline |
| void occ::mults::CrystalEnergy::build_neighbor_list_from_positions | ( | const std::vector< Vec3 > & | mol_coms, |
| bool | force_com_cutoff = false, |
||
| const std::vector< MoleculeState > * | orientation_states = nullptr |
||
| ) |
Build neighbor list from explicit molecule COM positions.
Bypasses Crystal's molecule detection (useful when loading external data). When force_com_cutoff=true, uses COM distance for the molecule pair gate even when atom geometry is available (matches DMACRYS TBLCNT behavior).
| bool occ::mults::CrystalEnergy::can_compute_exact_hessian | ( | ) | const |
Returns true when compute_with_hessian provides an exact Hessian for the current configured energy model.
|
inline |
|
inline |
Clear frozen site-pair masks (revert to distance-based cutoff).
|
inline |
|
inline |
| CrystalEnergyResult occ::mults::CrystalEnergy::compute | ( | const std::vector< MoleculeState > & | molecules | ) |
Compute energy and gradient for given molecular states.
| std::vector< std::vector< bool > > occ::mults::CrystalEnergy::compute_buckingham_site_masks | ( | const std::vector< MoleculeState > & | states | ) | const |
Compute which atom-atom pairs are within the Buckingham cutoff for each neighbor pair at the given molecular states.
Returns a per-neighbor-pair boolean mask (row-major, nA*nB) indicating inclusion.
| double occ::mults::CrystalEnergy::compute_energy | ( | const std::vector< MoleculeState > & | molecules | ) |
Compute energy only (faster, for line search).
| CrystalEnergyResultWithHessian occ::mults::CrystalEnergy::compute_with_hessian | ( | const std::vector< MoleculeState > & | molecules | ) |
Compute energy, gradient, and Hessian for given molecular states.
Hessian is assembled analytically from pair terms (short-range full rigid-body and full Cartesian multipole electrostatics). Ewald site-position Hessian terms are included when enabled; exactness for the full model is reported by exact_for_model.
|
inline |
Get the underlying crystal.
|
inline |
| std::vector< PairEnergyDebug > occ::mults::CrystalEnergy::debug_pair_energies | ( | const std::vector< MoleculeState > & | molecules | ) |
Compute per-pair debug breakdown at current states.
|
inline |
|
inline |
|
inline |
|
inline |
Access force field parameters.
|
inline |
|
inline |
|
inline |
|
inline |
|
inline |
|
inline |
|
inline |
|
inline |
| std::vector< MoleculeState > occ::mults::CrystalEnergy::initial_states | ( | ) | const |
Get initial states from crystal geometry.
|
inline |
| int occ::mults::CrystalEnergy::max_multipole_rank | ( | ) | const |
Get maximum multipole rank across all sites.
|
inline |
Access molecule geometry (body-frame atom positions).
|
inline |
Get the neighbor list.
|
inline |
Get neighbor list.
| std::vector< int > occ::mults::CrystalEnergy::neighbor_shell_histogram | ( | ) | const |
Neighbor shell histogram for quick sanity checks.
|
inline |
Number of molecules in asymmetric unit.
|
inline |
Get number of neighbor pairs.
| size_t occ::mults::CrystalEnergy::num_sites | ( | ) | const |
Get total number of multipole sites.
|
noexcept |
|
inline |
Get/set Buckingham parameters for atom pair.
|
inline |
Set a separate per-site cutoff for Buckingham (default: same as neighbor cutoff).
Use a larger value than the neighbor cutoff to reduce derivative discontinuities near the neighbor boundary.
| void occ::mults::CrystalEnergy::set_cutoff_radius | ( | double | cutoff | ) |
|
inline |
Set per-site cutoff for electrostatic interactions (Angstrom).
Default 0.0 means no per-site cutoff (all site pairs within included molecule pairs are computed). DMACRYS applies RANG2 per-site cutoff in its PAIR module for higher multipole terms.
| void occ::mults::CrystalEnergy::set_electrostatic_taper | ( | double | r_on, |
| double | r_off, | ||
| int | order = 3 |
||
| ) |
Set DMACRYS-style electrostatic spline taper.
f=1 for r<=r_on, spline to 0 over (r_on,r_off], zero beyond r_off. Order must be 3 (cubic) or 5 (quintic).
|
inline |
When false, the electrostatic taper is applied to energy and gradient but NOT to the pair Hessian.
This matches DMACRYS behaviour where the multipole SEC array does not include spline chain-rule terms.
|
inline |
Enable/disable dipole Ewald (charge-dipole + dipole-dipole).
Default is true (DMACRYS computes Ewald for qq, qμ, and μμ).
|
inline |
Set frozen site-pair masks.
When non-empty, compute_short_range_pair uses only the atom pairs marked true, bypassing the distance cutoff. This ensures a smoother energy surface under cell/molecular perturbations.
| void occ::mults::CrystalEnergy::set_initial_states | ( | std::vector< MoleculeState > | states | ) |
Set initial molecule states directly.
|
inline |
Set maximum interaction order for electrostatics (rankA + rankB <= max).
Default -1 means no truncation (compute all orders up to 2*max_rank). Set to 4 to match DMACRYS truncation.
| void occ::mults::CrystalEnergy::set_molecule_geometry | ( | std::vector< MoleculeGeometry > | geometry | ) |
Set molecule geometry directly (bypasses Crystal's molecule detection).
| void occ::mults::CrystalEnergy::set_neighbor_list | ( | const std::vector< NeighborPair > & | neighbors | ) |
Set neighbor list directly (e.g. to reuse a list from another CrystalEnergy).
| void occ::mults::CrystalEnergy::set_short_range_taper | ( | double | r_on, |
| double | r_off, | ||
| int | order = 3 |
||
| ) |
Set DMACRYS-style short-range spline taper.
|
inline |
|
inline |
Set/query anisotropic repulsion parameters (typed).
|
inline |
|
inline |
|
inline |
Enable COM-based gate for electrostatic interactions.
When enabled, only molecule pairs with COM distance <= cutoff_radius contribute to electrostatics (matching DMACRYS TBLCNT behavior). Buckingham is unaffected — uses full atom-based neighbor list. Default is true for DMACRYS compatibility.
|
inline |
|
inlinestatic |
Map a Williams/NEIGHCRYS type code to element Z, or 0 if unknown.
|
inlinestatic |
Convert a Williams/NEIGHCRYS type code to a short label (e.g. 512 -> C_W3).
|
inline |
| void occ::mults::CrystalEnergy::update_lattice | ( | const crystal::Crystal & | strained_crystal, |
| std::vector< MoleculeState > | new_states | ||
| ) |
Update the crystal lattice for strained evaluation.
Keeps: neighbors, force field, geometry (body-frame), multipoles. Updates: crystal (for cell translations + Ewald), initial states.
| void occ::mults::CrystalEnergy::update_neighbors | ( | ) |
Update neighbor list (called if molecules move significantly).
| void occ::mults::CrystalEnergy::update_neighbors | ( | const std::vector< MoleculeState > & | states | ) |
Update neighbor list using current molecule states.
For explicit neighbor mode (all UC molecules), this rebuilds the list from current COM positions and orientations.
|
inline |
|
inline |
|
inline |
|
inline |
|
inlinestatic |
Williams DE Buckingham parameters (built-in).