pyoomph.equations.topological_changes module

class pyoomph.equations.topological_changes.AxisymmetricReconnection(rmin=None, distmin=None, *, volume_conservation=True, volume_tolerance=1e-09, cap_window_factor=6.0, buffer_resolution=8, cap_spacing_factor=0.7, check_mesh_motion_direction=True, overlap_reject_factor=0.2, coalescence_arm_factor=3.0, axis_tolerance=1e-07, reservoir_depth=None, allow_fragment_removal=True, segment_jump_offset=1.0, handle_zeta=True, max_deferred_events=25, max_unplannable_states=25)[source]

Bases: InterfaceEquations

Detects axisymmetric pinch-off and coalescence and requests the corresponding remesh.

Attach it to the free interface of an axisymmetric problem whose bulk mesh comes from a TopologicalChangesGmshTemplate:

eqs += AxisymmetricReconnection(rmin=5*micro*meter, distmin=5*micro*meter) @ "interface"

Both thresholds are physical lengths (they may carry units) and either may be None to switch off that kind of event:

  • a neck whose minimal interface radius drops below rmin pinches off;

  • two fragments whose axial tip-to-tip gap drops below distmin coalesce.

The event itself is not applied here. It is handed to the mesh template as a SurgeryPlan and built into the next mesh by define_geometry, i.e. by the ordinary remeshing-by-recreation path.

axis_tolerance

A point counts as sitting on the axis if |x| is below this times the size of the interface.

before_newton_convergence_check(eqtree)[source]

Reject a step that would push two approaching tips through each other.

Only worth doing once something is actually close (see coalescence_arm_factor): it runs per Newton step, so it recomputes the tip positions from the mesh data and does no morphology.

On a distributed mesh the verdict is a statement about the whole interface - the two tips approaching each other are routinely on different ranks - so the armed case merges, decides on rank 0 and broadcasts. Every rank therefore returns the same answer and enters the same collectives. _armed is what keeps that off the per-Newton-step path away from an event, and it is itself broadcast (see after_newton_solve()), so the ranks cannot disagree about whether to enter the merge.

Return type:

bool

check_mesh_motion_direction

Refuse to coalesce a gap whose two tips are moving apart.

coalescence_arm_factor

The guard above is only armed once some gap is below this multiple of distmin.

distmin

Axial tip-to-tip gap below which two fragments coalesce. None disables coalescence.

ensure_nondimensional_distance_parameters(problem)[source]

Convert rmin/distmin to the problem’s spatial scale, once.

Return type:

None

get_boundary_line_segments(name, sort_along_axis='y+')[source]

The nondimensional polylines of a boundary of the parent domain, ordered and oriented.

The mesh-based replacement of the old helper of the same name, which read the point entries of a Remesher2d. There is no such remesher on the recreation path, and the mesh is the more direct source anyway.

Local: on a distributed mesh this describes this rank’s partition of the boundary, not the whole of it. The detection does not go through here - it merges, see _needs_merged_interface(); use get_boundary_coordinates() if the whole boundary is what is wanted.

Return type:

list[NDArray[float64]]

get_interface_and_axisymm_name()[source]

The short names of this interface and of the symmetry axis of the same domain.

The axis is found the way the legacy handler found it - it is the boundary all of whose points sit at r = 0 - but from the bulk mesh rather than from a remesher’s line entries, and with a tolerance relative to the size of the domain instead of a hard-coded 1e-7.

Collective on a distributed problem: see _interface_and_axis_name().

Return type:

tuple[str, str]

get_opposite_and_opposite_axisymm_name()[source]

The same, but for the domain on the other side of this interface (None if there is none).

Return type:

tuple[str | None, str | None]

handle_zeta

Carry the interface fields across the event by writing the plan’s zeta chart onto both the old and the new interface (see _before_mesh_to_mesh_interpolation()). Switch off to leave the transfer to whatever the geometry alone can match.

max_deferred_events

How many consecutive solves may end in a WaistNotYetSeparable before it is treated as a wrong rmin and raised. A collapsing neck needs one, occasionally two; a neck that is not collapsing at all would otherwise defer for ever while the mesh degenerates.

max_unplannable_states

How many consecutive solves may end in an InterfaceStateNotPlannable before it is treated as a real geometry this module cannot handle and raised. The transients it exists for are gone by the retry at a smaller dt; a cross section that stays self-intersecting is not something waiting will fix.

overlap_reject_factor

Reject a Newton step that brings two tips closer than this multiple of distmin, so that an adaptive time stepper cuts dt instead of letting them pass through each other. None switches the guard off.

reservoir_depth

