Skip to content

Commit 0ec0667

Browse files
jmgoffjmgoff
committed
basline docs updated
1 parent 83d625c commit 0ec0667

6 files changed

Lines changed: 194 additions & 98 deletions

File tree

‎mala/descriptors/acelib/ace_potential.py‎

Lines changed: 72 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
11
"""
22
ACE potential class.
33
4-
Computes the coupling coefficients. ACE_DOCS_MISSING: Why is this called
5-
"potential" - would this work as an actual ACE potential or is this just the
6-
expansion coefficients?
4+
It writes a .yace file (ACE potential file) that is readable by LAMMPS. When only the
5+
coupling coefficients are saved to the .yace file, this acts as a parameter
6+
file with which one can evaluate ACE descriptors.
77
"""
88

99
import itertools
@@ -16,49 +16,70 @@
1616

1717
class ACEPotential:
1818
"""
19-
Class for calculation of ACE coupling coefficients.
20-
21-
ACE_DOCS_MISSING: Explain scope of class. I think we always assume PA
22-
basis, but I don't know what that is.
23-
19+
Class to manage interface between ACE descriptor enumeration library and
20+
LAMMPS. By default, it will enumerate ACE descriptors according to the
21+
Permutation-adapted approach described in https://doi.org/10.1016/j.jcp.2024.113073.
22+
However, there are options for assigning descriptor labels if desired, manually
23+
for example.
24+
25+
After enumerating descriptors, it assigns all relevant hyperparamters needed
26+
to evaluate the ACE descriptors in LAMMPS. It saves a .yace file needed to
27+
evaluate ACE descriptors in LAMMPS (containing coupling coefficients). It does this
28+
by writing an ACE potential file, readable by LAMNMPS, that contains only
29+
information to evaluate descriptors, not energy models.
30+
2431
Parameters
2532
----------
2633
elements : List
27-
List of elements (symbols)
34+
List of elements (symbols), including 'G' for the grid points. In ACE, all possible
35+
combinations of these elements determine the "bond types" spanned by the ACE chemical
36+
basis (the chemical basis is the delta function basis used in Drautz 2019). For
37+
example, the "bond types" resulting from all possible combinations of ['Al','G'] are
38+
determined with :code:`itertools.product()` in python. They are (Al,Al)(Al,G)(G,Al)(G,G).
39+
For mala, only those of type (G,X) are kept, (grid-atom interactions) and only a placeholder
40+
is kept for other interaction types.
2841
2942
reference_ens : List
30-
List of floats, has same dimensions as elements. ACE_DOCS_MISSING:
31-
What does it do?
43+
List of reference energies. (To be applied only for linear models) with a constant
44+
shift to the energy per element type. Values other than 0 not be necessary in MALA.
3245
3346
ranks : List
34-
ACE_DOCS_MISSING
47+
Orders of the expansion, referred to as `N` in Drautz 2019, of the
48+
descriptors to be enumerated
3549
3650
nmax: List
37-
ACE_DOCS_MISSING
51+
Maximum radial basis function index per descriptor rank
3852
3953
lmax: List
40-
ACE_DOCS_MISSING
54+
Maximum angular momentum number per descriptor rank (maximum angular function index)
4155
4256
nradbase : int
43-
ACE_DOCS_MISSING
57+
Maximum radial basis function index OVERALL: max(nmax) - in the future, may be used
58+
to define the number of g_k(r) comprising R_nl from Drautz 2019 radial basis.
4459
45-
rcut : float
46-
ACE_DOCS_MISSING
60+
rcut : float/list
61+
radial basis function cutoff per bond type. For example, if elements are ['Al','G']
62+
then rcut must be supplied for each:(Al,Al)(Al,G)(G,Al)(G,G)
4763
48-
lmbda : float
49-
ACE_DOCS_MISSING
64+
lmbda : float/list
65+
Exponential factor for scaled distance in Drautz 2019 used in the radial basis
66+
functions. As with the radial cutoff, lambda must be supplied per bond type. For
67+
example, if elements are ['Al','G'] then lambda must be supplied for
68+
each:(Al,Al)(Al,G)(G,Al)(G,G)
5069
5170
css : dict
52-
ACE_DOCS_MISSING
71+
Dictionary of coupling coefficients of the format: {rank:{l:{m:coupling_coefficient}}
5372
5473
rcutinner : List
55-
ACE_DOCS_MISSING
74+
Inner cutoff to turn on soft-core repulsions. This parameter should be 0.0 (OFF) for
75+
each bond type in MALA.
5676
5777
drcutinner : List
58-
ACE_DOCS_MISSING
78+
Parameter for soft-core repulsions. This parameter should not matter if rcutinner is
79+
0.0 (OFF) for each bond type in MALA.
5980
60-
lmin : int
61-
ACE_DOCS_MISSING
81+
lmin : int/list
82+
lower bound on angular momentum quantum number per rank.
6283
6384
manual_labels : str
6485
File for loading labels. If not None, then labels will be loaded from
@@ -89,15 +110,22 @@ def __init__(
89110
if kwargs is not None:
90111
self.__dict__.update(kwargs)
91112

92-
# ACE_DOCS_MISSING: Explain what all these variables do, at least
93-
# briefly, and give them more meaningful names.
113+
#NOTE Our unused variable names here match exactly what is in LAMMPS
114+
# I'm hesitant to change these to something else. We wont use them in MALA
115+
# and if people are really interested, they can find them in the lammps
116+
# source code directly
117+
#coupling coefficients (generalized Wigner symbols or Generalized Clebsch-Gordan coefficients)
94118
self.__global_ccs = css
95119
self.__global_ccs[1] = {"0": {tuple([]): {"0": 1.0}}}
120+
#0th-order expansion term in ACE (e.g., constant energy shift)
96121
self.__E0 = reference_energy
97122
self.__ranks = ranks
98123
self.__elements = elements
124+
#linear model coefficients
99125
self.__betas = None
126+
#descriptor labels in FitSNAP/LAMMPS format - as described elsewhere
100127
self.__nus = None
128+
#hyperparameters for ACE basis (relevant for density embeddings)
101129
self.__deltaSplineBins = 0.001
102130
self.__global_ndensity = 1
103131
self.__global_rhocut = 100000
@@ -203,17 +231,17 @@ def __init__(
203231

204232
def __set_embeddings(self, npoti="FinnisSinclair", FSparams=[1.0, 1.0]):
205233
"""
206-
Set embeddings.
207-
208-
ACE_DOCS_MISSING
234+
Set 'embeddings' in the .yace file for lammps. Some terms here control
235+
if a square-root embedding term is added. This should always be OFF
236+
for descriptor calculations in MALA
209237
210238
Parameters
211239
----------
212240
npoti : str
213-
ACE_DOCS_MISSING
241+
paramter to specify descriptor type in LAMMPS
214242
215243
FSparams : List
216-
ACE_DOCS_MISSING
244+
parameters to specify embedding terms in LAMMPS
217245
"""
218246
# embeddings =dict()#OrderedDict() #{ind:None for ind in range(len(self.elements))}
219247
embeddings = {ind: None for ind in range(len(self.__elements))}
@@ -235,9 +263,13 @@ def __set_bonds(self):
235263

236264
def __set_bond_base(self):
237265
"""
238-
Set bond base.
266+
Set the per-bond radial basis parameters. The 'bonds' are determined based
267+
on the elements. If the elements are ['Al','G'], the bonds may be
268+
determined with :code:`itertools.product()` in python. They are
269+
(Al,Al)(Al,G)(G,Al)(G,G). Some hyperparameters must be specified per bond
270+
label shown here.
239271
240-
ACE_DOCS_MISSING - what does that mean, what does this function do?
272+
241273
"""
242274
bondstrs = ["[%d, %d]" % (b[0], b[1]) for b in self.__bondlsts]
243275
bonds = {bondstr: None for bondstr in bondstrs}
@@ -320,17 +352,19 @@ def __set_bond_base(self):
320352

321353
def set_funcs(self, nulst=None, print_0s=True):
322354
"""
323-
Set functions.
324-
325-
ACE_DOCS_MISSING - what does this function do?
355+
Set ctilde 'functions' in the .yace file, used to calculate
356+
descriptors in lammps
326357
327358
Parameters
328359
----------
329360
nulst : List
330-
List of nus ACE_DOCS_MISSING - what are those?
361+
List of nus, a.k.a. ACE descriptor labels to write to
362+
the .yace file.
331363
332364
print_0s : bool
333-
ACE_DOCS_MISSING - what does this do?
365+
Logical to include 0-valued descriptors, this should always
366+
be True in MALA as 0-valued descriptors only arise after
367+
training linear models with sparsifying solvers like LASSO
334368
"""
335369
if nulst is None:
336370
if self.__nus is not None:

‎mala/descriptors/acelib/clebsch_gordan_coupling.py‎

Lines changed: 51 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -8,32 +8,36 @@ def clebsch_gordan_coupling(
88
clebsch_gordan_coefficients, ldict, L_R=0, use_permutations=True
99
):
1010
"""
11-
Compute Clebsch-Gordan couplings for a given L_R.
11+
Compute generalized Clebsch-Gordan coefficients for a given L_R.
12+
These are all defined according to the pairwise coupling scheme
13+
in Goff et al. 2024.
1214
13-
ACE_DOCS_MISSING: Clarify what this means, and also maybe the name,
14-
because I am not so sure about it (see ace.py).
15+
The approach to construct generalized Clebsch-Gordan coefficients is
16+
manually defined for each rank for pedagogical and clarity purposes.
1517
1618
Parameters
1719
----------
1820
clebsch_gordan_coefficients : dict
1921
Precomputed Clebsch-Gordan coefficients.
2022
2123
ldict : dict
22-
Dictionary of ranks and their corresponding L values.
24+
Dictionary of ranks and their corresponding l values.
2325
2426
L_R : int
25-
ACE_DOCS_MISSING
27+
Resultant angular momentum quantum number. This determines the equivariant
28+
character of the rank N descriptor after reduction. L_R=0 corresponds to
29+
a rotationally invariant feature, L_R=1 corresponds to a feature that
30+
transforms like a vector, L_R=2 a tensor, etc.
2631
2732
use_permutations : bool
28-
ACE_DOCS_MISSING
33+
Flag to consider permutations of l in generation of coupling coefficients.
2934
3035
Returns
3136
-------
3237
coupling : dict
33-
Clebsch-Gordan couplings.
38+
Generalized Clebsch-Gordan coefficients, {M_R:{rank:{l:{m:coupling_coefficient}}}
3439
"""
3540
# Define the functions for the individual ranks.
36-
# ACE_DOCS_MISSING Maybe we can briefly summarize what the differences
3741
# between the functions for the individual ranks are.
3842

3943
def _rank_1_tree(_clebsch_gordan_coefficients, _l, _L_R=0, _M_R=0):
@@ -46,18 +50,23 @@ def _rank_1_tree(_clebsch_gordan_coefficients, _l, _L_R=0, _M_R=0):
4650
Precomputed Clebsch-Gordan coefficients.
4751
4852
_l : List
49-
ACE_DOCS_MISSING
53+
list of angular momentum quantum numbers [l1]
5054
5155
_L_R : int
52-
ACE_DOCS_MISSING
56+
Resultant angular momentum quantum number. This determines the equivariant
57+
character of the rank N descriptor after reduction. L_R=0 corresponds to
58+
a rotationally invariant feature, L_R=1 corresponds to a feature that
59+
transforms like a vector, L_R=2 a tensor, etc.
5360
5461
_M_R : int
55-
ACE_DOCS_MISSING
62+
Resultant projection quantum number. This also determines the equivariant
63+
character of the rank N descriptor after reduction. M_R must obey
64+
-L_R <= M_R <= L_R
5665
5766
Returns
5867
-------
5968
decomposed : dict
60-
Clebsch-Gordan couplings for rank 1.
69+
Generalized Clebsch-Gordan coefficient for rank 1
6170
"""
6271
mstrs = mala.descriptors.acelib.common_utils.get_ms(_l, _M_R)
6372
full_inter_tuples = [()]
@@ -94,18 +103,24 @@ def _rank_2_tree(_clebsch_gordan_coefficients, _l, _L_R=0, _M_R=0):
94103
Precomputed Clebsch-Gordan coefficients.
95104
96105
_l : List
97-
ACE_DOCS_MISSING
106+
list of angular momentum quantum numbers [l1,l2]
98107
99108
_L_R : int
100-
ACE_DOCS_MISSING
109+
Resultant angular momentum quantum number. This determines the equivariant
110+
character of the rank N descriptor after reduction. L_R=0 corresponds to
111+
a rotationally invariant feature, L_R=1 corresponds to a feature that
112+
transforms like a vector, L_R=2 a tensor, etc.
101113
102114
_M_R : int
103-
ACE_DOCS_MISSING
115+
Resultant projection quantum number. This also determines the equivariant
116+
character of the rank N descriptor after reduction. M_R must obey
117+
-L_R <= M_R <= L_R
104118
105119
Returns
106120
-------
107121
decomposed : dict
108-
Clebsch-Gordan couplings for rank 2.
122+
Generalized Clebsch-Gordan coefficients for rank 2
123+
109124
"""
110125
nodes, remainder = ace_coupling_utils.build_quick_tree(_l)
111126
node = nodes[0]
@@ -147,18 +162,23 @@ def _rank_3_tree(_clebsch_gordan_coefficients, _l, _L_R=0, _M_R=0):
147162
Precomputed Clebsch-Gordan coefficients.
148163
149164
_l : List
150-
ACE_DOCS_MISSING
165+
list of angular momentum quantum numbers [l1,l2,l3]
151166
152167
_L_R : int
153-
ACE_DOCS_MISSING
168+
Resultant angular momentum quantum number. This determines the equivariant
169+
character of the rank N descriptor after reduction. L_R=0 corresponds to
170+
a rotationally invariant feature, L_R=1 corresponds to a feature that
171+
transforms like a vector, L_R=2 a tensor, etc.
154172
155173
_M_R : int
156-
ACE_DOCS_MISSING
174+
Resultant projection quantum number. This also determines the equivariant
175+
character of the rank N descriptor after reduction. M_R must obey
176+
-L_R <= M_R <= L_R
157177
158178
Returns
159179
-------
160180
decomposed : dict
161-
Clebsch-Gordan couplings for rank 3.
181+
Generalized Clebsch-Gordan coefficients for rank 3
162182
"""
163183
full_inter_tuples = ace_coupling_utils.build_tree_for_l_intermediates(
164184
_l, L_R=_L_R
@@ -203,18 +223,23 @@ def _rank_4_tree(_clebsch_gordan_coefficients, _l, _L_R=0, _M_R=0):
203223
Precomputed Clebsch-Gordan coefficients.
204224
205225
_l : List
206-
ACE_DOCS_MISSING
226+
list of angular momentum quantum numbers [l1,l2,l3,l4]
207227
208228
_L_R : int
209-
ACE_DOCS_MISSING
229+
Resultant angular momentum quantum number. This determines the equivariant
230+
character of the rank N descriptor after reduction. L_R=0 corresponds to
231+
a rotationally invariant feature, L_R=1 corresponds to a feature that
232+
transforms like a vector, L_R=2 a tensor, etc.
210233
211234
_M_R : int
212-
ACE_DOCS_MISSING
235+
Resultant projection quantum number. This also determines the equivariant
236+
character of the rank N descriptor after reduction. M_R must obey
237+
-L_R <= M_R <= L_R
213238
214239
Returns
215240
-------
216241
decomposed : dict
217-
Clebsch-Gordan couplings for rank 4.
242+
Generalized Clebsch-Gordan coefficients for rank 4
218243
"""
219244
nodes, remainder = ace_coupling_utils.build_quick_tree(_l)
220245
mstrs = mala.descriptors.acelib.common_utils.get_ms(_l, _M_R)
@@ -266,6 +291,8 @@ def _rank_4_tree(_clebsch_gordan_coefficients, _l, _L_R=0, _M_R=0):
266291
ranks = list(ldict.keys())
267292
coupling = {M_R: {rank: {} for rank in ranks} for M_R in M_Rs}
268293

294+
#NOTE higher-rank couplings (to enable higher rank descriptors)
295+
# are available in FitSNAP
269296
for M_R in M_Rs:
270297
for rank in ranks:
271298
rnk = rank

‎mala/descriptors/acelib/common_utils.py‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,9 @@
88

99
def filled_perm(tuples, rank):
1010
"""
11-
Returns the sympy permutation from permutations of N tabulated from GAP
11+
Returns a sympy Permutation object for permutations tabulated from GAP. This function
12+
uses `rank` to fill in missing permutation indices from GAP. For example tuples = [(0,1)],
13+
rank=4 would yeild Permutation(3)(0,1) corresponding to the cycles (0,1)(2)(3)
1214
1315
Parameters
1416
----------

‎mala/descriptors/acelib/coupling_utils.py‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -227,7 +227,8 @@ def generate_l_LR(lrng, rank, L_R=0, M_R=0, use_permutations=False):
227227
these will be (0,1,2...lmax)
228228
229229
rank : int
230-
body order of angular ace descriptor labels to be generated
230+
order of the expansion, referred to as `N` in Drautz 2019, of the
231+
descriptors to be enumerated
231232
232233
L_R : int
233234
Resultant angular momentum quantum number. This determines the equivariant
@@ -494,7 +495,7 @@ def compute_pa_labels_raw(rank, nmax, lmax, mumax, lmin=1, L_R=0, M_R=0):
494495
maximum radial basis function index for the given descriptor rank
495496
496497
lmax : any
497-
maximum angular momentum number for the given descriptor rank
498+
maximum angular momentum number for the given descriptor rank (maximum angular function index)
498499
499500
mumax : any
500501
maximum chemical basis index for the given rank (should generally be

0 commit comments

Comments
 (0)