0
# Local Descriptors
1

2
Local descriptors compute features for individual atoms or local atomic environments, producing per-atom feature vectors. These descriptors are ideal for machine learning tasks where atomic-level properties need to be predicted or where local chemical environments are the focus of analysis.
3

4
## Capabilities
5

6
### SOAP (Smooth Overlap of Atomic Positions)
7

8
SOAP creates descriptors based on the local atomic environment using spherical harmonics expansion. It captures both radial and angular information about neighboring atoms within a cutoff radius.
9

10
```python { .api }
11
class SOAP:
12
    def __init__(self, r_cut, n_max, l_max, sigma=1.0, rbf="gto", 
13
                 weighting=None, average="off", compression={"mode": "off", "species_weighting": None}, 
14
                 species=None, periodic=False, sparse=False, dtype="float64"):
15
        """
16
        Initialize SOAP descriptor.
17
        
18
        Parameters:
19
        - r_cut (float): Cutoff radius in angstroms for the local environment
20
        - n_max (int): Number of radial basis functions
21
        - l_max (int): Maximum degree of spherical harmonics
22
        - sigma (float): Width of atomic Gaussians for broadening
23
        - rbf (str): Radial basis functions ("gto" for Gaussian-type orbitals or "polynomial")
24
        - weighting (dict): Weighting function configuration for neighbor contributions
25
        - average (str): Averaging mode ("off", "inner", "outer")
26
        - compression (dict): Compression settings for reducing dimensionality
27
        - species (list): List of atomic species to include
28
        - periodic (bool): Whether to consider periodic boundary conditions
29
        - sparse (bool): Whether to return sparse arrays
30
        - dtype (str): Data type for arrays
31
        """
32

33
    def create(self, system, centers=None, n_jobs=1, only_physical_cores=False, verbose=False):
34
        """
35
        Create SOAP descriptor for given system(s).
36
        
37
        Parameters:
38
        - system: ASE Atoms object(s) or DScribe System object(s)
39
        - centers (list): Indices of atoms to compute SOAP for. If None, compute for all atoms
40
        - n_jobs (int): Number of parallel processes
41
        - only_physical_cores (bool): Whether to use only physical CPU cores
42
        - verbose (bool): Whether to print progress information
43
        
44
        Returns:
45
        numpy.ndarray or scipy.sparse matrix: SOAP descriptors
46
        """
47

48
    def derivatives(self, system, centers=None, include=None, exclude=None, 
49
                   method="auto", return_descriptor=False, n_jobs=1, only_physical_cores=False):
50
        """
51
        Calculate derivatives of SOAP descriptor with respect to atomic positions.
52
        
53
        Parameters:
54
        - system: ASE Atoms object(s) or DScribe System object(s)  
55
        - centers (list): Indices of atoms to compute derivatives for
56
        - include (list): Atomic indices to include in derivative calculation
57
        - exclude (list): Atomic indices to exclude from derivative calculation
58
        - method (str): Derivative calculation method ("auto", "analytical", "numerical")
59
        - return_descriptor (bool): Whether to also return the descriptor values
60
        - n_jobs (int): Number of parallel processes
61
        - only_physical_cores (bool): Whether to use only physical CPU cores
62
        
63
        Returns:
64
        numpy.ndarray or tuple: Derivatives array, optionally with descriptor values
65
        """
66

67
    def get_number_of_features(self):
68
        """Get total number of features in SOAP descriptor."""
69
```
70

71
**Usage Example:**
72

73
```python
74
from dscribe.descriptors import SOAP
75
from ase.build import molecule
76

77
# Setup SOAP descriptor
78
soap = SOAP(
79
    species=["H", "O"],
80
    r_cut=5.0,
81
    n_max=8,
82
    l_max=6,
83
    sigma=0.2
84
)
85

86
# Create descriptor for water molecule
87
water = molecule("H2O")
88
soap_desc = soap.create(water)  # Shape: (n_atoms, n_features)
89

90
# Calculate derivatives
91
derivatives = soap.derivatives(water, return_descriptor=False)
92
```
93

94
### ACSF (Atom-Centered Symmetry Functions)
95

