molsysmt.pbc package#

Submodules#

molsysmt.pbc.get_angles_from_box module#

molsysmt.pbc.get_angles_from_box.get_angles_from_box(box, skip_digestion=False)[source]#

Extracting box angles from a box matrix.

Parameters:

  • box (quantity) – Box matrix (single or array), shape (3, 3) or (n, 3, 3).

  • skip_digestion (bool, default False) – Whether to skip argument digestion.

Returns:

  • quantity – Angles (alpha, beta, gamma) in radians.

  • .. versionadded:: 1.0.0

molsysmt.pbc.get_box_from_lengths_and_angles module#

molsysmt.pbc.get_box_from_lengths_and_angles.get_box_from_lengths_and_angles(box_lengths, box_angles, skip_digestion=False)[source]#

Building a box matrix from lengths and angles.

Parameters:

  • box_lengths (quantity) – Box edge lengths (a, b, c) with units.

  • box_angles (quantity) – Box angles (alpha, beta, gamma) with units.

  • skip_digestion (bool, default False) – Whether to skip argument digestion.

Returns:

  • quantity – Box matrix of shape (3, 3) with the same length units as the input.

  • .. versionadded:: 1.0.0

molsysmt.pbc.get_box_with_shape module#

molsysmt.pbc.get_box_with_shape.get_box_with_shape(shape='cubic', length='1 nm', n_structures=1, skip_digestion=False)[source]#

Constructing a box matrix for a given shape.

Parameters:

  • shape ({'cubic', 'truncated octahedral', 'rhombic dodecahedral'}, default 'cubic') – Desired box shape.

  • length (quantity, default '1 nm') – Edge length (or characteristic length) with units.

  • n_structures (int, default 1) – Number of structures (frames) to generate.

  • skip_digestion (bool, default False) – Whether to skip argument digestion.

Returns:

  • quantity – Box array of shape (n_structures, 3, 3) in the specified length units.

  • .. versionadded:: 1.0.0

molsysmt.pbc.get_lengths_and_angles_from_box module#

molsysmt.pbc.get_lengths_and_angles_from_box.get_lengths_and_angles_from_box(box, skip_digestion=False)[source]#

Return box lengths and angles from a 3x3 box matrix or an array of boxes.

Parameters:

box (array-like) – A single box with shape (3, 3) or an array of boxes with shape (n, 3, 3). Vectors correspond to the three box edges: v0, v1, v2.

Returns:

  • lengths, angles –

    • lengths: |v0|, |v1|, |v2| in the same units as the input (often labeled as a, b, c in other libraries/software).

    • angles: (alpha, beta, gamma) in radians where:

      alpha = angle between v1 and v2, beta = angle between v0 and v2, gamma = angle between v0 and v1.

      This matches the conventional nomenclature (alpha between b and c, beta between a and c, gamma between a and b).

  • .. versionadded:: 1.0.0

molsysmt.pbc.get_lengths_from_box module#

molsysmt.pbc.get_lengths_from_box.get_lengths_from_box(box, skip_digestion=False)[source]#

Extracting box edge lengths from a box matrix.

Parameters:

  • box (quantity) – Box matrix (single or array), shape (3, 3) or (n, 3, 3).

  • skip_digestion (bool, default False) – Whether to skip argument digestion.

Returns:

  • quantity – Edge lengths (a, b, c) in the same units as the input.

  • .. versionadded:: 1.0.0

molsysmt.pbc.get_shape_from_angles module#

molsysmt.pbc.get_shape_from_angles.get_shape_from_angles(box_angles, skip_digestion=False)[source]#

Determining box shape from its angles.

Parameters:

  • box_angles (quantity) – Angles (alpha, beta, gamma) with units.

  • skip_digestion (bool, default False) – Whether to skip argument digestion.

Returns:

  • str – Box shape label inferred from the angles.

  • .. versionadded:: 1.0.0

molsysmt.pbc.get_shape_from_box module#

molsysmt.pbc.get_shape_from_box.get_shape_from_box(box, skip_digestion=False)[source]#

Inferring the box shape from its matrix.

Parameters:

  • box (quantity) – Box matrix (single or array), shape (3, 3) or (n, 3, 3).

  • skip_digestion (bool, default False) – Whether to skip argument digestion.

Returns:

  • str or None – Shape label inferred from the box angles, or None if no box.

  • .. versionadded:: 1.0.0

molsysmt.pbc.get_volume_from_box module#

molsysmt.pbc.get_volume_from_box.get_volume_from_box(box)[source]#

Computing box volume from a box matrix.

Parameters:

box (quantity or None) – Box matrix (single or array), shape (3, 3) or (n, 3, 3).

Returns:

  • quantity or None – Volume in cubic length units, or None if no box.

  • .. versionadded:: 1.0.0

molsysmt.pbc.get_volume_from_lengths_and_angles module#

molsysmt.pbc.get_volume_from_lengths_and_angles.get_volume_from_lengths_and_angles(box_lengths, box_angles)[source]#

Computing box volume from lengths and angles.

