upxo.geoEntities.bases module

Abstract base classes for UPXO geometric entities.

Usage

from upxo.geoEntities.bases import UPXO_Point, UPXO_Edge

Classes

UPXO_Point : Abstract base class for 2D and 3D point objects. UPXO_Edge : Abstract base class for 2D and 3D edge objects.

Notes

Concrete implementations (e.g., point2d, edge2d) must override all abstract methods. The base classes define the common interface contract only and carry no executable logic.

class upxo.geoEntities.bases.UPXO_Point(x=0.0, y=0.0, pln='ij')[source]

Bases: ABC

Abstract base class for UPXO point entities.

Defines the minimum interface that all concrete 2D and 3D point implementations must satisfy.

x
Type:

float

y
Type:

float

pln

Plane identifier (e.g. 'ij').

Type:

str

f

Reserved for future use.

Type:

object

Notes

Concrete subclasses must provide all geometric operations declared by this abstract interface.

abstractmethod add(distances, update=True, throw=False, mydecatlen2NUM='taxx')[source]

Translate this point by the given distances.

Parameters:

  • distances (object) – Translation distance specification accepted by the concrete class.

  • update (bool, optional) – Whether to update this object in place.

  • throw (bool, optional) – Whether to return generated point objects.

  • mydecatlen2NUM (str, optional) – Data-type handling mode used by concrete implementations.

Returns:

Return value defined by the concrete point class.

Return type:

object

abstractmethod distance(plist=None)[source]

Calculate Euclidean distances from this point to other points.

Parameters:

plist (object or list, optional) – Point or point collection to evaluate.

Returns:

Distance result supplied by the concrete point class.

Return type:

float or list of float

x
y
pln
f
class upxo.geoEntities.bases.UPXO_Edge[source]

Bases: ABC

Abstract base class for UPXO edge (line segment) entities.

Defines the common interface contract for all concrete 2D and 3D edge implementations. Subclasses store their start and end point references as i and j.

i

Start point of the edge.

Type:

object

j

End point of the edge.

Type:

object

Notes

Concrete subclasses are responsible for deciding whether calculations are performed in 2D, 3D, or projected coordinates.

abstract property mid

Unique identifier of this edge object.

Returns:

Identifier supplied by the concrete edge class.

Return type:

object

abstract property ang

Orientation angle of the edge.

Returns:

Edge orientation angle in degrees.

Return type:

float

abstract property length

Euclidean length of the edge.

Returns:

Edge length.

Return type:

float

classmethod by_coord(start_point, end_point)[source]

Construct an edge from two coordinate pairs or point objects.

Parameters:

  • start_point (object) – Start point or coordinate specification.

  • end_point (object) – End point or coordinate specification.

Returns:

Concrete edge instance.

Return type:

UPXO_Edge

classmethod by_loc_len_ang(*, ref='i', loc=[0, 0, 0], length=1, ang=0, degree=True)[source]

Construct an edge from a reference point, length, and angle.

Parameters:

  • ref (str, optional) – Reference endpoint identifier.

  • loc (array-like, optional) – Reference endpoint location.

  • length (float, optional) – Edge length.

  • ang (float, optional) – Edge orientation angle.

  • degree (bool, optional) – Whether ang is specified in degrees.

Returns:

Concrete edge instance.

Return type:

UPXO_Edge

abstractmethod distance_to_points(*, plist=None)[source]

Calculate distances from this edge to a list of points.

Parameters:

plist (list, optional) – Points to evaluate.

Returns:

Distance result supplied by the concrete edge class.

Return type:

object

abstractmethod distance_to_edges(*, elist=None, method='ref', refi='mid', refj='mid')[source]

Calculate distances from this edge to a list of other edges.

Parameters:

  • elist (list, optional) – Edges to evaluate.

  • method (str, optional) – Distance method used by the concrete implementation.

  • refi (str, optional) – Reference location on this edge.

  • refj (str, optional) – Reference location on candidate edges.

Returns:

Distance result supplied by the concrete edge class.

Return type:

object

abstractmethod translate_by(*, vector=None, dist=None, update=False, throw=True)[source]

Translate this edge by a displacement vector or scalar distance.

Parameters:

  • vector (array-like, optional) – Translation vector.

  • dist (float, optional) – Scalar translation distance.

  • update (bool, optional) – Whether to update this edge in place.

  • throw (bool, optional) – Whether to return a generated edge object.

Returns:

Return value supplied by the concrete edge class.

Return type:

object

abstractmethod translate_to(*, ref='i', point=None, update=False, throw=True)[source]

Translate this edge so the reference endpoint lands on point.

Parameters:

  • ref (str, optional) – Reference endpoint identifier.

  • point (object, optional) – Target point or coordinate specification.

  • update (bool, optional) – Whether to update this edge in place.

  • throw (bool, optional) – Whether to return a generated edge object.

Returns:

Return value supplied by the concrete edge class.

Return type:

object

abstractmethod rotate_about(*, axis=None, angle=0, degree=True, update=False, throw=True)[source]

Rotate this edge about an axis by the given angle.

Parameters:

  • axis (object, optional) – Rotation axis specification.

  • angle (float, optional) – Rotation angle.

  • degree (bool, optional) – Whether angle is specified in degrees.

  • update (bool, optional) – Whether to update this edge in place.

  • throw (bool, optional) – Whether to return a generated edge object.