96
ACSF uses Behler-Parrinello symmetry functions to create rotationally and translationally invariant descriptors based on local atomic environments. Different symmetry function types (G2, G3, G4, G5) capture radial and angular information.
97

98
```python { .api }
99
class ACSF:
100
    def __init__(self, r_cut, g2_params=None, g3_params=None, g4_params=None, g5_params=None,
101
                 species=None, periodic=False, sparse=False, dtype="float64"):
102
        """
103
        Initialize ACSF descriptor.
104
        
105
        Parameters:
106
        - r_cut (float): Cutoff radius for all symmetry functions
107
        - g2_params (list): Parameters for G2 (radial) symmetry functions as [eta, Rs] pairs
108
        - g3_params (list): Parameters for G3 (angular) symmetry functions as kappa values
109
        - g4_params (list): Parameters for G4 (angular) symmetry functions as [eta, zeta, lambda] triplets
110
        - g5_params (list): Parameters for G5 (angular) symmetry functions as [eta, zeta, lambda] triplets
111
        - species (list): List of atomic species to include
112
        - periodic (bool): Whether to consider periodic boundary conditions
113
        - sparse (bool): Whether to return sparse arrays
114
        - dtype (str): Data type for arrays
115
        """
116

117
    def create(self, system, centers=None, n_jobs=1, only_physical_cores=False, verbose=False):
118
        """
119
        Create ACSF descriptor for given system(s).
120
        
121
        Parameters:
122
        - system: ASE Atoms object(s) or DScribe System object(s)
123
        - centers (list): Indices of atoms to compute ACSF for. If None, compute for all atoms
124
        - n_jobs (int): Number of parallel processes
125
        - only_physical_cores (bool): Whether to use only physical CPU cores
126
        - verbose (bool): Whether to print progress information
127
        
128
        Returns:
129
        numpy.ndarray or scipy.sparse matrix: ACSF descriptors
130
        """
131

132
    def derivatives(self, system, centers=None, include=None, exclude=None,
133
                   method="auto", return_descriptor=False, n_jobs=1, only_physical_cores=False):
134
        """
135
        Calculate derivatives of ACSF descriptor with respect to atomic positions.
136
        
137
        Parameters:
138
        - system: ASE Atoms object(s) or DScribe System object(s)
139
        - centers (list): Indices of atoms to compute derivatives for
140
        - include (list): Atomic indices to include in derivative calculation
141
        - exclude (list): Atomic indices to exclude from derivative calculation
142
        - method (str): Derivative calculation method ("auto", "analytical", "numerical")
143
        - return_descriptor (bool): Whether to also return the descriptor values
144
        - n_jobs (int): Number of parallel processes
145
        - only_physical_cores (bool): Whether to use only physical CPU cores
146
        
147
        Returns:
148
        numpy.ndarray or tuple: Derivatives array, optionally with descriptor values
149
        """
150

151
    def get_number_of_features(self):
152
        """Get total number of features in ACSF descriptor."""
153
```
154

155
**Usage Example:**
156

157
```python
158
from dscribe.descriptors import ACSF
159
from ase.build import molecule
160

161
# Setup ACSF descriptor with different symmetry function parameters
162
acsf = ACSF(
163
    species=["H", "O"],
164
    r_cut=6.0,
165
    g2_params=[[1, 1], [1, 2]],  # G2 parameters: [eta, Rs]
166
    g4_params=[[1, 1, 1], [1, -1, 4]]  # G4 parameters: [eta, zeta, lambda]
167
)
168

169
# Create descriptor for water molecule
170
water = molecule("H2O")
171
acsf_desc = acsf.create(water)  # Shape: (n_atoms, n_features)
172
```
173

174
### LMBTR (Local Many-Body Tensor Representation)
175

176
LMBTR is the local version of MBTR, computing many-body interaction terms for individual atomic environments. It provides detailed information about local chemical environments through k-body terms.
177

