Shared parts of networks
This page documents the shared layers in different networks, along with the convention about data structure.
Convention
Sparse indices
Since atomistic data comes in irregular shapes, PiNN uses sparse data structure
for data batching, and the construction of pairwise, triplet-wise tensors. All
these tensors are associated with indices named as ind_*
, with shapes ind_1:
[n_atoms, 1]
, ind_2: [n_pairs, 2]
, etc. The meanings of indices are:
- For
ind_1
:[i-th_struct_in_batch]
; - For
ind_2
:[i-th_atom_in_batch, j-th_atom_in_batch]
; - For
ind_3
:[i-th_pair_in_batch, j-th_pair_in_batch]
, with shared central atom; - ...
Using sparse indices
To construct a pairwise variable from atom-centered ones, use the
tf.gather_nd
operator, for instance the following operation broadcasts the
atom-centered \(\mathbb{P}_{i\alpha}\) variable to each pair of atoms
(\(\mathbb{I}_{ij\alpha}=\mathbf{1}_{ij}\mathbb{P}_{i\alpha}\)).
I = tf.gather_nd(P, ind_2[:, 0]) + tf.gather_nd(P, ind_2[:, 1])
To accumulate pairwise predictions over neighbors (\(\mathbb{P}_{i\alpha} =
\sum_{j} \mathbb{I}_{ij\alpha}\)), use the tf.scatter_nd
operation:
P = tf.scatter_nd(ind_2[:, :1], I, shape=[n_atoms, n_alpha])
or tf.math.unsorted_segment_sum
:
P = tf.math.unsorted_segment_sum(I, ind_2[:, 0], natoms)
Note that the number of atoms must be supplied since it cannot be inferred from
ind_2
, it can be inferred from a per-atom tensor instead, e.g.:
n_atoms = tf.shape(P)[0]
Neighbor list
CellListNL
Bases: Layer
Compute neighbour list with cell lists approach, see https://en.wikipedia.org/wiki/Cell_lists.
Source code in pinn/layers/nl.py
53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 |
|
__init__(rc=5.0)
Parameters:
Name | Type | Description | Default |
---|---|---|---|
rc
|
float
|
cutoff radius |
5.0
|
Source code in pinn/layers/nl.py
58 59 60 61 62 63 64 |
|
call(tensors)
The layer expects a dictionary of tensors from a sparse_batch with keys:
ind_1
: sparse indices of atoms in batch, with shape(n_atoms, 2)
coord
: atomic coordinate, with shape(n_atoms, 3)
cell
(optional): cell vectors with shape(n_batch,3,3)
It output a dictionary
ind_2
: sparse indices of neighbor list, with shape(n_pairs, 2)
diff
: displacement vectors, with shape(n_pairs, 3)
dist
: pairwise distances, with shape(n_pairs)
Parameters:
Name | Type | Description | Default |
---|---|---|---|
tensors
|
dict of tensor
|
input tensors, with keys: |
required |
Returns:
Name | Type | Description |
---|---|---|
output |
dict of tensor
|
output tensors, with keys: {"ind_2", "diff", "dist"}` |
Source code in pinn/layers/nl.py
66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 |
|
Basis functions
CutoffFunc
Bases: Layer
Cutoff function layer
The following types of cutoff function are implemented (all functions are defined within \(r_{ij}<r_{c}\) and decay to zero at \(r_{c}\)):
- \(f^1(r_{ij}) = 0.5 (\mathrm{cos}(\pi r_{ij}/r_{c})+1)\)
- \(f^2(r_{ij}) = \mathrm{tanh}^3(1- r_{ij}/r_{c})/\mathrm{tanh}^3(1)\)
- \(hip(r_{ij}) = \mathrm{cos}^2(\pi r_{ij}/2r_{c})\)
Source code in pinn/layers/basis.py
9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 |
|
__init__(rc=5.0, cutoff_type='f1')
Parameters:
Name | Type | Description | Default |
---|---|---|---|
rc
|
float
|
cutoff radius |
5.0
|
cutoff_type
|
string
|
name of the cutoff function |
'f1'
|
Source code in pinn/layers/basis.py
21 22 23 24 25 26 27 28 29 30 31 32 33 |
|
call(dist)
Parameters:
Name | Type | Description | Default |
---|---|---|---|
dist
|
tensor
|
distance tensor with arbitrary shape |
required |
Returns:
Name | Type | Description |
---|---|---|
fc |
tensor
|
cutoff function with the same shape as the input |
Source code in pinn/layers/basis.py
35 36 37 38 39 40 41 42 43 |
|
GaussianBasis
Bases: Layer
Gaussian Basis Layer
Builds the Gaussian basis function:
Both the Gaussian centers \(r_{b}\) and width \(\eta_{b}\) can be arrays that
specifies the parameter for each basis function. When \(\eta\) is given as a
single float, the same value is assigned to every basis. When center is not
given, n_basis
and rc
are used to generat a linearly spaced set of
basis.
Source code in pinn/layers/basis.py
46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 |
|
__init__(center=None, gamma=None, rc=None, n_basis=None)
Parameters:
Name | Type | Description | Default |
---|---|---|---|
center
|
float | array
|
Gaussian centers |
None
|
gamma
|
float | array
|
inverse Gaussian width |
None
|
rc
|
float
|
cutoff radius |
None
|
n_basis
|
int
|
number of basis function |
None
|
Source code in pinn/layers/basis.py
64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 |
|
call(dist, fc=None)
Parameters:
Name | Type | Description | Default |
---|---|---|---|
dist
|
tensor
|
distance tensor with shape (n_pairs) |
required |
fc
|
tensor
|
when supplied, apply a cutoff function to the basis |
None
|
Returns:
Name | Type | Description |
---|---|---|
basis |
tensor
|
basis functions with shape (n_pairs, n_basis) |
Source code in pinn/layers/basis.py
80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 |
|
PolynomialBasis
Bases: Layer
Polynomial Basis Layer
Builds the polynomial basis function:
, where \(n_b\) is specified by n_basis
. n_basis
can be a list that
explicitly specifies polynomail orders, or an integer that specifies a the
orders as [0, 1, ..., n_basis-1]
.
Source code in pinn/layers/basis.py
101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 |
|
__init__(n_basis)
Parameters:
Name | Type | Description | Default |
---|---|---|---|
n_basis
|
int | list
|
number of basis function |
required |
Source code in pinn/layers/basis.py
116 117 118 119 120 121 122 123 124 125 |
|
call(dist, fc=None)
Parameters:
Name | Type | Description | Default |
---|---|---|---|
dist
|
tensor
|
distance tensor with shape (n_pairs) |
required |
fc
|
tensor
|
when supplied, apply a cutoff function to the basis |
None
|
Returns:
Name | Type | Description |
---|---|---|
basis |
tensor
|
basis functions with shape (n_pairs, n_basis) |
Source code in pinn/layers/basis.py
127 128 129 130 131 132 133 134 135 136 137 138 |
|
Misc
AtomicOneHot
Bases: Layer
One-hot embedding layer
Given the atomic number of each atom (\(Z_{i}\)) and a list of specified element types denoted as (\(Z^{\mathrm{0}}_{\alpha}\)), returns:
Source code in pinn/layers/misc.py
7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 |
|
__init__(atom_types=[1, 6, 7, 8, 9])
Parameters:
Name | Type | Description | Default |
---|---|---|---|
atom_types
|
list of int
|
list of elements (\(Z^{0}\)) |
[1, 6, 7, 8, 9]
|
Source code in pinn/layers/misc.py
15 16 17 18 19 20 21 |
|
call(elems)
Parameters:
Name | Type | Description | Default |
---|---|---|---|
elems
|
tensor
|
atomic indices of atoms, with shape |
required |
Returns:
Name | Type | Description |
---|---|---|
prop |
tensor
|
atomic property tensor, with shape |
Source code in pinn/layers/misc.py
23 24 25 26 27 28 29 30 31 32 33 |
|
ANNOutput
Bases: Layer
ANN Ouput layer
Output atomic or molecular (system) properties depending on out_pool
, where \(\mathrm{pool}\) is a reducing operation specified with out_pool
,
it can be one of 'sum', 'max', 'min', 'avg'.
Source code in pinn/layers/misc.py
35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 |
|
call(tensors)
Parameters:
Name | Type | Description | Default |
---|---|---|---|
tensors
|
list of tensor
|
ind_1 and output tensors |
required |
Returns:
Name | Type | Description |
---|---|---|
output |
tensor
|
atomic or per-structure predictions |
Source code in pinn/layers/misc.py
55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 |
|