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:
InterfaceEquationsDetects 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
Noneto switch off that kind of event:a neck whose minimal interface radius drops below
rminpinches off;two fragments whose axial tip-to-tip gap drops below
distmincoalesce.
The event itself is not applied here. It is handed to the mesh template as a
SurgeryPlanand built into the next mesh bydefine_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.
_armedis what keeps that off the per-Newton-step path away from an event, and it is itself broadcast (seeafter_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.
Nonedisables coalescence.
- ensure_nondimensional_distance_parameters(problem)[source]
Convert
rmin/distminto 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(); useget_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-coded1e-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 (
Noneif 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
WaistNotYetSeparablebefore it is treated as a wrongrminand 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
InterfaceStateNotPlannablebefore 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 smallerdt; 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 cutsdtinstead of letting them pass through each other.Noneswitches 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 thanrminand 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*rminaround 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.
Nonedisables pinch-off.
- class pyoomph.equations.topological_changes.DisjunctDomainMarker(name, direction='up')[source]
Bases:
EquationsNumber the connected components of a mesh into a
D0field, ordered alongy.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 ofAxisymmetricReconnectionthis 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:
objectThe 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_volumesare 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_namewas given.
- class pyoomph.equations.topological_changes.ReconnectedChain(points, suggested_sizes, end_types=('axis', 'axis'), zeta=None, origin=None, nondimensional=False)[source]
Bases:
objectOne interface polyline of the geometry that is about to be built.
pointscarry the spatial scaling unlessnondimensional=Truewas requested, so they can be fed straight to the template’spoint().suggested_sizesare always plain nondimensional floats, because that is what both backends’sizeargument is.- nondimensional: bool = False
Whether
pointsare plain numbers rather than dimensional expressions.
- origin: NDArray[int32] | None = None
freshly created by the surgery.
Nonefor 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
Nonefor a plain remesh. Handed out for user code; the transfer itself reads the plan’sNewChain.zetadirectly, inAxisymmetricReconnection._before_mesh_to_mesh_interpolation().
- class pyoomph.equations.topological_changes.TopologicalChangesGmshTemplate(loaded_from_mesh_file=None)[source]
Bases:
GmshTemplateTopologicalChangesTemplateon top of aGmshTemplate.- 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_geometrywhile remeshing. If anAxisymmetricReconnectionhas 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 samedefine_geometrybranch 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 ofinterface_name, as"domain/boundary".opposite_axis_name (
str|None) – The symmetry axis of the opposite phase, if there is one. Only then isopposite_axis_segmentsfilled.nondimensional (
bool) – Return plain numbers instead of coordinates carrying the spatial scale.
- Return type:
- 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; seeTopologicalChangesTemplate._snapped_point().- Return type:
Point
- spline_from_chain(chain, name, size=None)
Turn one
ReconnectedChaininto a named spline (a line if it has two points).- Parameters:
chain (
ReconnectedChain) – One entry ofReconnectedBoundaries.interface_chains.name (
str) – Boundary name of the created curve.size (
float|Callable[[Expression|GiNaC_GlobalParam|int|float,Expression|GiNaC_GlobalParam|int|float,float],float] |None) –Noneuses the chain’s ownsuggested_sizes, a float a uniform size, and a callable is asked(x, y, suggested) -> sizeper point.
- Return type:
Spline|Line
- class pyoomph.equations.topological_changes.TopologicalChangesTQMeshTemplate[source]
Bases:
TQMeshTemplateTopologicalChangesTemplateon top of aTQMeshTemplate.The same
define_geometryserves 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 hasmesh_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_geometrywhile remeshing. If anAxisymmetricReconnectionhas 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 samedefine_geometrybranch 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 ofinterface_name, as"domain/boundary".opposite_axis_name (
str|None) – The symmetry axis of the opposite phase, if there is one. Only then isopposite_axis_segmentsfilled.nondimensional (
bool) – Return plain numbers instead of coordinates carrying the spatial scale.
- Return type:
- 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; seeTopologicalChangesTemplate._snapped_point().- Return type:
- 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,ABCVirtual base of every mesh template that can rebuild itself after a pinch-off or a coalescence, i.e. of
TopologicalChangesGmshTemplateandTopologicalChangesTQMeshTemplate. Use it forisinstance; it is whatAxisymmetricReconnectionrequires 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 - becauseMeshTemplateis 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.