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, and mol_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 to True, uses self.positions. If set to False (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 of self.positions.
  • nlist (tensor) – Defaults to None. Particle-wise neighbor list to use for force calculations. If not specified, uses self.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