Signed axial depth of the body of liquid behind a wall contact line. Without it a "fixed" chain end is closed straight across at the contact height, which is only right when there is nothing behind the contact - a drop cut by a symmetry plane. A nozzle meniscus has a reservoir behind it, and the flat closure then cuts it off: a meniscus dimpled near the axis is left as a sliver thinner than rmin and is either erased or split into a ring, and one that crosses the contact height is left self-intersecting. Set it to the depth of the reservoir along the wall - deeper than any excursion of the interface past the contact line - with the sign pointing INTO the liquid.

The closure is a straight wall at the CONTACT radius, for the whole depth. On a bore that widens - a nozzle opening into a feedthrough - that is a wall which is not there past the nozzle, so an interface retracted that far runs alongside something synthetic. The opening leaves a band of 2*rmin around the closure alone for exactly that reason, so it costs no detection; but the volume the plan conserves is measured against this same closure, so a depth far beyond the real geometry is not free.

rmin

Minimal interface radius below which a neck pinches off. None disables pinch-off.

class pyoomph.equations.topological_changes.DisjunctDomainMarker(name, direction='up')[source]

Bases: Equations

Number the connected components of a mesh into a D0 field, ordered along y.

Warning

Not usable on a mesh distributed with --distribute: the flood fill below walks the elements this rank holds, so each rank numbers the components of its own partition from zero. Unlike the detection of AxisymmetricReconnection this cannot be fixed by merging - the marker is written back onto the local elements - and it would need the component labels to be reconciled across the partition boundaries instead.

class pyoomph.equations.topological_changes.ReconnectedBoundaries(interface_chains=<factory>, axis_segments=<factory>, opposite_axis_segments=<factory>, events=<factory>, fragment_volumes=<factory>, has_plan=False, nondimensional=False)[source]

Bases: object

The result of _TopologicalChangesMixin.get_reconnected_boundaries().

axis_segments: list[tuple[tuple[Expression | GiNaC_GlobalParam | int | float, Expression | GiNaC_GlobalParam | int | float], tuple[Expression | GiNaC_GlobalParam | int | float, Expression | GiNaC_GlobalParam | int | float]]]

Axis pieces that belong to the domain the interface bounds, as ((x0,y0),(x1,y1)) pairs.

events: list[ReconnectionEvent]

The reconnection events behind this geometry; empty for a plain quality remesh.

fragment_volumes: list[float | Expression | GiNaC_GlobalParam | int]

Target volume of each fragment, in the same units as points. Meant for verification.

has_plan: bool = False

Whether a surgery plan was consumed, i.e. whether this is a reconnection or a quality remesh.

interface_chains: list[ReconnectedChain]

The free interface, one entry per connected fluid fragment, ordered by ascending y.

nondimensional: bool = False

Whether points/fragment_volumes are nondimensional.

opposite_axis_segments: list[tuple[tuple[Expression | GiNaC_GlobalParam | int | float, Expression | GiNaC_GlobalParam | int | float], tuple[Expression | GiNaC_GlobalParam | int | float, Expression | GiNaC_GlobalParam | int | float]]]

Axis pieces that belong to the other side of the interface, i.e. the gaps between fragments plus whatever the opposite phase covered before. Empty unless opposite_axis_name was given.

class pyoomph.equations.topological_changes.ReconnectedChain(points, suggested_sizes, end_types=('axis', 'axis'), zeta=None, origin=None, nondimensional=False)[source]

Bases: object

One interface polyline of the geometry that is about to be built.

points carry the spatial scaling unless nondimensional=True was requested, so they can be fed straight to the template’s point(). suggested_sizes are always plain nondimensional floats, because that is what both backends’ size argument is.

nondimensional: bool = False

Whether points are plain numbers rather than dimensional expressions.

origin: NDArray[int32] | None = None

freshly created by the surgery. None for a plain remesh, where every point is an old one.

Type:

>= 0

Type:

index of the old interface point this point is; -1

zeta: NDArray[float64] | None = None

Old interface chart of each point, or None for a plain remesh. Handed out for user code; the transfer itself reads the plan’s NewChain.zeta directly, in AxisymmetricReconnection._before_mesh_to_mesh_interpolation().

class pyoomph.equations.topological_changes.TopologicalChangesGmshTemplate(loaded_from_mesh_file=None)[source]

Bases: GmshTemplate

TopologicalChangesTemplate on top of a GmshTemplate.

get_reconnected_boundaries(interface_name, axis_name, opposite_axis_name=None, nondimensional=False)

The interface and axis of the mesh that is about to be created.

May only be called from define_geometry while remeshing. If an AxisymmetricReconnection has planned a pinch-off or coalescence, the returned chains and axis spans describe the reconnected geometry; otherwise they describe the current one, so that the same define_geometry branch also serves a plain quality remesh.

