schrodinger.application.matsci.network_cg_mapping.periodic module¶

Periodic geometry and graph-topology utilities for network mapping.

All image shifts in this module use the three input-PBC box vectors. Primitive repeat coordinates are introduced later by repeat detection.

schrodinger.application.matsci.network_cg_mapping.periodic.reduce_box(box)¶

Return a Niggli-reduced box and its integer row transformation.

The returned matrix transform satisfies reduced_box == transform @ box. If reduction fails, the original box and identity transformation are returned.

Parameters:: box (numpy.ndarray) – PBC box vectors stored as rows
Return type:: tuple
Returns:: Niggli-reduced box and its integer row transformation

class schrodinger.application.matsci.network_cg_mapping.periodic.PeriodicImageSearch(box)¶

Bases: object

Reusable nearest-image geometry for one periodic box.

Box validation, Niggli reduction, the integer basis transformation, and the reduced-box inverse are computed once. Reusing this object therefore avoids repeating that setup when many displacements are queried against the same PBC.

__init__(box)¶

Prepare image-search geometry for a periodic box.

Parameters:: box (numpy.ndarray) – PBC box vectors stored as rows

wrapPosition(position)¶

Wrap a Cartesian position into the canonical reduced-box image.

The returned image shift is expressed in the input-box basis, even though the canonical image is selected using the reduced box.

Parameters:: position (numpy.ndarray) – Cartesian position to wrap
Raises:: ValueError – if position does not have shape (3,).

nearestImage(displacement, include_zero=True)¶

Return the nearest image shift and Cartesian displacement.

Parameters:

displacement (numpy.ndarray) – Cartesian displacement to move to its nearest image
include_zero (bool) – Whether the zero image shift may be selected

Return type:

tuple

Returns:

Closest input-box image shift and Cartesian displacement

minimumImage(displacement)¶

Return the closest periodic image of a Cartesian displacement.

Parameters:: displacement (numpy.ndarray) – Cartesian displacement to move to its nearest image
Return type:: numpy.ndarray
Returns:: Cartesian displacement to the closest periodic image

bondImageShifts(displacement, include_zero=False, distance_tolerance=0.15)¶

Return the image shifts represented by a stored PBC bond.

More than one shift may be returned when several images are at indistinguishable distances. include_zero also adds the zero shift when the stored atom pair has an ordinary bond.

Parameters:

displacement (numpy.ndarray) – Cartesian displacement from the first stored atom to the second
include_zero (bool) – Whether to include the zero image shift
distance_tolerance (float) – Maximum distance in angstroms above the shortest nonzero image to include

Return type:

tuple

Returns:

Input-box image shifts represented by the stored bond

schrodinger.application.matsci.network_cg_mapping.periodic.vector_rank(vectors, tolerance=1e-06)¶

Return the number of independent Cartesian vector directions.

In repeat detection, vectors typically contains candidate translation vectors. Parallel translations and integer multiples contribute only one direction, while independent translations contribute separate dimensions; for example, a chain, sheet, and 3D crystal have ranks one, two, and three.

Effectively zero vectors are discarded and the remaining vectors are normalized so their lengths do not affect the result. Singular value decomposition then identifies independent directions, with tolerance used to treat numerically negligible singular values as zero.

Parameters:

vectors (collections.abc.Iterable) – Cartesian row vectors, typically candidate translations
tolerance (float) – Relative singular-value threshold

Return type:

int

Returns:

Number of linearly independent vector directions

schrodinger.application.matsci.network_cg_mapping.periodic.lattice_coefficients(vectors, basis)¶

Return row-vector coefficients in an independent basis.

Parameters:

vectors (numpy.ndarray) – Cartesian row vectors to express in basis
basis (numpy.ndarray) – Independent Cartesian basis vectors stored as rows

Return type:

numpy.ndarray

Returns:

Coefficient row for each input vector in basis

schrodinger.application.matsci.network_cg_mapping.periodic.integer_lattice_basis(rows)¶

Return an exact basis for the integer lattice generated by rows.

In periodic-network analysis, rows contains the nonzero input-PBC shifts accumulated around bonded cycles. These winding generators may include opposite directions, multiples, and integer combinations of one another. Hermite normal form removes that redundancy while preserving the exact discrete lattice generated by integer combinations.

The number of returned vectors is the cycle-winding rank. Their integer values are also retained so they can be converted to Cartesian box translations and later expressed in the detected primitive repeat basis. This information is needed for commensurability checks and construction of the repeat supercell matrix; rank alone is insufficient.

Parameters:: rows (collections.abc.Iterable) – Integer row-lattice generators, typically cycle windings in the input PBC basis
Return type:: tuple
Returns:: Exact basis rows for the generated integer lattice

schrodinger.application.matsci.network_cg_mapping.periodic.cycle_windings_and_gauge(network)¶

Return the cycle-winding lattice and a spanning-tree image gauge.

A gauge assigns each stored atom an input-cell image. The difference between the image proposed by an edge and the previously assigned image of its endpoint is a cycle winding. Nonzero windings identify paths that traverse the periodic boundary and return to an equivalent stored atom.

Parameters:: network (AtomicNetwork) – Atomic network to analyze
Return type:: tuple
Returns:: Exact cycle-winding basis and input-image gauge by atom

schrodinger.application.matsci.network_cg_mapping.periodic.gauged_positions(network, gauge)¶

Return atom positions in the input-PBC images selected by a gauge.

Parameters:

network (AtomicNetwork) – Atomic network whose positions should be transformed
gauge (dict) – Input-PBC image assignment for each atom

Return type:

dict

Returns:

Gauge-transformed Cartesian position for each atom

schrodinger.application.matsci.network_cg_mapping.periodic.gauged_edge_shift(edge, gauge)¶

Return an edge shift after applying an atom-image gauge.

Parameters:

edge (AtomicEdge) – Atomic edge to transform
gauge (dict) – Input-PBC image assignment for each atom

Return type:

numpy.ndarray

Returns:

Edge image shift after applying the gauge

schrodinger.application.matsci.network_cg_mapping.periodic.cycle_winding_rank(network)¶

Return the integer rank of the network’s PBC cycle-winding lattice.

Parameters:: network (AtomicNetwork) – Atomic network to analyze
Return type:: int
Returns:: Rank of the PBC cycle-winding lattice

schrodinger.application.matsci.network_cg_mapping.periodic.unwrap_zero_winding_network(network)¶

Convert a zero-winding network to a contiguous, nonperiodic copy.

A zero-winding network may have bonds that cross the input PBC boundary, but those image shifts only describe how a finite structure is split across the stored cell; they do not represent genuine infinite-network connectivity. The image gauge is used to move each atom into a contiguous Cartesian image. All edge shifts are then reset to zero, duplicate edges that differ only by their former image representation are removed, and the periodic box is discarded.

A network with a nonzero cycle winding cannot be represented by a finite unwrapped copy and raises NetworkMappingError.

Parameters:: network (AtomicNetwork) – Atomic network whose finite components should be unwrapped
Return type:: AtomicNetwork
Returns:: Contiguous network with zero edge shifts and no periodic box