Periodicity

plot3d.periodicity.__periodicity_check__(face1: Face, face2: Face, block1: Block, block2: Block, tol: float = 1e-06)[source]

General function to find periodicity within a given block.

Steps:

  • 1: Take the face with the shorter diagonal.

  • 2: Rotate the shorter face by angle 360/nblades.

  • 3: Check to see if faces intersect

Parameters:

  • face1 (Face) – An arbitrary face

  • face2 (Face) – An arbitrary face

  • block1 (Block) – block 1 cooresponding to face 1

  • block2 (Block) – block 2 cooresponding to face 2

Returns:

containing

  • df (pandas.Dataframe): List of point matches for periodic surfaces

  • periodic_surface (List[Face]): These are faces that are periodic

  • split_surfaces (List[Face]): Some blocks may have periodic faces with other blocks. But the faces may need to be split so say you pair a small face with a larger face. The split surfaces should be treated as an outer face

Return type:

(tuple)

plot3d.periodicity.create_rotation_matrix(rotation_angle: float, rotation_axis: str = 'x')[source]

Creates a rotation matrix given an angle and axis

Parameters:

  • rotation_angle (float) – Rotation angle in radians

  • rotation_axis (str, optional) – Axis of rotation “x”, “y”, or “z”. Defaults to “x”.

Returns:

3x3 rotation matrix

Return type:

np.ndarray

plot3d.periodicity.linear_real_transform(face1: Face, face2: Face) → Tuple[source]
Computes the rotation angle from Face1 to Face2. This can be used to check if the faces are periodic

This function assumes the rotation axis is in the “x” direction. This is good for faces within the same block

Reference:
Parameters:

  • Face1 (Face) – Face to rotate

  • Face2 (Face) – Face to rotate to

Returns:

tuple containing:

  • ang (float): rotation angle

  • rotation_matrix (numpy.ndarray): Rotation matrix 3x3

Return type:

(tuple)

plot3d.periodicity.periodicity(blocks: List[Block], outer_faces: List[Dict[str, int]], matched_faces: List[Dict[str, int]], periodic_direction: str = 'k', rotation_axis: str = 'x', nblades: int = 55)[source]
This function is used to check for periodicity of the other faces rotated about an axis. Use periodicity_fast instead. Periodicity_fast calls this function after reducing the size of the mesh.

The way it works is to find faces of a constant i,j, or k value

Parameters:

  • blocks (List[Block]) – List of blocks that will be scanned for perodicity

  • outer_faces (List[Dict[str,int]]) – List of outer faces for each block as a dictionary format. You can get this from connectivity

  • matched_faces (ListList[Dict[str,int]]) – List of matched faces from connectivity. Matched faces was added so that it’s always removed from outer faces

  • periodic_direction (str) – either i,j,k to look for

  • rotation_axis (str) – either x,y,z

  • nblades (int) – Number of blades to consider, this affects the rotation angle.

Returns:

containing

  • periodic_faces_export (List[Dict[str,int]]): This is list of all the surfaces/faces that match when rotated by an angle formatted as a dictionary.

  • outer_faces_export (List[Dict[str,int]]): These are the list of outer faces that are not periodic formatted as a dictionary.

  • periodic_faces (List[Tuple[Face,Face]]): - This is a list of Face objects that are connected to each other organized as a list of tuples: [Face1, Face2] where Face 1 will contain the block number and the diagonals [IMIN,JMIN,KMIN,IMAX,JMAX,KMAX]. Example: blk: 1 [168,0,0,268,100,0].

  • outer_faces_all (List[Face]): This is a list of outer faces save as a list of Faces

Return type:

(Tuple)

plot3d.periodicity.periodicity_fast(blocks: List[Block], outer_faces: List[Face], matched_faces: List[Dict[str, int]], periodic_direction: str = 'k', rotation_axis: str = 'x', nblades: int = 55)[source]
Finds the connectivity of blocks when they are rotated by an angle defined by the number of blades. Only use this if your mesh is of an annulus.

This function reduces the size of the blocks by a factor of the minimum gcd. This speeds up finding the connectivity

Parameters:

  • blocks (List[Block]) – List of blocks that will be scanned for perodicity

  • outer_faces (List[Dict[str,int]]) – List of outer faces for each block as a dictionary format. You can get this from connectivity

  • matched_faces (ListList[Dict[str,int]]) – List of matched faces from connectivity. Matched faces was added so that it’s always removed from outer faces

  • periodic_direction (str) – either i,j,k to look for

  • rotation_axis (str) – either x,y,z

  • nblades (int) – Number of blades to consider, this affects the rotation angle.

Returns:

containing

  • periodic_faces_export (List[Dict[str,int]]): This is list of all the surfaces/faces that match when rotated by an angle formatted as a dictionary.

  • outer_faces_export (List[Dict[str,int]]): These are the list of outer faces that are not periodic formatted as a dictionary.

  • periodic_faces (List[Tuple[Face,Face]]): - This is a list of Face objects that are connected to each other organized as a list of tuples: [Face1, Face2] where Face 1 will contain the block number and the diagonals [IMIN,JMIN,KMIN,IMAX,JMAX,KMAX]. Example: blk: 1 [168,0,0,268,100,0].

  • outer_faces_all (List[Face]): This is a list of outer faces save as a list of Faces

Return type:

(Tuple)

plot3d.periodicity.rotated_periodicity(blocks: List[Block], matched_faces: List[Dict[str, int]], outer_faces: List[Dict[str, int]], rotation_angle: float, rotation_axis: str = 'x', ReduceMesh: bool = True)[source]