Parameters:
  • interface_name (str) – The free interface, as "domain/boundary", e.g. "liquid/interface". This is also the key the surgery plan was filed under.

  • axis_name (str) – The symmetry axis on the side of interface_name, as "domain/boundary".

  • opposite_axis_name (str | None) – The symmetry axis of the opposite phase, if there is one. Only then is opposite_axis_segments filled.

  • nondimensional (bool) – Return plain numbers instead of coordinates carrying the spatial scale.

Return type:

ReconnectedBoundaries

has_pending_surgery_plan(interface_name=None)

Whether a reconnection is waiting to be built into the next mesh.

Return type:

bool

lines_from_axis_segments(segments, name, size=None)

Turn axis spans into named two-point lines. An empty list of segments is not an error: after a coalescence a phase can lose its share of the axis entirely.

Return type:

list[Line]

point(x, y=0.0, z=0.0, size=None, *, name=None, consider_spatial_scale=None)[source]

As point(), but merges nearly coincident points; see TopologicalChangesTemplate._snapped_point().

Return type:

Point

spline_from_chain(chain, name, size=None)

Turn one ReconnectedChain into a named spline (a line if it has two points).

Parameters:
Return type:

Spline | Line

class pyoomph.equations.topological_changes.TopologicalChangesTQMeshTemplate[source]

Bases: TQMeshTemplate

TopologicalChangesTemplate on top of a TQMeshTemplate.

The same define_geometry serves either backend: the geometry methods the surgery goes through - spline_from_chain(), lines_from_axis_segments(), plane_surface - are spelled the same way in both. What differs is everything around them, i.e. how the element sizes are prescribed: gmsh has size fields, TQMesh has mesh_size().

get_reconnected_boundaries(interface_name, axis_name, opposite_axis_name=None, nondimensional=False)

The interface and axis of the mesh that is about to be created.

May only be called from define_geometry while remeshing. If an AxisymmetricReconnection has planned a pinch-off or coalescence, the returned chains and axis spans describe the reconnected geometry; otherwise they describe the current one, so that the same define_geometry branch also serves a plain quality remesh.

Parameters:
  • interface_name (str) – The free interface, as "domain/boundary", e.g. "liquid/interface". This is also the key the surgery plan was filed under.

  • axis_name (str) – The symmetry axis on the side of interface_name, as "domain/boundary".

  • opposite_axis_name (str | None) – The symmetry axis of the opposite phase, if there is one. Only then is opposite_axis_segments filled.

  • nondimensional (bool) – Return plain numbers instead of coordinates carrying the spatial scale.

Return type:

ReconnectedBoundaries

has_pending_surgery_plan(interface_name=None)

Whether a reconnection is waiting to be built into the next mesh.

Return type:

bool

lines_from_axis_segments(segments, name, size=None)

Turn axis spans into named two-point lines. An empty list of segments is not an error: after a coalescence a phase can lose its share of the axis entirely.

Return type:

list[Line]

point(x, y=0.0, size=None, *, size_range=None, name=None, consider_spatial_scale=None)[source]

As point(), but merges nearly coincident points; see TopologicalChangesTemplate._snapped_point().

Return type:

TQMeshPoint

spline_from_chain(chain, name, size=None)[source]

As _TopologicalChangesMixin.spline_from_chain(), but the chain is resampled at the element sizes it asks for rather than used as it stands.

TQMesh takes the points it is given as the boundary edges themselves, where gmsh takes them as the geometry only and discretises it by size afterwards. The chain comes from get_boundary_coordinates, which walks the interface nodes, so on a second-order interface it holds two points per element - and handing all of them over doubles the boundary discretisation at every remesh, which multiplies the element count of the whole mesh by four: measured on a plain unit square, 40 boundary edges became 80, 160 and 320 over three quality remeshes, and 589 elements became 30850.

So the chain becomes the control points of the spline and TQMesh distributes the chain along it by the size function, which is the mechanism its spline() documents for exactly this purpose and which is stable. The per-point sizes the plan asks for - a fresh cap is finer than the interface it grew out of - are supplied through that size function, for the duration of this call only, since TQMesh has no per-control-point sizes to pass them as.

Return type:

Any

class pyoomph.equations.topological_changes.TopologicalChangesTemplate[source]

Bases: _TopologicalChangesMixin, ABC

Virtual base of every mesh template that can rebuild itself after a pinch-off or a coalescence, i.e. of TopologicalChangesGmshTemplate and TopologicalChangesTQMeshTemplate. Use it for isinstance; it is what AxisymmetricReconnection requires of the bulk template it is attached to.

It is a virtual base for the concrete templates - they register() with it rather than deriving from it - because MeshTemplate is a nanobind type and nanobind refuses any class with two bases, so a real mixin cannot be inherited alongside a backend. The shared implementation therefore lives in _TopologicalChangesMixin, which this class does inherit (it is a plain Python class) and which _with_topological_changes() copies into each backend.