graph_builder¶
Details
-
class
graphbuilder.
graph_builder
(nneighbor_cutoff, output_forces=True, check_nlist=False)¶ Build the TensorFlow graph that will be used during the HOOMD run.
Parameters: - nneighbor_cutoff (int) – The maximum number of neigbhors to consider (can be 0)
- output_forces (bool) – True if your graph will compute forces to be used in TensorFlow
- check_nlist (bool) – True will raise error if neighbor list overflows (nneighbor_cutoff too low)
-
build_mol_rep
(MN)¶ This creates
mol_forces
,mol_positions
, andmol_nlist
which have dimensions mol_number x MN x 4 (mol_forces
,mol_positions
) and ? x MN x NN x 4 (mol_nlist
) tensors batched by molecule, where MN is the number of molecules. MN is determined at run time. The MN must be chosen to be large enough to encompass all molecules. If your molecule is 6 atoms and you chose MN=18, then the extra entries will be zeros. Note that your input should be 0 based, but subsequent tensorflow data will be 1 based, since 0 means no atom. The specification of what is a molecule will be passed at runtime, so that it can be dynamic if desired.To convert a mol_quantity to a per-particle quantity, call
scatter_mol_quanitity(mol_quantity)
Parameters: MN (int) – The number of molecules Returns: None
-
compute_forces
(energy, virial=None, positions=False, nlist=None)¶ Computes pairwise or position-dependent forces (field) given a potential energy function that computes per-particle or overall energy
Parameters: - energy (tensor) – The potential energy
- virial (bool) – Defaults to
None
. Virial contribution will be computed if the graph outputs forces. Can be set manually instead. Note that the virial term that depends on positions is not computed. - positions (tensor) – Defaults to
False
. Particle positions tensor to use for force calculations. If set toTrue
, usesself.positions
. If set toFalse
(default), no position dependent forces will be computed. Only pairwise forces from neighbor list will be applied. If set to a tensor, that tensor will be used instead ofself.positions
. - nlist (tensor) – Defaults to
None
. Particle-wise neighbor list to use for force calculations. If not specified, usesself.nlist
.
Returns: The TF force tensor. Note that the virial part will be stored as the class attribute
virial
and will be saved automatically.
-
compute_rdf
(r_range, name, nbins=100, type_i=None, type_j=None, nlist=None, positions=None)¶ - Computes the pairwise radial distribution function, and appends
- the histogram tensor to the graph’s
out_nodes
.
Parameters: - bins – The bins to use for the RDF
- name – The name of the tensor containing rdf. The name will be concatenated with ‘-r’ to create a tensor containing the r values of the rdf.
- type_i – Use this to select the first particle type.
- type_j – Use this to select the second particle type.
- nlist – Neighbor list to use for RDF calculation. By default
it will use
self.nlist
. - positions – Defaults to
self.positions
. This tensor is only used to get the origin particle’s type. So if you’re making your own, just make sure column 4 has the type index.
Returns: Historgram tensor of the RDF (not normalized).
-
masked_nlist
(type_i=None, type_j=None, nlist=None, type_tensor=None)¶ Returns a neighbor list masked by the given particle type(s).
Parameters: - type_i – Use this to select the first particle type.
- type_j – Use this to select a second particle type (optional).
- nlist – Neighbor list to mask. By default it will use
self.nlist
. - type_tensor – An N x 1 tensor containing the type(s) of the nlist origin.
If None, particle types from
self.positions
will be used.
Returns: The masked neighbor list tensor.
-
nlist_rinv
¶ Returns an N x NN tensor of 1 / r for each neighbor
-
running_mean
(tensor, name, batch_reduction='mean')¶ Computes running mean of the given tensor
Parameters: - tensor (tensor) – The tensor for which you’re computing running mean
- name (str) – The name of the variable in which the running mean will be stored
- batch_reduction (str) – If the hoomd data is batched by atom index, how should the component tensor values be reduced? Options are ‘mean’ and ‘sum’. A sum means that tensor values are summed across the batch and then a mean is taking between batches. This makes sense for looking at a system property like pressure. A mean gives a mean across the batch. This would make sense for a per-particle property.
Returns: A variable containing the running mean
-
static
safe_div
(numerator, denominator, delta=3e-06, **kwargs)¶ Use this method to avoid nan forces if doing 1/r or equivalent force calculations. There are some numerical instabilities that can occur during learning when gradients are propagated. The delta is problem specific.
Parameters: - numerator (tensor) – The numerator.
- denominator (tensor) – The denominator.
- delta – Tolerance for magnitude that triggers safe division.
Returns: The safe division op (TensorFlow operation)
-
static
safe_norm
(tensor, delta=1e-07, **kwargs)¶ There are some numerical instabilities that can occur during learning when gradients are propagated. The delta is problem specific. NOTE: delta of safe_div must be > sqrt(3) * (safe_norm delta) See this TensorFlow issue <https://github.com/tensorflow/tensorflow/issues/12071>.
Parameters: - tensor – the tensor over which to take the norm
- delta – small value to add so near-zero is treated without too much accuracy loss.
Returns: The safe norm op (TensorFlow operation)
-
save
(model_directory, force_tensor=None, virial=None, out_nodes=None, move_previous=True)¶ Save the graph model to specified directory.
Parameters: - model_directory – Multiple files will be saved, including a dictionary with information specific to hoomd-tf and TF model files.
- force_tensor – The forces that should be sent to hoomd
- virial – The virial which should be sent to hoomd. If None and you called compute_forces, then the virial computed from that function will be saved.
- out_nodes – Any additional TF graph nodes that should be executed. For example, optimizers, printers, etc. Each element of the list can itself be a list where the first element is the node and the second element is the period indicating how often to execute it.
Returns: None
-
save_tensor
(tensor, name, save_period=1)¶ Saves a tensor to a variable
Parameters: - tensor (tensor) – The tensor to save
- name (str) – The name of the variable which will be saved
- save_period (int) – How often to save the variable
Returns: None
-
wrap_vector
(r)¶ Computes the minimum image version of the given vector.
Parameters: r (tensor) – The vector to wrap around the HOOMD box. Returns: The wrapped vector as a TF tensor