Returns:

Return value supplied by the concrete edge class.

Return type:

object

abstractmethod attach_mp(*, mp=None, name=None)[source]

Attach a material-property object to this edge under name.

Parameters:

  • mp (object, optional) – Material-property object to attach.

  • name (str, optional) – Storage name for the material-property object.

abstractmethod attach_xtal(*, xtals=None)[source]

Associate crystal objects with this edge.

Parameters:

xtals (object or list, optional) – Crystal object or collection to associate with this edge.

abstractmethod find_neigh_point_by_distance(*, plist=None, plane='xy', r=0)[source]

Find all points within radius r of this edge.

Parameters:

  • plist (list, optional) – Candidate points.

  • plane (str, optional) – Coordinate plane used for projected distance checks.

  • r (float, optional) – Search radius.

Returns:

Neighbor result supplied by the concrete edge class.

Return type:

object

abstractmethod find_neigh_point_by_count(*, plist=None, n=None, plane='xy')[source]

Find the n nearest points to this edge.

Parameters:

  • plist (list, optional) – Candidate points.

  • n (int, optional) – Number of nearest points to return.

  • plane (str, optional) – Coordinate plane used for projected distance checks.

Returns:

Neighbor result supplied by the concrete edge class.

Return type:

object

abstractmethod find_neigh_mulpoint_by_distance(*, mplist=None, plane='xy', r=0, tolf=-1)[source]

Find all mulpoint objects within radius r of this edge.

Parameters:

  • mplist (list, optional) – Candidate multi-point objects.

  • plane (str, optional) – Coordinate plane used for projected distance checks.

  • r (float, optional) – Search radius.

  • tolf (float, optional) – Tolerance factor used by concrete implementations.

Returns:

Neighbor result supplied by the concrete edge class.

Return type:

object

abstractmethod find_neigh_edge_by_distance(*, elist=None, plane='xy', refloc='starting', r=0)[source]

Find all edges whose reference location is within radius r.

Parameters:

  • elist (list, optional) – Candidate edges.

  • plane (str, optional) – Coordinate plane used for projected distance checks.

  • refloc (str, optional) – Reference location on candidate edges.

  • r (float, optional) – Search radius.

Returns:

Neighbor result supplied by the concrete edge class.

Return type:

object

abstractmethod find_neigh_muledge_by_distance(*, melist=None, plane='xy', refloc='starting', r=0)[source]

Find all muledge objects within radius r.

Parameters:

  • melist (list, optional) – Candidate multi-edge objects.

  • plane (str, optional) – Coordinate plane used for projected distance checks.

  • refloc (str, optional) – Reference location on candidate multi-edge objects.

  • r (float, optional) – Search radius.

Returns:

Neighbor result supplied by the concrete edge class.

Return type:

object

abstractmethod find_neigh_xtal_by_distance(*, xlist=None, plane='xy', refloc='starting', r=0)[source]

Find all crystal objects within radius r of this edge.

Parameters:

  • xlist (list, optional) – Candidate crystal objects.

  • plane (str, optional) – Coordinate plane used for projected distance checks.

  • refloc (str, optional) – Reference location on candidate crystal objects.

  • r (float, optional) – Search radius.

Returns:

Neighbor result supplied by the concrete edge class.

Return type:

object

abstractmethod set_gmsh_props(prop_dict)[source]

Attach GMSH mesh properties to this edge.

Parameters:

prop_dict (dict) – GMSH property dictionary.

abstractmethod make_shapely()[source]

Return a Shapely geometry object for this edge.

Returns:

Shapely geometry supplied by the concrete edge class.

Return type:

object

abstractmethod make_vtk()[source]

Return a VTK geometry object for this edge.

Returns:

VTK geometry supplied by the concrete edge class.

Return type:

object

abstract property coords

Endpoint coordinates as a NumPy array.

Returns:

Endpoint coordinate array supplied by the concrete edge class.

Return type:

numpy.ndarray

abstractmethod array_translation(*, ncopies=10, vector=[[0, 0, 0], [0, 0, 1]], spacing='constant')[source]

Generate an array of translated copies of this edge.

Parameters:

  • ncopies (int, optional) – Number of translated copies to generate.

  • vector (array-like, optional) – Translation vector specification.

  • spacing (str, optional) – Spacing mode for translated copies.

Returns:

Translated edge collection supplied by the concrete edge class.

Return type:

object

abstractmethod lies_on_which_edge(*, elist=None, consider_ends=True)[source]

Determine which edges from elist this edge lies on.

Parameters:

  • elist (list, optional) – Candidate edges.

  • consider_ends (bool, optional) – Whether endpoint coincidence is considered part of the test.

Returns:

Containment result supplied by the concrete edge class.

Return type:

object

i
j
abstractmethod lies_in_which_xtal(*, xlist=None, cosider_boundary=True, consider_boundary_ends=True)[source]

Determine which crystal from xlist contains this edge.

Parameters:

  • xlist (list, optional) – Candidate crystal objects.

  • cosider_boundary (bool, optional) – Whether crystal boundaries are considered part of the test.

  • consider_boundary_ends (bool, optional) – Whether edge endpoints on boundaries are considered.

Returns:

Containment result supplied by the concrete edge class.

Return type:

object