Parameters:

  • box_lengths (quantity) – Edge lengths (a, b, c).

  • box_angles (quantity) – Angles (alpha, beta, gamma).

Returns:

  • quantity – Volume in cubic length units.

  • .. versionadded:: 1.0.0

molsysmt.pbc.has_pbc module#

molsysmt.pbc.has_pbc.has_pbc(molecular_system, skip_digestion=False)[source]#

Check whether a molecular system has periodic boundary conditions (box).

Parameters:

  • molecular_system (molecular system) – System to inspect.

  • skip_digestion (bool, default False) – Whether to skip argument digestion.

Returns:

  • bool – True if the system has a box defined; otherwise False.

  • .. versionadded:: 1.0.0

molsysmt.pbc.unwrap module#

molsysmt.pbc.unwrap.unwrap(molecular_system, selection='all', structure_indices='all', syntax='MolSysMT', engine='MolSysMT', in_place=False, skip_digestion=False)[source]#

Unwrapping coordinates across periodic boundaries to produce continuous trajectories.

Parameters:

  • molecular_system (molecular system) – Input system.

  • selection (str, list, tuple or numpy.ndarray, default 'all') – Atoms to unwrap.

  • structure_indices ('all' or array-like, default 'all') – Structures/frames to process.

  • syntax (str, default 'MolSysMT') – Selection syntax when using strings.

  • engine ({'MolSysMT'}, default 'MolSysMT') – Backend.

  • in_place (bool, default False) – If True, modify the input system; otherwise return an unwrapped copy.

  • skip_digestion (bool, default False) – Whether to skip argument digestion.

Returns:

Unwrapped system when in_place=False, otherwise None.

Return type:

molecular system or None

Raises:

molsysmt.pbc.wrap_to_mic module#

molsysmt.pbc.wrap_to_mic.wrap_to_mic(molecular_system, selection='all', structure_indices='all', mic_origin='[0,0,0] nanometers', center_of_selection=None, center_coordinates='[0,0,0] nanometers', weights=None, keep_covalent_bonds=False, syntax='MolSysMT', engine='MolSysMT', in_place=False, skip_digestion=False)[source]#

Wrap coordinates into the minimum image convention (MIC) box.

Parameters:

  • molecular_system (molecular system) – Input system.

  • selection (str, list, tuple or numpy.ndarray, default 'all') – Atoms to wrap.

  • structure_indices ('all' or array-like, default 'all') – Structures/frames to process.

  • mic_origin (quantity, default '[0,0,0] nanometers') – Origin of the MIC box.

  • center_of_selection (str or array-like, optional) – Selection to center before wrapping (uses center_coordinates).

  • center_coordinates (quantity, default '[0,0,0] nanometers') – Target coordinates for centering the center_of_selection.

  • weights (array-like, optional) – Weights for centering when center_of_selection is given.

  • keep_covalent_bonds (bool, default False) – Placeholder (not implemented) to preserve covalent connectivity across PBC.

  • syntax (str, default 'MolSysMT') – Selection syntax for string selections.

  • engine ({'MolSysMT'}, default 'MolSysMT') – Backend.

  • in_place (bool, default False) – If True, modify the input system; otherwise return a wrapped copy.

  • skip_digestion (bool, default False) – Whether to skip argument digestion.

Returns:

Wrapped system when in_place=False, otherwise None.

Return type:

molecular system or None

Raises:

molsysmt.pbc.wrap_to_pbc module#

molsysmt.pbc.wrap_to_pbc.wrap_to_pbc(molecular_system, selection='all', structure_indices='all', box_origin='[0,0,0] nanometers', box_center=None, center_of_selection=None, weights=None, center_coordinates='[0,0,0] nanometers', keep_covalent_bonds=False, syntax='MolSysMT', engine='MolSysMT', in_place=False, skip_digestion=False)[source]#

Wrap coordinates into the primary periodic box.

Parameters:

  • molecular_system (molecular system) – Input system.

  • selection (str, list, tuple or numpy.ndarray, default 'all') – Atoms to wrap.

  • structure_indices ('all' or array-like, default 'all') – Structures/frames to process.

  • box_origin (quantity, default '[0,0,0] nanometers') – Origin of the periodic box.

  • box_center (quantity, optional) – Center of the box; if provided, uses center-based wrapping.

  • center_of_selection (str or array-like, optional) – Selection to center before wrapping (uses center_coordinates).

  • weights (array-like, optional) – Weights for centering when center_of_selection is given.

  • center_coordinates (quantity, default '[0,0,0] nanometers') – Target coordinates for centering the center_of_selection.

  • keep_covalent_bonds (bool, default False) – Placeholder (not implemented) to preserve covalent connectivity across PBC.

  • syntax (str, default 'MolSysMT') – Selection syntax for string selections.

  • engine ({'MolSysMT'}, default 'MolSysMT') – Backend.

  • in_place (bool, default False) – If True, modify the input system; otherwise return a wrapped copy.

  • skip_digestion (bool, default False) – Whether to skip argument digestion.

Returns:

Wrapped system when in_place=False, otherwise None.

Return type:

molecular system or None

Raises:

Module contents#