Finds the peridocity/connectivity by rotating a block. This is a bit different from “periodicity_fast” where you specify the periodic direction. This method doesn’t care about the direction as long as the angle you specify results in a match between the Left Face and the Right Face. I would use this instead.

Example 1:

L RL R | blk1 || Copy blk1 | | blk2 || Copy blk2 | | blk3 || Copy blk3 | Rotates the set of blocks by an angle and checks the matching surfaces for R and L.

Parameters:

  • blocks (List[Block]) – List of blocks for a particular geometry. Do not duplicate the geometry and pass it in!

  • outer_faces (List[Dict[str,int]]) – List of outer faces in dictionary form

  • rotation_angle (float) – rotation angle in between geometry in degrees.

  • rotation_axis (str, Optional) – “x”, “y”, or “z”

  • ReduceMesh (bool, Optional) – True, reduces the mesh for faster matching

periodic_faces, outer_faces_export, _, _ = rotated_periodicity(blocks,face_matches, outer_faces, rotation_angle=rotation_angle, rotation_axis = “x”)

Replaces:

Is the same as

periodic_surfaces, outer_faces_to_keep,periodic_faces,outer_faces = periodicity_fast(blocks,outer_faces,face_matches,periodic_direction=’k’,rotation_axis=’x’,nblades=55) and periodic_surfaces, outer_faces_to_keep,periodic_faces,outer_faces = periodicity(blocks,outer_faces,face_matches,periodic_direction=’k’,rotation_axis=’x’,nblades=55)

Returns:

containing

  • periodic_faces_export (List[Dict[str,int]]): This is list of all the surfaces/faces that match when rotated by an angle formatted as a dictionary.

  • outer_faces_export (List[Dict[str,int]]): These are the list of outer faces that are not periodic formatted as a dictionary.

  • periodic_faces (List[Tuple[Face,Face]]): - This is a list of Face objects that are connected to each other organized as a list of tuples: [Face1, Face2] where Face 1 will contain the block number and the diagonals [IMIN,JMIN,KMIN,IMAX,JMAX,KMAX]. Example: blk: 1 [168,0,0,268,100,0].

  • outer_faces_all (List[Face]): This is a list of outer faces save as a list of Faces

Return type:

(Tuple)

plot3d.periodicity.translational_periodicity(blocks: List[Block], outer_faces: List[Dict[str, int]], delta: float = None, translational_direction: str = 'z', node_tol_xyz: float = None, min_shared_frac: float = 0.02, min_shared_abs: int = 4, stride_u: int = 1, stride_v: int = 1) → Tuple[List[Dict[str, Dict[str, int]]], List[Tuple[Face, Face, Dict[str, str]]], List[Dict[str, int]]][source]

Detect translational periodicity between block faces along a given axis.

This function takes a set of outer block faces and attempts to identify periodic counterparts across the domain in the specified translational direction (‘x’, ‘y’, or ‘z’). It works by:

  1. Bounding faces: Uses find_bounding_faces to identify candidate lower/upper faces for the given axis.

  2. Grid reduction: Reduces blocks to their greatest common divisor (GCD) resolution to make indexing consistent across blocks.

  3. Shifting: Creates shifted copies of all blocks in both positive and negative directions along the periodic axis.

  4. Precheck in orthogonal plane: Uses a fast projection test (orthogonal to the periodic axis) to determine whether two faces could possibly match. This greatly reduces false negatives when spacing/tolerances differ slightly.

  5. Node-based match: Calls Face.touches_by_nodes on candidate pairs to check shared node positions, with an adaptive tolerance based on the in-plane spacing of each face.

  6. Pairing: Records each valid pair of periodic faces, their IJK index mappings (min→min or min→max), and removes matched faces from the outer-face list.

  7. Scaling back: Rescales reduced indices back to the original grid spacing so results are consistent with input block resolution.

Parameters:

  • blocks (List[Block]) – List of blocks.

  • outer_faces (List[Dict[str,int]]) – Outer faces represented as dictionaries (with IMIN, JMIN, KMIN, IMAX, JMAX, KMAX).

  • delta (float, optional) – Periodicity spacing along the chosen axis. If None, it is inferred from the global block min/max extent.

  • translational_direction (str, optional) – Axis to check (‘x’,’y’,’z’). Default is ‘z’.

  • node_tol_xyz (float, optional) – Absolute coordinate tolerance for node-matching. If None, tolerance is computed adaptively based on median in-plane spacing of candidate faces.

  • min_shared_frac (float, optional) – Minimum fraction of nodes that must overlap for two faces to be considered periodic. Default 0.02.

  • min_shared_abs (int, optional) – Minimum absolute number of shared nodes. Default 4.

  • stride_u (int, optional) – Subsampling stride along the first face index direction. Default 1 (no skipping).

  • stride_v (int, optional) – Subsampling stride along the second face index direction. Default 1 (no skipping).

Returns:

Tuple[

List[Dict[str, Dict[str,int]]], List[Tuple[Face, Face, Dict[str,str]]], List[Dict[str,int]]

]:

  • periodic_faces_export: Export-ready dictionaries describing each periodic pair (block indices, face extents, index mapping, and match mode).

  • periodic_pairs: Matched periodic face pairs as Face objects with IJK mapping.

  • outer_faces_remaining: Updated list of outer faces with periodic ones removed (preserving any existing id fields).

Notes

  • Works for periodicity in x, y, or z directions.

  • The adaptive tolerance makes the method robust to small spacing differences between blocks.

  • The orthogonal-plane precheck avoids expensive node comparisons when faces clearly do not align.