upxo.pxtal.geotess module

Geometric tessellation class. This has the following components.

1. class geotess2d for 2D voronoi tessellation grain structures.

2. class vtess2d, inheriting from geotess2d

3. class regtess2d, inheriting from geotess2d

4. class semiregtess2d, inheriting from geotess2d

5. class demiregtess2d, inheriting from geotess2d

geotess2d: parent class for generalized geometric tessellation

vtess2d: 2D Voronoi tessellation

regtess2d: Tessellation of regular polygons. Can make tessellations of

1. Equilateral triangles

2. SQuares

3. REgular hexagons

semiregtess2d: Semi-regular tessellations. Also known as Archimedan

tessellations. Each vertex in a semiregtess2d has the same arrangement of polygons areound it.. Can make tessellations of

1. triangles & Squares

2. Triangles & Squares (but a different pattern)

3. Hexagons & Triangles

4. Hexagons & Triangles (but a different pattern)

5. Hexagons & Triangles & Squares

6. Octagons & Squares

7. Dodecagons & Triangles

8. Dodecagons & Squares & Hexagons

demiregtess2d: Demi-regular tessellations.

Dependencies

numpy matplotlib pandas shapely

Authors

Dr. Sunil Anandatheertha vaasu.anandatheertha@ukaea.uk sunilanandatheertha@gmail.com

class upxo.pxtal.geotess.geotess2d(*, from_mcgs=False)

Bases: object

Base 2D geometric / Voronoi-style tessellation grain structure.

Parent type for VTGS-style pipelines: holds seeds, junction/vertex points, grain-boundary edges, grain polygons (xtals), neighbour maps, and a property table. Prefer specialised constructors on related VT / polyxtal classes when available; many seed and neighbour helpers on this base remain stubs.

bounds

Domain bounds on x and y.

seeds

Seed multipoint / array for the tessellation.

grid

Optional underlay x/y grids.

jp, vp

Junction and vertex points (UPXO point entities).

gbedges, gbseg

Grain-boundary edges and multi-edge segments.

xtals

Grain polygons (typically Shapely).

gid

Grain IDs.

Type:

list

neigh_gid

Neighbour grain IDs per grain.

Type:

dict

prop

Morphological / other property table (e.g. DataFrame).

info

Metadata (including whether built from_mcgs).

Type:

dict

set_seed_points(upxo_mp2d=None)

Set or update seed points.

make_seeds_random(nsp=50, bounds=None)

Build uniform-random seed points within the domain bounds.

Parameters:

• nsp (int, optional) – Number of seed points to generate. Default value is 50.

• bounds (list or tuple, optional) – Domain bounds as [xmin, xmax, ymin, ymax]. If given, replaces and updates self.bounds. If None, uses the existing self.bounds, falling back to [0.0, 1.0, 0.0, 1.0] when unset.

Returns:

seeds – The generated seed points, also stored in self.seeds. Returned as an upxo.geoEntities.mulpoint2d.MPoint2d when construction from coordinates succeeds, otherwise as a plain (nsp, 2) array of x, y coordinates.

Return type:

MPoint2d or numpy.ndarray

make_seeds_pdisc(char_length=0.1, bounds=None)

Build Poisson-disc seed points using Bridson sampling.

Parameters:

• char_length (float, optional) – Minimum allowed spacing (disc radius) between seed points, in the same length units as bounds. Default value is 0.1.

• bounds (list or tuple, optional) – Domain bounds as [xmin, xmax, ymin, ymax]. If given, replaces and updates self.bounds. If None, uses the existing self.bounds, falling back to [0.0, 1.0, 0.0, 1.0] when unset.

Returns:

seeds – The generated seed points, also stored in self.seeds. Returned as an upxo.geoEntities.mulpoint2d.MPoint2d when construction from coordinates succeeds, otherwise as a plain (n, 2) array of x, y coordinates.

Return type:

MPoint2d or numpy.ndarray

Notes

Delegates to upxo.statops.sampling.bridson_uniform_density, which samples in a width x height window before the result is translated by (xmin, ymin) back into the requested bounds.

make_seeds_dart()

Build and return seeds dart.

set_seeds(seeds)

Set or update seeds.

save()

Save.

load()

Load.

find_neighbours()

Find neighbours for all grains in xtals using boundary topology.

For every pair of grain polygons, checks whether they touch or intersect and, if so, whether their intersection is a genuine shared boundary (a non-empty line with length > 1e-9, or a LineString/MultiLineString intersection geometry) rather than a single touching point. Qualifying pairs are recorded as mutual neighbours.

This is an exhaustive O(n^2) pairwise scan over self.xtals (n grains), each pairwise check itself calling into Shapely’s touches/intersects/intersection. There is no spatial index, so this does not scale well to large grain counts.

Returns:

neigh_gid – Mapping of grain ID to a list of neighbouring grain IDs. Also stored on self.neigh_gid, replacing any previous content. Keys are self.gid when its length matches len(self.xtals), otherwise range(len(self.xtals)).