178
```python { .api }
179
class LMBTR:
180
    def __init__(self, geometry=None, grid=None, weighting=None, normalize_gaussians=True,
181
                 normalization="none", species=None, periodic=False, sparse=False, dtype="float64"):
182
        """
183
        Initialize LMBTR descriptor.
184
        
185
        Parameters:
186
        - geometry (dict): Geometry functions for k1, k2, k3 terms
187
        - grid (dict): Discretization grids for each geometry function
188
        - weighting (dict): Weighting functions for neighbor contributions
189
        - normalize_gaussians (bool): Whether to normalize Gaussian broadening
190
        - normalization (str): Normalization scheme ("none", "l2", "n_atoms")
191
        - species (list): List of atomic species to include
192
        - periodic (bool): Whether to consider periodic boundary conditions
193
        - sparse (bool): Whether to return sparse arrays
194
        - dtype (str): Data type for arrays
195
        """
196

197
    def create(self, system, centers=None, n_jobs=1, only_physical_cores=False, verbose=False):
198
        """
199
        Create LMBTR descriptor for given system(s).
200
        
201
        Parameters:
202
        - system: ASE Atoms object(s) or DScribe System object(s)
203
        - centers (list): Indices of atoms to compute LMBTR for. If None, compute for all atoms
204
        - n_jobs (int): Number of parallel processes
205
        - only_physical_cores (bool): Whether to use only physical CPU cores
206
        - verbose (bool): Whether to print progress information
207
        
208
        Returns:
209
        numpy.ndarray or scipy.sparse matrix: LMBTR descriptors
210
        """
211

212
    def derivatives(self, system, centers=None, include=None, exclude=None,
213
                   method="auto", return_descriptor=False, n_jobs=1, only_physical_cores=False):
214
        """
215
        Calculate derivatives of LMBTR descriptor with respect to atomic positions.
216
        
217
        Parameters:
218
        - system: ASE Atoms object(s) or DScribe System object(s)
219
        - centers (list): Indices of atoms to compute derivatives for
220
        - include (list): Atomic indices to include in derivative calculation
221
        - exclude (list): Atomic indices to exclude from derivative calculation
222
        - method (str): Derivative calculation method ("auto", "analytical", "numerical")
223
        - return_descriptor (bool): Whether to also return the descriptor values
224
        - n_jobs (int): Number of parallel processes
225
        - only_physical_cores (bool): Whether to use only physical CPU cores
226
        
227
        Returns:
228
        numpy.ndarray or tuple: Derivatives array, optionally with descriptor values
229
        """
230

231
    def get_number_of_features(self):
232
        """Get total number of features in LMBTR descriptor."""
233
```
234

235
**Usage Example:**
236

237
```python
238
from dscribe.descriptors import LMBTR
239
from ase.build import molecule
240

241
# Setup LMBTR descriptor
242
lmbtr = LMBTR(
243
    species=["H", "O"],
244
    geometry={
245
        "k2": {
246
            "function": "inverse_distance",
247
        },
248
        "k3": {
249
            "function": "angle",
250
        }
251
    },
252
    grid={
253
        "k2": {
254
            "min": 0.5,
255
            "max": 2.0,
256
            "n": 50,
257
            "sigma": 0.05
258
        },
259
        "k3": {
260
            "min": 0,
261
            "max": 180,
262
            "n": 50,
263
            "sigma": 5
264
        }
265
    }
266
)
267

268
# Create descriptor for water molecule
269
water = molecule("H2O")
270
lmbtr_desc = lmbtr.create(water)  # Shape: (n_atoms, n_features)
271
```
272

273
## Common Local Descriptor Features
274

275
All local descriptors share these characteristics:
276

277
- **Per-atom output**: Each descriptor returns features for individual atoms
278
- **Center specification**: Can compute features for specific atoms using the `centers` parameter
279
- **Parallel processing**: Support parallel computation across multiple systems
280
- **Derivative support**: All local descriptors support analytical or numerical derivatives
281
- **Averaging options**: Some descriptors (like SOAP) support different averaging schemes
282

283
## Output Shapes
284

285
Local descriptors return arrays with shape:
286
- Single system: `(n_centers, n_features)` where n_centers is the number of atoms processed
287
- Multiple systems: `(total_centers, n_features)` where total_centers is the sum across all systems
288

289
When `centers` is specified, only those atomic indices are processed, reducing the output size.