Return type:

dict

Notes

Mutates self.neigh_gid in place (it is reset to an empty-list-per-grain dict at the start of the call) in addition to returning it.

find_first_nearest_neighbours(gid=None)

Return first-nearest (directly touching) neighbour grain IDs.

Computes self.neigh_gid via find_neighbours() first if it has not been populated yet (i.e. is falsy/empty); an already populated self.neigh_gid is reused as-is and not recomputed.

Parameters:

gid (hashable, optional) – Grain ID to query. If None (default), results for all grains are returned.

Returns:

neighbours – If gid is given: a list of first-nearest-neighbour grain IDs for that grain ([] if gid is unknown). If gid is None: the full self.neigh_gid dict mapping every grain ID to its list of first-nearest-neighbour IDs.

Return type:

list or dict

find_second_nearest_neighbours(gid=None)

Return second-nearest neighbour grain IDs (neighbours of neighbours).

For a given grain, the second-nearest neighbours are the union of first-nearest neighbours of each of its first-nearest neighbours, excluding the grain itself and excluding any grain already counted as a first-nearest neighbour.

Computes self.neigh_gid via find_neighbours() first if it has not been populated yet (i.e. is falsy/empty); an already populated self.neigh_gid is reused as-is and not recomputed.

Parameters:

gid (hashable, optional) – Grain ID to query. If None (default), results for all grains present in self.neigh_gid are returned.

Returns:

neighbours – If gid is given: a sorted list of second-nearest-neighbour grain IDs for that grain. If gid is None: a dict mapping every grain ID in self.neigh_gid to its sorted list of second-nearest-neighbour IDs.

Return type:

list or dict

filter_boundary_grains()

Return grain IDs that touch or intersect the domain boundary.

Returns:

boundary_grains – Grain IDs whose polygon intersects the boundary of the domain box built from self.bounds. Empty list if self.bounds or self.xtals is unset/empty.

Return type:

list

filter_internal_grains()

Return grain IDs that do not touch the domain boundary.

Returns:

internal_grains – Grain IDs in self.gid (or range(len(self.xtals)) when self.gid doesn’t match in length) that are not in the result of filter_boundary_grains().

Return type:

list

filter_grains_by_loc(loc='internal')

Filter grains by loc (‘internal’ or ‘boundary’).

filter_grains_by_prop(col, op, val)

Filter grains in self.prop by a comparison on one property column.

Parameters:

• col (str) – Column name in self.prop to filter on.

• op (str) – Comparison operator. One of '>', '>=', '<', '<=', '==', '!='.

• val (object) – Value to compare self.prop[col] against.

Returns:

filtered – Subset of self.prop where self.prop[col] op val is True.

Return type:

pandas.DataFrame

Raises:

ValueError – If self.prop is not a pandas DataFrame, or if op is not one of the supported operator strings.

divide_all_edges_in_half()

Divide all edges in half.

move_new_vertex_point()

Move new vertex point.

perturb_grain_boundaries(factor=0.05, seed=None)

Perturb grain boundaries with controlled curvature while keeping junctions fixed.

Parameters:

• factor (float, optional) – Magnitude of the boundary perturbation (curvature strength), passed through to upxo.pxtal.voronoi_tessellation_2d.engine.perturb_interfaces_2d. Default value is 0.05. Larger values produce more strongly curved grain boundaries; junctions (grain-boundary triple points) remain fixed regardless of factor.

• seed (int, optional) – Random seed for reproducible perturbation. Default value is None (non-deterministic).

Returns:

xtals – The updated list of grain polygons, also stored in self.xtals. Returned unchanged (and self.xtals is left untouched) if self.xtals is empty.

Return type:

list

convert_to_pixels()

Convert to pixels.

bounds

seeds

grid

gridpoints

jp

vp

gbedges

gbseg

xtals

gid

neigh_gid

prop

info

class upxo.pxtal.geotess.geoxtal2d

Bases: object

Single 2D geometric grain (crystal) within a tessellation.

Placeholder for future work. Planned companion to geotess2d for per-grain geometry. Every method, including __init__, currently raises NotImplementedError; this class cannot be instantiated or used in its current form. Do not use.

class upxo.pxtal.geotess.vtgs3d

Bases: object

3D Voronoi / geometric tessellation grain structure (API stub).

Placeholder for future work. Intended 3D counterpart of geotess2d with bounds, seeds, grains, junction topology, and property storage. Every method, including __init__, currently raises NotImplementedError; this class cannot be instantiated or used in its current form. Do not use.

Attributes (planned)

bounds, seeds, grid, xtals, gid, jp, gbedges, neigh_gid, prop, info

Same roles as the 2D tessellation base, extended to 3D.

set_seeds()

Set or update seeds.

save()

Save.

load()

Load.

filter_boundary_grains()

Filter boundary grains.

filter_internal_grains()

Filter internal grains.

bounds

xtals

seeds

grid

gid

jp

gbedges

neigh_gid

prop

info