diff --git a/docs/docstrings/inventory.json b/docs/docstrings/inventory.json index 1fe1b629..d5dd83fa 100644 --- a/docs/docstrings/inventory.json +++ b/docs/docstrings/inventory.json @@ -21,7 +21,7 @@ "name": "SNES_Scalar", "kind": "class", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 2327, + "line": 2336, "signature": "class SNES_Scalar(SolverBaseClass):", "parameters": [], "returns": null, @@ -38,7 +38,7 @@ "name": "SNES_Vector", "kind": "class", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 3263, + "line": 3272, "signature": "class SNES_Vector(SolverBaseClass):", "parameters": [], "returns": null, @@ -55,7 +55,7 @@ "name": "SNES_MultiComponent", "kind": "class", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 4334, + "line": 4343, "signature": "class SNES_MultiComponent(SolverBaseClass):", "parameters": [], "returns": null, @@ -72,7 +72,7 @@ "name": "SNES_Stokes_SaddlePt", "kind": "class", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 4998, + "line": 5007, "signature": "class SNES_Stokes_SaddlePt(SolverBaseClass):", "parameters": [], "returns": null, @@ -1265,7 +1265,7 @@ "name": "SphericalCoordinateAccessor", "kind": "class", "file": "src/underworld3/coordinates.py", - "line": 925, + "line": 926, "signature": "class SphericalCoordinateAccessor", "parameters": [], "returns": null, @@ -1283,7 +1283,7 @@ "name": "CoordinateSystem", "kind": "class", "file": "src/underworld3/coordinates.py", - "line": 1325, + "line": 1326, "signature": "class CoordinateSystem", "parameters": [], "returns": null, @@ -1409,7 +1409,7 @@ "name": "F0", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 1811, + "line": 1820, "signature": "def F0(self):", "parameters": [], "returns": null, @@ -1427,7 +1427,7 @@ "name": "F1", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 1815, + "line": 1824, "signature": "def F1(self):", "parameters": [], "returns": null, @@ -1445,7 +1445,7 @@ "name": "u", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 1830, + "line": 1839, "signature": "def u(self, new_u):", "parameters": [], "returns": null, @@ -1463,7 +1463,7 @@ "name": "DuDt", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 1845, + "line": 1854, "signature": "def DuDt(self, new_du):", "parameters": [], "returns": null, @@ -1481,7 +1481,7 @@ "name": "DFDt", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 1860, + "line": 1869, "signature": "def DFDt(self, new_dF):", "parameters": [], "returns": null, @@ -1499,7 +1499,7 @@ "name": "constitutive_model", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 1881, + "line": 1890, "signature": "def constitutive_model(self, model_or_class):", "parameters": [], "returns": null, @@ -1517,7 +1517,7 @@ "name": "constant_nullspace", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 2502, + "line": 2511, "signature": "def constant_nullspace(self, value):", "parameters": [], "returns": null, @@ -1535,7 +1535,7 @@ "name": "petsc_use_constant_nullspace", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 2571, + "line": 2580, "signature": "def petsc_use_constant_nullspace(self, value):", "parameters": [], "returns": null, @@ -1553,7 +1553,7 @@ "name": "tolerance", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 2597, + "line": 2606, "signature": "def tolerance(self, value):", "parameters": [], "returns": null, @@ -1571,7 +1571,7 @@ "name": "tolerance", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 3440, + "line": 3449, "signature": "def tolerance(self, value):", "parameters": [], "returns": null, @@ -1589,7 +1589,7 @@ "name": "tolerance", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 4453, + "line": 4462, "signature": "def tolerance(self):", "parameters": [], "returns": null, @@ -1607,7 +1607,7 @@ "name": "tolerance", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 4457, + "line": 4466, "signature": "def tolerance(self, value):", "parameters": [], "returns": null, @@ -1625,7 +1625,7 @@ "name": "p", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 5102, + "line": 5111, "signature": "def p(inner_self):", "parameters": [], "returns": null, @@ -1643,7 +1643,7 @@ "name": "p", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 5106, + "line": 5115, "signature": "def p(inner_self, new_p):", "parameters": [], "returns": null, @@ -1661,7 +1661,7 @@ "name": "tolerance", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 5792, + "line": 5804, "signature": "def tolerance(self, value):", "parameters": [], "returns": null, @@ -1679,7 +1679,7 @@ "name": "strategy", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 5823, + "line": 5835, "signature": "def strategy(self, value):", "parameters": [], "returns": null, @@ -1697,7 +1697,7 @@ "name": "PF0", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 5911, + "line": 5923, "signature": "def PF0(self, value):", "parameters": [], "returns": null, @@ -1715,7 +1715,7 @@ "name": "p", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 5936, + "line": 5948, "signature": "def p(self, new_p):", "parameters": [], "returns": null, @@ -1733,7 +1733,7 @@ "name": "saddle_preconditioner", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 5956, + "line": 5968, "signature": "def saddle_preconditioner(self, function):", "parameters": [], "returns": null, @@ -1751,7 +1751,7 @@ "name": "petsc_use_nullspace", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 5974, + "line": 5986, "signature": "def petsc_use_nullspace(self, value):", "parameters": [], "returns": null, @@ -1769,7 +1769,7 @@ "name": "petsc_use_pressure_nullspace", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 6025, + "line": 6037, "signature": "def petsc_use_pressure_nullspace(self, value):", "parameters": [], "returns": null, @@ -1787,7 +1787,7 @@ "name": "multiplier_schur_pc", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 6066, + "line": 6078, "signature": "def multiplier_schur_pc(self, value):", "parameters": [], "returns": null, @@ -1805,7 +1805,7 @@ "name": "petsc_velocity_nullspace_basis", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 6121, + "line": 6133, "signature": "def petsc_velocity_nullspace_basis(self, modes):", "parameters": [], "returns": null, @@ -1907,7 +1907,7 @@ "name": "RemeshPolicy", "kind": "class", "file": "src/underworld3/discretisation/remesh.py", - "line": 56, + "line": 75, "signature": "class RemeshPolicy", "parameters": [], "returns": null, @@ -1925,11 +1925,11 @@ "name": "RemeshContext", "kind": "class", "file": "src/underworld3/discretisation/remesh.py", - "line": 97, + "line": 116, "signature": "class RemeshContext", "parameters": [], "returns": null, - "existing_docstring": "State passed to operator ``on_remesh`` hooks.\n\nCarries the geometric data an operator (typically a ``DuDt``) needs\nto update its own history coherently \u2014 old/new coordinates, total\ndisplacement across the mover sweep, ``dt``, and a scratch slot\nwhere an ALE-style operator stashes ``v_mesh`` for the next solve\nto consume. The framework has already handled the generic\nper-variable REMAP pass before hooks are fired.\n\n``managed_snapshot`` holds pre-move ``.data`` for every\noperator-managed variable (vars with ``_remesh_managed_by`` set).\nThe default CARRY path doesn't need it \u2014 ``.data`` is left\nuntouched. A hook that needs to fall back to REMAP (e.g. on an OT\nreset, see ``ale_opt_out``) calls\n:func:`remap_var_set` with this dict and its own var list.\n\n``scratch`` is a free-form dict where adapt ops or hooks publish\nflags / per-step state (e.g. ``ale_opt_out``, a stashed\n``v_mesh``). Keys are by convention.", + "existing_docstring": "State passed to operator ``on_remesh`` hooks.\n\nCarries the geometric data an operator (typically a ``DuDt``) needs\nto update its own history coherently \u2014 old/new coordinates, total\ndisplacement across the mover sweep, ``dt``, and a scratch slot\nwhere an ALE-style operator stashes ``v_mesh`` for the next solve\nto consume. The framework has already handled the generic\nper-variable REMAP pass before hooks are fired.\n\n``managed_snapshot`` holds pre-move ``.data`` for every\noperator-managed variable (vars with ``_remesh_managed_by`` set).\nThe default CARRY path doesn't need it \u2014 ``.data`` is left\nuntouched. A hook that needs to fall back to REMAP (e.g. on an OT\nreset, see ``ale_opt_out``) calls\n:func:`remap_var_set` with this dict and its own var list.\n\n``scratch`` is a free-form dict where adapt ops or hooks publish\nflags / per-step state. Two keys are in use:\n\n* ``\"ale_opt_out\"`` \u2014 published by ``OT_adapt``\n (:mod:`underworld3.meshing._ot_adapt`, from inside ``do_move`` via\n ``mesh._remesh_pending_scratch``) on a reset adapt; consumed by\n the ``DuDt`` ``on_remesh`` hook (:mod:`underworld3.systems.ddt`),\n which falls back to REMAP for its managed history vars.\n* ``\"v_mesh\"`` \u2014 the Phase 2 ALE convention: an ALE-style operator\n hook stashes the mesh velocity here for the next solve to\n consume. No producer exists yet.", "harvested_comments": [], "status": "partial", "needs": [ @@ -2515,7 +2515,7 @@ "name": "IndexSwarmVariable", "kind": "class", "file": "src/underworld3/swarm.py", - "line": 2146, + "line": 2210, "signature": "class IndexSwarmVariable", "parameters": [], "returns": null, @@ -2532,7 +2532,7 @@ "name": "Swarm", "kind": "class", "file": "src/underworld3/swarm.py", - "line": 2603, + "line": 2667, "signature": "class Swarm", "parameters": [], "returns": null, @@ -2549,7 +2549,7 @@ "name": "NodalPointSwarm", "kind": "class", "file": "src/underworld3/swarm.py", - "line": 5076, + "line": 5080, "signature": "class NodalPointSwarm", "parameters": [], "returns": null, @@ -3853,7 +3853,7 @@ "name": "add_essential_bc", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 1655, + "line": 1664, "signature": "def add_essential_bc(self, conds, boundary, components=None):", "parameters": [], "returns": null, @@ -3870,7 +3870,7 @@ "name": "add_natural_bc", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 1698, + "line": 1707, "signature": "def add_natural_bc(self, conds, boundary, components=None):", "parameters": [], "returns": null, @@ -3887,7 +3887,7 @@ "name": "add_dirichlet_bc", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 1756, + "line": 1765, "signature": "def add_dirichlet_bc(self, conds, boundary, components=None):", "parameters": [], "returns": null, @@ -3904,7 +3904,7 @@ "name": "u", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 1819, + "line": 1828, "signature": "def u(self):", "parameters": [], "returns": null, @@ -3922,7 +3922,7 @@ "name": "DuDt", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 1835, + "line": 1844, "signature": "def DuDt(self):", "parameters": [], "returns": null, @@ -3940,7 +3940,7 @@ "name": "DFDt", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 1850, + "line": 1859, "signature": "def DFDt(self):", "parameters": [], "returns": null, @@ -3958,7 +3958,7 @@ "name": "constitutive_model", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 1866, + "line": 1875, "signature": "def constitutive_model(self):", "parameters": [], "returns": null, @@ -3976,7 +3976,7 @@ "name": "tau", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 1925, + "line": 1934, "signature": "def tau(self):", "parameters": [], "returns": null, @@ -3993,7 +3993,7 @@ "name": "validate_solver", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 2076, + "line": 2085, "signature": "def validate_solver(self):", "parameters": [], "returns": null, @@ -4010,7 +4010,7 @@ "name": "get_dof_partition", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 2093, + "line": 2102, "signature": "def get_dof_partition(self,\n section_type: str,\n filename: Optional[str | None] = None,\n outputPath: Optional[str] = \"\"):", "parameters": [], "returns": null, @@ -4027,7 +4027,7 @@ "name": "boundary_flux", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 2290, + "line": 2299, "signature": "def boundary_flux(self, boundary, mass=\"lumped\", remove_mean=False, normal=None):", "parameters": [], "returns": null, @@ -4044,7 +4044,7 @@ "name": "boundary_flux_field", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 2308, + "line": 2317, "signature": "def boundary_flux_field(self, boundary, field, mass=\"lumped\",\n remove_mean=False, scale=1.0, normal=None):", "parameters": [], "returns": null, @@ -4061,7 +4061,7 @@ "name": "constant_nullspace", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 2485, + "line": 2494, "signature": "def constant_nullspace(self):", "parameters": [], "returns": null, @@ -4079,7 +4079,7 @@ "name": "petsc_use_constant_nullspace", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 2559, + "line": 2568, "signature": "def petsc_use_constant_nullspace(self):", "parameters": [], "returns": null, @@ -4097,7 +4097,7 @@ "name": "tolerance", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 2575, + "line": 2584, "signature": "def tolerance(self):", "parameters": [], "returns": null, @@ -4114,7 +4114,7 @@ "name": "solve", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 3053, + "line": 3062, "signature": "def solve(self,\n zero_init_guess: bool =True,\n _force_setup: bool =False,\n verbose: bool=False,\n debug: bool=False,\n debug_name: str=None,\n time=None,\n divergence_retries: int=0, ):", "parameters": [], "returns": null, @@ -4129,7 +4129,7 @@ "name": "tolerance", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 3423, + "line": 3432, "signature": "def tolerance(self):", "parameters": [], "returns": null, @@ -4146,7 +4146,7 @@ "name": "add_nitsche_bc", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 3447, + "line": 3456, "signature": "def add_nitsche_bc(self, conds=None, boundary=None, direction=None,\n normal=None, gamma=10.0, theta=1, mask=None,\n local_h=True, g=None):", "parameters": [], "returns": null, @@ -4163,7 +4163,7 @@ "name": "solve", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 4140, + "line": 4149, "signature": "def solve(self,\n zero_init_guess: bool =True,\n _force_setup: bool =False,\n verbose=False,\n debug=False,\n debug_name=None,\n divergence_retries: int=0,\n ):", "parameters": [], "returns": null, @@ -4178,7 +4178,7 @@ "name": "n_components", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 4448, + "line": 4457, "signature": "def n_components(self):", "parameters": [], "returns": null, @@ -4195,7 +4195,7 @@ "name": "solve", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 4913, + "line": 4922, "signature": "def solve(self,\n zero_init_guess: bool = True,\n _force_setup: bool = False,\n verbose=False,\n debug=False,\n debug_name=None,\n divergence_retries: int=0,\n ):", "parameters": [], "returns": null, @@ -4212,7 +4212,7 @@ "name": "add_rotated_freeslip_bc", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 5338, + "line": 5347, "signature": "def add_rotated_freeslip_bc(self, conds=None, boundary=None, normal=None):", "parameters": [], "returns": null, @@ -4229,7 +4229,7 @@ "name": "boundary_normal_traction", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 5460, + "line": 5472, "signature": "def boundary_normal_traction(self, boundary, mass=\"lumped\"):", "parameters": [], "returns": null, @@ -4247,7 +4247,7 @@ "name": "dynamic_topography", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 5479, + "line": 5491, "signature": "def dynamic_topography(self, boundary, field, buoyancy_scale=1.0, mass=\"lumped\"):", "parameters": [], "returns": null, @@ -4265,7 +4265,7 @@ "name": "add_nitsche_bc", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 5500, + "line": 5512, "signature": "def add_nitsche_bc(self, conds=None, boundary=None, direction=None, normal=None,\n gamma=10.0, theta=1, mask=None, local_h=True, g=None):", "parameters": [], "returns": null, @@ -4282,7 +4282,7 @@ "name": "tolerance", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 5766, + "line": 5778, "signature": "def tolerance(self):", "parameters": [], "returns": null, @@ -4299,7 +4299,7 @@ "name": "strategy", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 5804, + "line": 5816, "signature": "def strategy(self):", "parameters": [], "returns": null, @@ -4316,7 +4316,7 @@ "name": "PF0", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 5890, + "line": 5902, "signature": "def PF0(self):", "parameters": [], "returns": null, @@ -4333,7 +4333,7 @@ "name": "p", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 5917, + "line": 5929, "signature": "def p(self):", "parameters": [], "returns": null, @@ -4350,7 +4350,7 @@ "name": "saddle_preconditioner", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 5941, + "line": 5953, "signature": "def saddle_preconditioner(self):", "parameters": [], "returns": null, @@ -4367,7 +4367,7 @@ "name": "petsc_use_nullspace", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 5961, + "line": 5973, "signature": "def petsc_use_nullspace(self):", "parameters": [], "returns": null, @@ -4385,7 +4385,7 @@ "name": "petsc_use_pressure_nullspace", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 5990, + "line": 6002, "signature": "def petsc_use_pressure_nullspace(self):", "parameters": [], "returns": null, @@ -4403,7 +4403,7 @@ "name": "multiplier_schur_pc", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 6035, + "line": 6047, "signature": "def multiplier_schur_pc(self):", "parameters": [], "returns": null, @@ -4421,7 +4421,7 @@ "name": "petsc_velocity_nullspace_basis", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 6071, + "line": 6083, "signature": "def petsc_velocity_nullspace_basis(self):", "parameters": [], "returns": null, @@ -4439,7 +4439,7 @@ "name": "validate_solver", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 6498, + "line": 6510, "signature": "def validate_solver(self):", "parameters": [], "returns": null, @@ -4456,7 +4456,7 @@ "name": "get_dof_partition", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 6520, + "line": 6532, "signature": "def get_dof_partition(self,\n section_type: str,\n filename: Optional[str | None] = None,\n outputPath: Optional[str] = \"\"):", "parameters": [], "returns": null, @@ -4473,7 +4473,7 @@ "name": "set_active_region", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 7605, + "line": 7617, "signature": "def set_active_region(self, region_label_name, region_label_value):", "parameters": [], "returns": null, @@ -4490,7 +4490,7 @@ "name": "compute_volume_residual_fields", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 7665, + "line": 7677, "signature": "def compute_volume_residual_fields(\n self,\n time=None,\n verbose=False,\n cell_indices=None,\n residual_field_id=None,\n include_boundary_terms=False,\n ):", "parameters": [], "returns": null, @@ -4507,7 +4507,7 @@ "name": "compute_boundary_residual_fields", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 7804, + "line": 7816, "signature": "def compute_boundary_residual_fields(self, boundary, time=None, verbose=False, residual_field_id=0):", "parameters": [], "returns": null, @@ -4525,7 +4525,7 @@ "name": "get_local_field_is", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 7943, + "line": 7955, "signature": "def get_local_field_is(section, field, unconstrained=False):", "parameters": [], "returns": null, @@ -4542,7 +4542,7 @@ "name": "solve", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 8054, + "line": 8066, "signature": "def solve(self,\n zero_init_guess: bool = True,\n picard: int = 0,\n verbose=False,\n debug=False,\n debug_name=None,\n _force_setup: bool =False,\n time=None,\n divergence_retries: int = 0, ):", "parameters": [], "returns": null, @@ -4557,7 +4557,7 @@ "name": "estimate_dt", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 8348, + "line": 8360, "signature": "def estimate_dt(self):", "parameters": [], "returns": null, @@ -7771,7 +7771,7 @@ "name": "mesh_adapt_meshVar", "kind": "function", "file": "src/underworld3/adaptivity.py", - "line": 588, + "line": 586, "signature": "(mesh, meshVarH, metricVar, verbose = False, redistribute = False)", "parameters": [ { @@ -8526,7 +8526,7 @@ "name": "checkpoint_xdmf", "kind": "function", "file": "src/underworld3/discretisation/discretisation_mesh.py", - "line": 6232, + "line": 6231, "signature": "(filename: str, meshUpdates: bool = True, meshVars: Optional[list] = [], swarmVars: Optional[list] = [], index: Optional[int] = 0)", "parameters": [ { @@ -9000,271 +9000,6 @@ "parent_class": "TransformedDict", "is_public": true }, - { - "name": "write_proxy", - "kind": "method", - "file": "src/underworld3/swarm.py", - "line": 2032, - "signature": "(self, filename: str)", - "parameters": [ - { - "name": "filename", - "type_hint": "str", - "default": null, - "description": "" - } - ], - "returns": null, - "existing_docstring": null, - "harvested_comments": [ - "if not proxied, nothing to do. return." - ], - "status": "none", - "needs": [ - "NEEDS_OVERVIEW", - "NEEDS_PARAMETERS" - ], - "parent_class": "SwarmVariable", - "is_public": true - }, - { - "name": "read_timestep", - "kind": "method", - "file": "src/underworld3/swarm.py", - "line": 2043, - "signature": "(self, data_filename: str, swarmID: str, data_name: str, index: int, outputPath = '')", - "parameters": [ - { - "name": "data_filename", - "type_hint": "str", - "default": null, - "description": "" - }, - { - "name": "swarmID", - "type_hint": "str", - "default": null, - "description": "" - }, - { - "name": "data_name", - "type_hint": "str", - "default": null, - "description": "" - }, - { - "name": "index", - "type_hint": "int", - "default": null, - "description": "" - }, - { - "name": "outputPath", - "type_hint": null, - "default": "''", - "description": "" - } - ], - "returns": null, - "existing_docstring": null, - "harvested_comments": [ - "mesh.write_timestep( \"test\", meshUpdates=False, meshVars=[X], outputPath=\"\", index=0)", - "swarm.write_timestep(\"test\", \"swarm\", swarmVars=[var], outputPath=\"\", index=0)", - "check if swarmFilename exists", - "easier to debug abs path", - "Memory-bounded parallel read. Rank 0 reads the saved file in one" - ], - "status": "none", - "needs": [ - "NEEDS_OVERVIEW", - "NEEDS_PARAMETERS" - ], - "parent_class": "SwarmVariable", - "is_public": true - }, - { - "name": "read_timestep", - "kind": "method", - "file": "src/underworld3/swarm.py", - "line": 4137, - "signature": "(self, base_filename: str, swarm_id: str, index: int, outputPath: Optional[str] = '', migrate = True)", - "parameters": [ - { - "name": "base_filename", - "type_hint": "str", - "default": null, - "description": "" - }, - { - "name": "swarm_id", - "type_hint": "str", - "default": null, - "description": "" - }, - { - "name": "index", - "type_hint": "int", - "default": null, - "description": "" - }, - { - "name": "outputPath", - "type_hint": "Optional[str]", - "default": "''", - "description": "" - }, - { - "name": "migrate", - "type_hint": null, - "default": "True", - "description": "" - } - ], - "returns": null, - "existing_docstring": null, - "harvested_comments": [ - "Keep-local restore: every rank reads the saved coordinates", - "(plain read-only h5py) and add_particles_with_coordinates", - "keeps only the points this rank owns \u2014 no communication, no", - "rank-0 memory hotspot. The cost is np-fold read amplification,", - "which scalable/striped parallel filesystems absorb, so this is" - ], - "status": "none", - "needs": [ - "NEEDS_OVERVIEW", - "NEEDS_PARAMETERS" - ], - "parent_class": "Swarm", - "is_public": true - }, - { - "name": "advection", - "kind": "method", - "file": "src/underworld3/swarm.py", - "line": 4839, - "signature": "(self, V_fn, delta_t, order = 2, corrector = False, restore_points_to_domain_func = None, evalf = False, step_limit = False)", - "parameters": [ - { - "name": "V_fn", - "type_hint": null, - "default": null, - "description": "" - }, - { - "name": "delta_t", - "type_hint": null, - "default": null, - "description": "" - }, - { - "name": "order", - "type_hint": null, - "default": "2", - "description": "" - }, - { - "name": "corrector", - "type_hint": null, - "default": "False", - "description": "" - }, - { - "name": "restore_points_to_domain_func", - "type_hint": null, - "default": "None", - "description": "" - }, - { - "name": "evalf", - "type_hint": null, - "default": "False", - "description": "" - }, - { - "name": "step_limit", - "type_hint": null, - "default": "False", - "description": "" - } - ], - "returns": null, - "existing_docstring": null, - "harvested_comments": [ - "Convert delta_t to model units if it has units", - "This ensures consistent arithmetic: velocity is in model units, so time must be too", - "X0 holds the particle location at the start of advection", - "This is needed because the particles may be migrated off-proc", - "during timestepping. Probably not needed - use global evaluation instead" - ], - "status": "none", - "needs": [ - "NEEDS_OVERVIEW", - "NEEDS_PARAMETERS" - ], - "parent_class": "Swarm", - "is_public": true - }, - { - "name": "advection", - "kind": "method", - "file": "src/underworld3/swarm.py", - "line": 5191, - "signature": "(self, V_fn, delta_t, order = 2, corrector = False, restore_points_to_domain_func = None, evalf = False, step_limit = True)", - "parameters": [ - { - "name": "V_fn", - "type_hint": null, - "default": null, - "description": "" - }, - { - "name": "delta_t", - "type_hint": null, - "default": null, - "description": "" - }, - { - "name": "order", - "type_hint": null, - "default": "2", - "description": "" - }, - { - "name": "corrector", - "type_hint": null, - "default": "False", - "description": "" - }, - { - "name": "restore_points_to_domain_func", - "type_hint": null, - "default": "None", - "description": "" - }, - { - "name": "evalf", - "type_hint": null, - "default": "False", - "description": "" - }, - { - "name": "step_limit", - "type_hint": null, - "default": "True", - "description": "" - } - ], - "returns": null, - "existing_docstring": null, - "harvested_comments": [], - "status": "none", - "needs": [ - "NEEDS_OVERVIEW", - "NEEDS_PARAMETERS" - ], - "parent_class": "NodalPointSwarm", - "is_public": true - }, { "name": "state", "kind": "method", @@ -10822,7 +10557,7 @@ "name": "metric_from_gradient", "kind": "function", "file": "src/underworld3/adaptivity.py", - "line": 159, + "line": 158, "signature": "(field: 'MeshVariable', h_min: float, h_max: float, gradient_min: float = None, gradient_max: float = None, profile: str = 'linear', name: str = None) -> 'MeshVariable'", "parameters": [ { @@ -10886,7 +10621,7 @@ "name": "metric_from_field", "kind": "function", "file": "src/underworld3/adaptivity.py", - "line": 322, + "line": 321, "signature": "(indicator: 'MeshVariable', h_min: float, h_max: float, indicator_min: float = None, indicator_max: float = None, invert: bool = False, profile: str = 'linear', name: str = None) -> 'MeshVariable'", "parameters": [ { @@ -10956,7 +10691,7 @@ "name": "mesh2mesh_swarm", "kind": "function", "file": "src/underworld3/adaptivity.py", - "line": 629, + "line": 627, "signature": "(mesh0, mesh1, swarm0, swarmVarList, proxy = True, verbose = False)", "parameters": [ { @@ -11017,7 +10752,7 @@ "name": "mesh2mesh_meshVariable", "kind": "function", "file": "src/underworld3/adaptivity.py", - "line": 870, + "line": 867, "signature": "(meshVar0, meshVar1, verbose = False)", "parameters": [ { @@ -13978,7 +13713,7 @@ } ], "returns": null, - "existing_docstring": "Convert Cartesian coordinates to geographic (lon, lat, depth).\n\nUses the mesh's ellipsoid parameters automatically.\nWhen units are active, coordinates should be nondimensional.\n\nParameters\n----------\nx : float or array_like\n X coordinate (nondimensional if units active, km otherwise)\ny : float or array_like\n Y coordinate\nz : float or array_like\n Z coordinate\n\nReturns\n-------\ntuple\n (lon, lat, depth) where:\n - lon: Longitude in degrees East (-180 to 180)\n - lat: Geodetic latitude in degrees North (-90 to 90)\n - depth: Depth (nondimensional if units active, km otherwise)\n\nExamples\n--------\n>>> # Convert mesh points to geographic for comparison with data\n>>> x, y, z = mesh.data[:, 0], mesh.data[:, 1], mesh.data[:, 2]\n>>> lon, lat, depth = mesh.geo.from_cartesian(x, y, z)", + "existing_docstring": "Convert Cartesian coordinates to geographic (lon, lat, depth).\n\nUses the mesh's ellipsoid parameters automatically.\nWhen units are active, coordinates should be nondimensional.\n\nParameters\n----------\nx : float or array_like\n X coordinate (nondimensional if units active, km otherwise)\ny : float or array_like\n Y coordinate\nz : float or array_like\n Z coordinate\n\nReturns\n-------\ntuple\n (lon, lat, depth) where:\n - lon: Longitude in degrees East (-180 to 180)\n - lat: Geodetic latitude in degrees North (-90 to 90)\n - depth: Depth (nondimensional if units active, km otherwise)\n\nExamples\n--------\n>>> # Convert mesh points to geographic for comparison with data\n>>> coords = mesh.X.coords\n>>> x, y, z = coords[:, 0], coords[:, 1], coords[:, 2]\n>>> lon, lat, depth = mesh.geo.from_cartesian(x, y, z)", "harvested_comments": [ "Convert mesh points to geographic for comparison with data", "Nondimensionalise ellipsoid for numeric coordinate conversion" @@ -13992,7 +13727,7 @@ "name": "points_to_cartesian", "kind": "method", "file": "src/underworld3/coordinates.py", - "line": 788, + "line": 789, "signature": "(self, points_geo)", "parameters": [ { @@ -14018,7 +13753,7 @@ "name": "points_from_cartesian", "kind": "method", "file": "src/underworld3/coordinates.py", - "line": 820, + "line": 821, "signature": "(self, points_xyz)", "parameters": [ { @@ -14029,10 +13764,9 @@ } ], "returns": null, - "existing_docstring": "Convert array of Cartesian points to geographic coordinates.\n\nParameters\n----------\npoints_xyz : array_like\n Array of shape (N, 3) with columns [x, y, z] in km\n\nReturns\n-------\nndarray\n Array of shape (N, 3) with columns [lon, lat, depth]\n\nExamples\n--------\n>>> # Export mesh coordinates to geographic\n>>> mesh_xyz = mesh.data # or mesh.CoordinateSystem.coords\n>>> mesh_llz = mesh.geo.points_from_cartesian(mesh_xyz)", + "existing_docstring": "Convert array of Cartesian points to geographic coordinates.\n\nParameters\n----------\npoints_xyz : array_like\n Array of shape (N, 3) with columns [x, y, z] in km\n\nReturns\n-------\nndarray\n Array of shape (N, 3) with columns [lon, lat, depth]\n\nExamples\n--------\n>>> # Export mesh coordinates to geographic\n>>> mesh_xyz = mesh.X.coords\n>>> mesh_llz = mesh.geo.points_from_cartesian(mesh_xyz)", "harvested_comments": [ - "Export mesh coordinates to geographic", - "or mesh.CoordinateSystem.coords" + "Export mesh coordinates to geographic" ], "status": "complete", "needs": [], @@ -14043,7 +13777,7 @@ "name": "view", "kind": "method", "file": "src/underworld3/coordinates.py", - "line": 861, + "line": 862, "signature": "(self)", "parameters": [], "returns": null, @@ -14061,7 +13795,7 @@ "name": "r", "kind": "property", "file": "src/underworld3/coordinates.py", - "line": 1010, + "line": 1011, "signature": "(self)", "parameters": [], "returns": null, @@ -14078,7 +13812,7 @@ "name": "theta", "kind": "property", "file": "src/underworld3/coordinates.py", - "line": 1016, + "line": 1017, "signature": "(self)", "parameters": [], "returns": null, @@ -14095,7 +13829,7 @@ "name": "phi", "kind": "property", "file": "src/underworld3/coordinates.py", - "line": 1022, + "line": 1023, "signature": "(self)", "parameters": [], "returns": null, @@ -14112,7 +13846,7 @@ "name": "coords", "kind": "property", "file": "src/underworld3/coordinates.py", - "line": 1033, + "line": 1034, "signature": "(self)", "parameters": [], "returns": null, @@ -14129,7 +13863,7 @@ "name": "r_sym", "kind": "property", "file": "src/underworld3/coordinates.py", - "line": 1093, + "line": 1094, "signature": "(self)", "parameters": [], "returns": null, @@ -14146,7 +13880,7 @@ "name": "theta_sym", "kind": "property", "file": "src/underworld3/coordinates.py", - "line": 1098, + "line": 1099, "signature": "(self)", "parameters": [], "returns": null, @@ -14163,7 +13897,7 @@ "name": "phi_sym", "kind": "property", "file": "src/underworld3/coordinates.py", - "line": 1103, + "line": 1104, "signature": "(self)", "parameters": [], "returns": null, @@ -14180,7 +13914,7 @@ "name": "unit_r", "kind": "property", "file": "src/underworld3/coordinates.py", - "line": 1115, + "line": 1116, "signature": "(self)", "parameters": [], "returns": null, @@ -14197,7 +13931,7 @@ "name": "unit_theta", "kind": "property", "file": "src/underworld3/coordinates.py", - "line": 1120, + "line": 1121, "signature": "(self)", "parameters": [], "returns": null, @@ -14214,7 +13948,7 @@ "name": "unit_phi", "kind": "property", "file": "src/underworld3/coordinates.py", - "line": 1125, + "line": 1126, "signature": "(self)", "parameters": [], "returns": null, @@ -14231,7 +13965,7 @@ "name": "unit_radial", "kind": "property", "file": "src/underworld3/coordinates.py", - "line": 1137, + "line": 1138, "signature": "(self)", "parameters": [], "returns": null, @@ -14248,7 +13982,7 @@ "name": "unit_outward", "kind": "property", "file": "src/underworld3/coordinates.py", - "line": 1142, + "line": 1143, "signature": "(self)", "parameters": [], "returns": null, @@ -14265,7 +13999,7 @@ "name": "unit_inward", "kind": "property", "file": "src/underworld3/coordinates.py", - "line": 1147, + "line": 1148, "signature": "(self)", "parameters": [], "returns": null, @@ -14282,7 +14016,7 @@ "name": "to_cartesian", "kind": "method", "file": "src/underworld3/coordinates.py", - "line": 1153, + "line": 1154, "signature": "(self, r, theta, phi)", "parameters": [ { @@ -14316,7 +14050,7 @@ "name": "from_cartesian", "kind": "method", "file": "src/underworld3/coordinates.py", - "line": 1181, + "line": 1182, "signature": "(self, x, y, z)", "parameters": [ { @@ -14350,7 +14084,7 @@ "name": "points_to_cartesian", "kind": "method", "file": "src/underworld3/coordinates.py", - "line": 1213, + "line": 1214, "signature": "(self, points_sph)", "parameters": [ { @@ -14372,7 +14106,7 @@ "name": "points_from_cartesian", "kind": "method", "file": "src/underworld3/coordinates.py", - "line": 1233, + "line": 1234, "signature": "(self, points_xyz)", "parameters": [ { @@ -14394,7 +14128,7 @@ "name": "view", "kind": "method", "file": "src/underworld3/coordinates.py", - "line": 1264, + "line": 1265, "signature": "(self)", "parameters": [], "returns": null, @@ -14412,7 +14146,7 @@ "name": "coords", "kind": "property", "file": "src/underworld3/coordinates.py", - "line": 1861, + "line": 1862, "signature": "(self)", "parameters": [], "returns": null, @@ -14435,7 +14169,7 @@ "name": "units", "kind": "property", "file": "src/underworld3/coordinates.py", - "line": 1921, + "line": 1922, "signature": "(self)", "parameters": [], "returns": null, @@ -14455,7 +14189,7 @@ "name": "with_units", "kind": "property", "file": "src/underworld3/coordinates.py", - "line": 1948, + "line": 1949, "signature": "(self)", "parameters": [], "returns": null, @@ -14478,7 +14212,7 @@ "name": "shape", "kind": "property", "file": "src/underworld3/coordinates.py", - "line": 1970, + "line": 1971, "signature": "(self)", "parameters": [], "returns": null, @@ -14495,7 +14229,7 @@ "name": "is_symbol", "kind": "property", "file": "src/underworld3/coordinates.py", - "line": 1996, + "line": 1997, "signature": "(self)", "parameters": [], "returns": null, @@ -14512,7 +14246,7 @@ "name": "is_Matrix", "kind": "property", "file": "src/underworld3/coordinates.py", - "line": 2001, + "line": 2002, "signature": "(self)", "parameters": [], "returns": null, @@ -14529,7 +14263,7 @@ "name": "is_scalar", "kind": "property", "file": "src/underworld3/coordinates.py", - "line": 2006, + "line": 2007, "signature": "(self)", "parameters": [], "returns": null, @@ -14546,7 +14280,7 @@ "name": "is_number", "kind": "property", "file": "src/underworld3/coordinates.py", - "line": 2011, + "line": 2012, "signature": "(self)", "parameters": [], "returns": null, @@ -14563,7 +14297,7 @@ "name": "is_commutative", "kind": "property", "file": "src/underworld3/coordinates.py", - "line": 2016, + "line": 2017, "signature": "(self)", "parameters": [], "returns": null, @@ -14580,7 +14314,7 @@ "name": "X", "kind": "property", "file": "src/underworld3/coordinates.py", - "line": 2096, + "line": 2097, "signature": "(self) -> sympy.Matrix", "parameters": [], "returns": "sympy.Matrix", @@ -14603,7 +14337,7 @@ "name": "x", "kind": "property", "file": "src/underworld3/coordinates.py", - "line": 2136, + "line": 2137, "signature": "(self) -> sympy.Matrix", "parameters": [], "returns": "sympy.Matrix", @@ -14620,7 +14354,7 @@ "name": "N", "kind": "property", "file": "src/underworld3/coordinates.py", - "line": 2141, + "line": 2142, "signature": "(self) -> sympy.Matrix", "parameters": [], "returns": "sympy.Matrix", @@ -14637,7 +14371,7 @@ "name": "R", "kind": "property", "file": "src/underworld3/coordinates.py", - "line": 2146, + "line": 2147, "signature": "(self) -> sympy.Matrix", "parameters": [], "returns": "sympy.Matrix", @@ -14654,7 +14388,7 @@ "name": "r", "kind": "property", "file": "src/underworld3/coordinates.py", - "line": 2151, + "line": 2152, "signature": "(self) -> sympy.Matrix", "parameters": [], "returns": "sympy.Matrix", @@ -14671,7 +14405,7 @@ "name": "xR", "kind": "property", "file": "src/underworld3/coordinates.py", - "line": 2156, + "line": 2157, "signature": "(self) -> sympy.Matrix", "parameters": [], "returns": "sympy.Matrix", @@ -14688,7 +14422,7 @@ "name": "geo", "kind": "property", "file": "src/underworld3/coordinates.py", - "line": 2161, + "line": 2162, "signature": "(self)", "parameters": [], "returns": null, @@ -14710,7 +14444,7 @@ "name": "spherical", "kind": "property", "file": "src/underworld3/coordinates.py", - "line": 2212, + "line": 2213, "signature": "(self)", "parameters": [], "returns": null, @@ -14732,7 +14466,7 @@ "name": "rRotN", "kind": "property", "file": "src/underworld3/coordinates.py", - "line": 2264, + "line": 2265, "signature": "(self) -> sympy.Matrix", "parameters": [], "returns": "sympy.Matrix", @@ -14750,7 +14484,7 @@ "name": "xRotN", "kind": "property", "file": "src/underworld3/coordinates.py", - "line": 2273, + "line": 2274, "signature": "(self) -> sympy.Matrix", "parameters": [], "returns": "sympy.Matrix", @@ -14767,7 +14501,7 @@ "name": "geoRotN", "kind": "property", "file": "src/underworld3/coordinates.py", - "line": 2278, + "line": 2279, "signature": "(self) -> sympy.Matrix", "parameters": [], "returns": "sympy.Matrix", @@ -14784,7 +14518,7 @@ "name": "unit_e_0", "kind": "property", "file": "src/underworld3/coordinates.py", - "line": 2312, + "line": 2313, "signature": "(self) -> sympy.Matrix", "parameters": [], "returns": "sympy.Matrix", @@ -14801,7 +14535,7 @@ "name": "unit_e_1", "kind": "property", "file": "src/underworld3/coordinates.py", - "line": 2317, + "line": 2318, "signature": "(self) -> sympy.Matrix", "parameters": [], "returns": "sympy.Matrix", @@ -14818,7 +14552,7 @@ "name": "unit_e_2", "kind": "property", "file": "src/underworld3/coordinates.py", - "line": 2322, + "line": 2323, "signature": "(self) -> sympy.Matrix", "parameters": [], "returns": "sympy.Matrix", @@ -14835,7 +14569,7 @@ "name": "unit_i", "kind": "property", "file": "src/underworld3/coordinates.py", - "line": 2330, + "line": 2331, "signature": "(self) -> sympy.Matrix", "parameters": [], "returns": "sympy.Matrix", @@ -14852,7 +14586,7 @@ "name": "unit_j", "kind": "property", "file": "src/underworld3/coordinates.py", - "line": 2335, + "line": 2336, "signature": "(self) -> sympy.Matrix", "parameters": [], "returns": "sympy.Matrix", @@ -14869,7 +14603,7 @@ "name": "unit_k", "kind": "property", "file": "src/underworld3/coordinates.py", - "line": 2340, + "line": 2341, "signature": "(self) -> sympy.Matrix", "parameters": [], "returns": "sympy.Matrix", @@ -14886,7 +14620,7 @@ "name": "unit_ijk", "kind": "method", "file": "src/underworld3/coordinates.py", - "line": 2347, + "line": 2348, "signature": "(self, dirn) -> sympy.Matrix", "parameters": [ { @@ -14910,7 +14644,7 @@ "name": "unit_vertical", "kind": "property", "file": "src/underworld3/coordinates.py", - "line": 2356, + "line": 2357, "signature": "(self) -> sympy.Matrix", "parameters": [], "returns": "sympy.Matrix", @@ -14933,7 +14667,7 @@ "name": "unit_horizontal", "kind": "property", "file": "src/underworld3/coordinates.py", - "line": 2376, + "line": 2377, "signature": "(self) -> sympy.Matrix", "parameters": [], "returns": "sympy.Matrix", @@ -14956,7 +14690,7 @@ "name": "unit_horizontal_0", "kind": "property", "file": "src/underworld3/coordinates.py", - "line": 2392, + "line": 2393, "signature": "(self) -> sympy.Matrix", "parameters": [], "returns": "sympy.Matrix", @@ -14973,7 +14707,7 @@ "name": "unit_horizontal_1", "kind": "property", "file": "src/underworld3/coordinates.py", - "line": 2397, + "line": 2398, "signature": "(self) -> sympy.Matrix", "parameters": [], "returns": "sympy.Matrix", @@ -14994,7 +14728,7 @@ "name": "unit_radial", "kind": "property", "file": "src/underworld3/coordinates.py", - "line": 2414, + "line": 2415, "signature": "(self) -> sympy.Matrix", "parameters": [], "returns": "sympy.Matrix", @@ -15011,7 +14745,7 @@ "name": "unit_tangential", "kind": "property", "file": "src/underworld3/coordinates.py", - "line": 2429, + "line": 2430, "signature": "(self) -> sympy.Matrix", "parameters": [], "returns": "sympy.Matrix", @@ -15028,7 +14762,7 @@ "name": "unit_meridional", "kind": "property", "file": "src/underworld3/coordinates.py", - "line": 2442, + "line": 2443, "signature": "(self) -> sympy.Matrix", "parameters": [], "returns": "sympy.Matrix", @@ -15045,7 +14779,7 @@ "name": "unit_azimuthal", "kind": "property", "file": "src/underworld3/coordinates.py", - "line": 2452, + "line": 2453, "signature": "(self) -> sympy.Matrix", "parameters": [], "returns": "sympy.Matrix", @@ -15062,7 +14796,7 @@ "name": "geometric_dimension_names", "kind": "property", "file": "src/underworld3/coordinates.py", - "line": 2462, + "line": 2463, "signature": "(self) -> list", "parameters": [], "returns": "list", @@ -15079,7 +14813,7 @@ "name": "primary_directions", "kind": "property", "file": "src/underworld3/coordinates.py", - "line": 2479, + "line": 2480, "signature": "(self) -> dict", "parameters": [], "returns": "dict", @@ -15098,7 +14832,7 @@ "name": "create_line_sample", "kind": "method", "file": "src/underworld3/coordinates.py", - "line": 2527, + "line": 2528, "signature": "(self, start_point, direction_vector, length, num_points = 50)", "parameters": [ { @@ -15144,7 +14878,7 @@ "name": "create_profile_sample", "kind": "method", "file": "src/underworld3/coordinates.py", - "line": 2652, + "line": 2653, "signature": "(self, profile_type, **params)", "parameters": [ { @@ -15172,7 +14906,7 @@ "name": "zero_matrix", "kind": "method", "file": "src/underworld3/coordinates.py", - "line": 2911, + "line": 2912, "signature": "(self, shape)", "parameters": [ { @@ -16176,7 +15910,7 @@ "name": "lvec", "kind": "property", "file": "src/underworld3/discretisation/discretisation_mesh.py", - "line": 3004, + "line": 3003, "signature": "(self) -> PETSc.Vec", "parameters": [], "returns": "PETSc.Vec", @@ -16193,7 +15927,7 @@ "name": "register_remesh_hook", "kind": "method", "file": "src/underworld3/discretisation/discretisation_mesh.py", - "line": 3017, + "line": 3016, "signature": "(self, op)", "parameters": [ { @@ -16224,7 +15958,7 @@ "name": "unregister_remesh_hook", "kind": "method", "file": "src/underworld3/discretisation/discretisation_mesh.py", - "line": 3049, + "line": 3048, "signature": "(self, op)", "parameters": [ { @@ -16248,7 +15982,7 @@ "name": "ephemeral_coords", "kind": "method", "file": "src/underworld3/discretisation/discretisation_mesh.py", - "line": 3114, + "line": 3113, "signature": "(self)", "parameters": [], "returns": null, @@ -16266,7 +16000,7 @@ "name": "deform", "kind": "method", "file": "src/underworld3/discretisation/discretisation_mesh.py", - "line": 3133, + "line": 3132, "signature": "(self, new_coords)", "parameters": [ { @@ -16294,7 +16028,7 @@ "name": "access", "kind": "method", "file": "src/underworld3/discretisation/discretisation_mesh.py", - "line": 3386, + "line": 3385, "signature": "(self, *writeable_vars)", "parameters": [ { @@ -16319,7 +16053,7 @@ "name": "N", "kind": "property", "file": "src/underworld3/discretisation/discretisation_mesh.py", - "line": 3436, + "line": 3435, "signature": "(self) -> sympy.vector.CoordSys3D", "parameters": [], "returns": "sympy.vector.CoordSys3D", @@ -16336,7 +16070,7 @@ "name": "Gamma_N", "kind": "property", "file": "src/underworld3/discretisation/discretisation_mesh.py", - "line": 3456, + "line": 3455, "signature": "(self) -> sympy.Matrix", "parameters": [], "returns": "sympy.Matrix", @@ -16353,7 +16087,7 @@ "name": "Gamma", "kind": "property", "file": "src/underworld3/discretisation/discretisation_mesh.py", - "line": 3472, + "line": 3471, "signature": "(self) -> sympy.Matrix", "parameters": [], "returns": "sympy.Matrix", @@ -16370,7 +16104,7 @@ "name": "X", "kind": "property", "file": "src/underworld3/discretisation/discretisation_mesh.py", - "line": 3486, + "line": 3485, "signature": "(self)", "parameters": [], "returns": null, @@ -16390,7 +16124,7 @@ "name": "CoordinateSystem", "kind": "property", "file": "src/underworld3/discretisation/discretisation_mesh.py", - "line": 3514, + "line": 3513, "signature": "(self) -> CoordinateSystem", "parameters": [], "returns": "CoordinateSystem", @@ -16407,7 +16141,7 @@ "name": "t", "kind": "property", "file": "src/underworld3/discretisation/discretisation_mesh.py", - "line": 3519, + "line": 3518, "signature": "(self)", "parameters": [], "returns": null, @@ -16427,7 +16161,7 @@ "name": "nullspace_rotations", "kind": "property", "file": "src/underworld3/discretisation/discretisation_mesh.py", - "line": 3545, + "line": 3544, "signature": "(self)", "parameters": [], "returns": null, @@ -16447,7 +16181,7 @@ "name": "r", "kind": "property", "file": "src/underworld3/discretisation/discretisation_mesh.py", - "line": 3570, + "line": 3569, "signature": "(self) -> Tuple[sympy.vector.BaseScalar]", "parameters": [], "returns": "Tuple[sympy.vector.BaseScalar]", @@ -16464,7 +16198,7 @@ "name": "rvec", "kind": "property", "file": "src/underworld3/discretisation/discretisation_mesh.py", - "line": 3585, + "line": 3584, "signature": "(self) -> sympy.vector.Vector", "parameters": [], "returns": "sympy.vector.Vector", @@ -16481,7 +16215,7 @@ "name": "data", "kind": "property", "file": "src/underworld3/discretisation/discretisation_mesh.py", - "line": 3605, + "line": 3604, "signature": "(self) -> numpy.ndarray", "parameters": [], "returns": "numpy.ndarray", @@ -16499,7 +16233,7 @@ "name": "points", "kind": "property", "file": "src/underworld3/discretisation/discretisation_mesh.py", - "line": 3624, + "line": 3623, "signature": "(self)", "parameters": [], "returns": null, @@ -16519,7 +16253,7 @@ "name": "points", "kind": "method", "file": "src/underworld3/discretisation/discretisation_mesh.py", - "line": 3666, + "line": 3665, "signature": "(self, value)", "parameters": [ { @@ -16544,7 +16278,7 @@ "name": "physical_coordinates", "kind": "property", "file": "src/underworld3/discretisation/discretisation_mesh.py", - "line": 3685, + "line": 3684, "signature": "(self)", "parameters": [], "returns": null, @@ -16563,7 +16297,7 @@ "name": "physical_bounds", "kind": "property", "file": "src/underworld3/discretisation/discretisation_mesh.py", - "line": 3710, + "line": 3709, "signature": "(self)", "parameters": [], "returns": null, @@ -16580,7 +16314,7 @@ "name": "physical_extent", "kind": "property", "file": "src/underworld3/discretisation/discretisation_mesh.py", - "line": 3741, + "line": 3740, "signature": "(self)", "parameters": [], "returns": null, @@ -16597,7 +16331,7 @@ "name": "write_timestep", "kind": "method", "file": "src/underworld3/discretisation/discretisation_mesh.py", - "line": 3769, + "line": 3768, "signature": "(self, filename: str, index: int, outputPath: Optional[str] = '', meshVars: Optional[list] = [], swarmVars: Optional[list] = [], meshUpdates: bool = False, create_xdmf: bool = True, petsc_reload: bool = False)", "parameters": [ { @@ -16669,7 +16403,7 @@ "name": "petsc_save_checkpoint", "kind": "method", "file": "src/underworld3/discretisation/discretisation_mesh.py", - "line": 3903, + "line": 3902, "signature": "(self, index: int, meshVars: Optional[list] = [], outputPath: Optional[str] = '')", "parameters": [ { @@ -16711,7 +16445,7 @@ "name": "write_checkpoint", "kind": "method", "file": "src/underworld3/discretisation/discretisation_mesh.py", - "line": 4004, + "line": 4003, "signature": "(self, filename: str, outputPath: str = '', meshUpdates: bool = True, meshVars: Optional[list] = [], swarmVars: Optional[list] = [], index: Optional[int] = 0, unique_id: Optional[bool] = False, separate_variable_files: bool = True, create_xdmf: bool = False)", "parameters": [ { @@ -16785,7 +16519,7 @@ "name": "snapshot_payload", "kind": "method", "file": "src/underworld3/discretisation/discretisation_mesh.py", - "line": 4144, + "line": 4143, "signature": "(self) -> dict", "parameters": [], "returns": "dict", @@ -16807,7 +16541,7 @@ "name": "apply_snapshot_payload", "kind": "method", "file": "src/underworld3/discretisation/discretisation_mesh.py", - "line": 4177, + "line": 4176, "signature": "(self, payload: dict) -> None", "parameters": [ { @@ -16835,7 +16569,7 @@ "name": "write", "kind": "method", "file": "src/underworld3/discretisation/discretisation_mesh.py", - "line": 4241, + "line": 4240, "signature": "(self, filename: str, index: Optional[int] = None, petsc_format: Optional[bool] = None)", "parameters": [ { @@ -16877,7 +16611,7 @@ "name": "vtk", "kind": "method", "file": "src/underworld3/discretisation/discretisation_mesh.py", - "line": 4371, + "line": 4370, "signature": "(self, filename: str)", "parameters": [ { @@ -16901,7 +16635,7 @@ "name": "generate_xdmf", "kind": "method", "file": "src/underworld3/discretisation/discretisation_mesh.py", - "line": 4380, + "line": 4379, "signature": "(self, filename: str)", "parameters": [ { @@ -16925,7 +16659,7 @@ "name": "vars", "kind": "property", "file": "src/underworld3/discretisation/discretisation_mesh.py", - "line": 4402, + "line": 4401, "signature": "(self)", "parameters": [], "returns": null, @@ -16942,7 +16676,7 @@ "name": "block_vars", "kind": "property", "file": "src/underworld3/discretisation/discretisation_mesh.py", - "line": 4411, + "line": 4410, "signature": "(self)", "parameters": [], "returns": null, @@ -16959,7 +16693,7 @@ "name": "points_in_domain", "kind": "method", "file": "src/underworld3/discretisation/discretisation_mesh.py", - "line": 5078, + "line": 5077, "signature": "(self, points, strict_validation = True)", "parameters": [ { @@ -16995,7 +16729,7 @@ "name": "get_closest_cells", "kind": "method", "file": "src/underworld3/discretisation/discretisation_mesh.py", - "line": 5165, + "line": 5164, "signature": "(self, coords: numpy.ndarray) -> numpy.ndarray", "parameters": [ { @@ -17022,7 +16756,7 @@ "name": "test_if_points_in_cells", "kind": "method", "file": "src/underworld3/discretisation/discretisation_mesh.py", - "line": 5326, + "line": 5325, "signature": "(self, points, cells, on_boundary = True, tol = 0.0)", "parameters": [ { @@ -17068,7 +16802,7 @@ "name": "get_closest_local_cells", "kind": "method", "file": "src/underworld3/discretisation/discretisation_mesh.py", - "line": 5381, + "line": 5380, "signature": "(self, coords: numpy.ndarray, on_boundary: bool = True, tol: float = 0.0) -> numpy.ndarray", "parameters": [ { @@ -17106,7 +16840,7 @@ "name": "get_min_radius_old", "kind": "method", "file": "src/underworld3/discretisation/discretisation_mesh.py", - "line": 5575, + "line": 5574, "signature": "(self) -> float", "parameters": [], "returns": "float", @@ -17126,7 +16860,7 @@ "name": "get_min_radius", "kind": "method", "file": "src/underworld3/discretisation/discretisation_mesh.py", - "line": 5593, + "line": 5592, "signature": "(self) -> float", "parameters": [], "returns": "float", @@ -17146,7 +16880,7 @@ "name": "get_max_radius", "kind": "method", "file": "src/underworld3/discretisation/discretisation_mesh.py", - "line": 5610, + "line": 5609, "signature": "(self) -> float", "parameters": [], "returns": "float", @@ -17166,7 +16900,7 @@ "name": "get_mean_radius", "kind": "method", "file": "src/underworld3/discretisation/discretisation_mesh.py", - "line": 5625, + "line": 5624, "signature": "(self) -> float", "parameters": [], "returns": "float", @@ -17184,7 +16918,7 @@ "name": "stats", "kind": "method", "file": "src/underworld3/discretisation/discretisation_mesh.py", - "line": 5654, + "line": 5653, "signature": "(self, uw_function, uw_meshVariable, basis = None)", "parameters": [ { @@ -17224,7 +16958,7 @@ "name": "meshVariable_mask_from_label", "kind": "method", "file": "src/underworld3/discretisation/discretisation_mesh.py", - "line": 5690, + "line": 5689, "signature": "(self, label_name, label_value)", "parameters": [ { @@ -17254,7 +16988,7 @@ "name": "register_swarm", "kind": "method", "file": "src/underworld3/discretisation/discretisation_mesh.py", - "line": 5716, + "line": 5715, "signature": "(self, swarm)", "parameters": [ { @@ -17278,7 +17012,7 @@ "name": "unregister_swarm", "kind": "method", "file": "src/underworld3/discretisation/discretisation_mesh.py", - "line": 5720, + "line": 5719, "signature": "(self, swarm)", "parameters": [ { @@ -17304,7 +17038,7 @@ "name": "register_surface", "kind": "method", "file": "src/underworld3/discretisation/discretisation_mesh.py", - "line": 5725, + "line": 5724, "signature": "(self, surface)", "parameters": [ { @@ -17328,7 +17062,7 @@ "name": "unregister_surface", "kind": "method", "file": "src/underworld3/discretisation/discretisation_mesh.py", - "line": 5729, + "line": 5728, "signature": "(self, surface)", "parameters": [ { @@ -17352,7 +17086,7 @@ "name": "OT_adapt", "kind": "method", "file": "src/underworld3/discretisation/discretisation_mesh.py", - "line": 5744, + "line": 5743, "signature": "(self, field)", "parameters": [ { @@ -17377,7 +17111,7 @@ "name": "OT_adapt_reset_reference", "kind": "method", "file": "src/underworld3/discretisation/discretisation_mesh.py", - "line": 5883, + "line": 5882, "signature": "(self, coords = None)", "parameters": [ { @@ -17402,7 +17136,7 @@ "name": "adapt", "kind": "method", "file": "src/underworld3/discretisation/discretisation_mesh.py", - "line": 5899, + "line": 5898, "signature": "(self, metric_field, verbose = False)", "parameters": [ { @@ -17438,7 +17172,7 @@ "name": "meshVariable_lookup_by_symbol", "kind": "function", "file": "src/underworld3/discretisation/discretisation_mesh.py", - "line": 6517, + "line": 6516, "signature": "(mesh, sympy_object)", "parameters": [ { @@ -17469,7 +17203,7 @@ "name": "petsc_dm_find_labeled_points_local", "kind": "function", "file": "src/underworld3/discretisation/discretisation_mesh.py", - "line": 6534, + "line": 6533, "signature": "(dm, label_name, label_value, sectionIndex = False, verbose = False)", "parameters": [ { @@ -19726,7 +19460,7 @@ "name": "total_disp", "kind": "property", "file": "src/underworld3/discretisation/remesh.py", - "line": 127, + "line": 154, "signature": "(self) -> np.ndarray", "parameters": [], "returns": "np.ndarray", @@ -19743,7 +19477,7 @@ "name": "remesh_with_field_transfer", "kind": "function", "file": "src/underworld3/discretisation/remesh.py", - "line": 218, + "line": 274, "signature": "(mesh: 'Mesh', do_move: Callable[[], None]) -> bool", "parameters": [ { @@ -19766,7 +19500,7 @@ "reset+build+smooth pipeline once at the outer level; inner movers", "(smooth_mesh_interior called from inside that pipeline) consult", "this flag and skip their own wrap.", - "Surface the outer scratch dict so a nested do_move can still" + "Nested call: run the mover only. The OUTER wrapper owns" ], "status": "partial", "needs": [ @@ -19775,6 +19509,61 @@ "parent_class": null, "is_public": true }, + { + "name": "remap_var_set", + "kind": "function", + "file": "src/underworld3/discretisation/remesh.py", + "line": 452, + "signature": "(mesh, vars_, old_X, new_X, old_data)", + "parameters": [ + { + "name": "mesh", + "type_hint": null, + "default": null, + "description": "" + }, + { + "name": "vars_", + "type_hint": null, + "default": null, + "description": "" + }, + { + "name": "old_X", + "type_hint": null, + "default": null, + "description": "" + }, + { + "name": "new_X", + "type_hint": null, + "default": null, + "description": "" + }, + { + "name": "old_data", + "type_hint": null, + "default": null, + "description": "" + } + ], + "returns": null, + "existing_docstring": "One-shot REMAP dance for a set of variables.\n\nUsed by the generic per-variable pass in\n:func:`remesh_with_field_transfer`, and public so an operator's\n``on_remesh`` hook can force-REMAP its CARRY-managed vars on an\nadapt that is ALE-incompatible (e.g. an OT_adapt reset, where the\nlinear ``\u0394x/dt \u2192 v_mesh`` interpretation breaks down).\n\nContract: on entry the mesh is at ``new_X`` and each var's\n``.data`` may hold *either* the original snapshot value (CARRY:\noperator-managed vars that the generic pass skipped) or the\nnot-yet-restored value (REMAP: the snapshot has not been written\nback). ``old_data`` is the snapshot keyed by var, captured *before*\n``do_move`` ran. On exit the mesh is back at ``new_X`` and every\nvar's ``.data`` holds the OLD field evaluated at the var's NEW DOF\ncoordinates.\n\nThe set may be empty (no-op). Operations are MPI-collective; every\nrank must call with the same set.", + "harvested_comments": [ + "Capture target DOF coords on the NEW mesh first (we are sitting", + "on new_X right now). var.coords reads from the live mesh state.", + "Deform back to the old coords, restore data so global_evaluate", + "sees the old field, evaluate at each var's new DOF coords,", + "then deform forward and write the resampled values back." + ], + "status": "partial", + "needs": [ + "NEEDS_PARAMETERS", + "NEEDS_RETURNS" + ], + "parent_class": null, + "is_public": true + }, { "name": "with_units", "kind": "function", @@ -19941,7 +19730,7 @@ "name": "evaluate_nd", "kind": "function", "file": "src/underworld3/function/_function.pyx", - "line": 901, + "line": 900, "signature": "def evaluate_nd( expr,\n coords=None,\n coord_sys=None,\n other_arguments=None,\n simplify=True,\n verbose=False,\n evalf=False,\n rbf=False,\n data_layout=None,\n check_extrapolated=False,\n force_l2=False,\n smoothing=1e-6):", "parameters": [], "returns": null, @@ -19958,7 +19747,7 @@ "name": "petsc_interpolate", "kind": "function", "file": "src/underworld3/function/_function.pyx", - "line": 1091, + "line": 1090, "signature": "def petsc_interpolate( expr,\n np.ndarray coords=None,\n coord_sys=None,\n mesh=None,\n other_arguments=None,\n simplify=True,\n verbose=False, ):", "parameters": [], "returns": null, @@ -19975,7 +19764,7 @@ "name": "interpolate_vars_on_mesh", "kind": "method", "file": "src/underworld3/function/_function.pyx", - "line": 1222, + "line": 1221, "signature": "def interpolate_vars_on_mesh( varfns, np.ndarray coords ):", "parameters": [], "returns": null, @@ -19992,7 +19781,7 @@ "name": "rbf_evaluate", "kind": "function", "file": "src/underworld3/function/_function.pyx", - "line": 1381, + "line": 1380, "signature": "def rbf_evaluate( expr,\n coords=None,\n coord_sys=None,\n mesh=None,\n other_arguments=None,\n verbose=False,\n simplify=True,):", "parameters": [], "returns": null, @@ -20009,7 +19798,7 @@ "name": "dm_swarm_get_migrate_type", "kind": "function", "file": "src/underworld3/function/_function.pyx", - "line": 1503, + "line": 1502, "signature": "def dm_swarm_get_migrate_type(swarm):", "parameters": [], "returns": null, @@ -20024,7 +19813,7 @@ "name": "dm_swarm_set_migrate_type", "kind": "function", "file": "src/underworld3/function/_function.pyx", - "line": 1528, + "line": 1527, "signature": "def dm_swarm_set_migrate_type(swarm, mtype):", "parameters": [], "returns": null, @@ -21400,7 +21189,7 @@ "name": "evaluate", "kind": "function", "file": "src/underworld3/function/functions_unit_system.py", - "line": 825, + "line": 758, "signature": "(expr, coords, coord_sys = None, other_arguments = None, simplify = False, verbose = False, evalf = False, mode = 'default', data_layout = None, check_extrapolated = False, smoothing = 1e-06, rbf = None, force_l2 = None, monotone = False)", "parameters": [ { @@ -21489,15 +21278,15 @@ } ], "returns": null, - "existing_docstring": "Evaluate ``expr`` at ``coords`` with automatic unit handling.\n\nThin wrapper over :func:`_evaluate_impl`. See that function for the\nfull parameter documentation and evaluation-mode notes. With the\ndefault ``monotone=False`` this is bit-identical to the historical\n``evaluate``.\n\nCoordinates are a plain ``(N, dim)`` array in model (non-dimensional)\nunits, or a ``UnitAwareArray``/``UWQuantity`` array which is\nnon-dimensionalised automatically. Python lists/tuples of individual\nquantity objects (``[(x_qty, y_qty)]``) are NOT supported \u2014 convert\nphysical locations with :func:`underworld3.scaling.non_dimensionalise`\nand pass a numpy array (units-family ruling, 2026-07).\n\nParameters\n----------\nmonotone : bool or str, optional\n Opt-in bounded (monotone) interpolation, applied as a\n post-process to the computed result. ``False`` (default) \u2192 no\n limiting. ``True`` / ``\"clamp\"`` \u2192 clip the result into the\n ``[min, max]`` of the ``mesh.dim + 1`` nearest source-field DOFs.\n ``\"pick\"`` \u2192 keep in-bounds values and re-evaluate only the\n out-of-bounds subset via (bounded) RBF interpolation. Only\n single-MeshVariable expressions are supported; composites raise\n ``ValueError``. See :func:`_apply_monotone_limit`.", + "existing_docstring": "Evaluate ``expr`` at ``coords`` with automatic unit handling.\n\nWraps the compiled ``evaluate_nd`` machinery so unit conversion\n(dimensional coordinates in, unit-aware results out) happens\nautomatically. With the default ``monotone=False`` the result is\nbit-identical to the historical ``evaluate``.\n\nParameters\n----------\nexpr : sympy expression or UWexpression\n Expression to evaluate. All MeshVariable symbols in the\n expression must belong to the same mesh (``ValueError``\n otherwise \u2014 use ``var.copy_into()`` to transfer data between\n meshes first).\ncoords : numpy.ndarray or UnitAwareArray\n Coordinates at which to evaluate, shape ``(n_points, dim)``.\n A plain array is taken to be in model (non-dimensional) units;\n a ``UnitAwareArray`` / ``UWQuantity`` array (e.g. from\n ``mesh.X.coords``) is non-dimensionalised automatically.\n Python lists/tuples of individual quantity objects\n (``[(x_qty, y_qty)]``) are NOT supported and raise\n ``TypeError`` \u2014 convert physical locations with\n :func:`underworld3.scaling.non_dimensionalise` and pass a\n numpy array (units-family ruling, 2026-07).\ncoord_sys : mesh.N vector coordinate system, optional\n Coordinate system to evaluate in (default: the mesh's own).\nother_arguments : dict, optional\n Additional arguments passed through to the compiled evaluator.\nsimplify : bool, optional\n Sympy-simplify the expression before evaluation\n (default: False).\nverbose : bool, optional\n Verbose output (default: False).\nevalf : bool, optional\n Force numerical evaluation via sympy ``evalf``\n (default: False).\nmode : {\"default\", \"fast\", \"projection\"}, optional\n Accuracy / speed tradeoff. ``\"default\"`` \u2014 L2 projection for\n derivative terms, direct evaluation otherwise (DMInterp + RBF).\n ``\"fast\"`` \u2014 Clement gradient (no solve), RBF everywhere.\n ``\"projection\"`` \u2014 always L2 projection (a solve).\ndata_layout : callable, optional\n Data layout specification (default: None).\ncheck_extrapolated : bool, optional\n If True, also return a boolean mask flagging points whose\n value was extrapolated from outside the domain\n (default: False).\nsmoothing : float, optional\n Smoothing parameter for the L2 projection (dimensionless);\n only used when a projection path is active. Default: 1e-6.\nrbf : bool, optional\n Expert override: force RBF interpolation everywhere.\n Takes precedence over ``mode``.\nforce_l2 : bool, optional\n Expert override: force the L2 projection path.\n Takes precedence over ``mode``.\nmonotone : bool or str, optional\n Opt-in bounded (monotone) interpolation, applied as a\n post-process to the computed result. ``False`` (default) \u2192 no\n limiting. ``True`` / ``\"clamp\"`` \u2192 clip the result into the\n ``[min, max]`` of the ``mesh.dim + 1`` nearest source-field DOFs.\n ``\"pick\"`` \u2192 keep in-bounds values and re-evaluate only the\n out-of-bounds subset via (bounded) RBF interpolation. Only\n single-MeshVariable expressions are supported; composites raise\n ``ValueError``. See :func:`_apply_monotone_limit`.\n\nReturns\n-------\nUWQuantity, UnitAwareArray, or numpy.ndarray\n If non-dimensional scaling is active, a plain ndarray. If the\n expression carries units, a ``UWQuantity`` (scalar) or\n ``UnitAwareArray``. Otherwise a plain ndarray. With\n ``check_extrapolated=True``, a ``(values, extrapolated_mask)``\n pair.\n\nExamples\n--------\n>>> result = uw.function.evaluate(T.sym, T.coords) # dimensional coords\n>>> result = uw.function.evaluate(T.sym, mesh.X.coords[:, :2])\n>>> if hasattr(result, 'to'):\n... result_K = result.to('K') # unit conversion", "harvested_comments": [ "Expert overrides (override mode settings)", + "dimensional coords", + "unit conversion", "Validate up front so an unknown option fails fast (no wasted eval)." ], - "status": "partial", - "needs": [ - "NEEDS_RETURNS" - ], + "status": "complete", + "needs": [], "parent_class": null, "is_public": true }, @@ -21505,7 +21294,7 @@ "name": "global_evaluate", "kind": "function", "file": "src/underworld3/function/functions_unit_system.py", - "line": 903, + "line": 892, "signature": "(expr, coords = None, coord_sys = None, other_arguments = None, simplify = False, verbose = False, evalf = False, mode = 'default', data_layout = None, check_extrapolated = False, smoothing = 1e-06, rbf = None, force_l2 = None, monotone = False, local_fallback = True)", "parameters": [ { @@ -27808,7 +27597,7 @@ } ], "returns": "'MeshVariable'", - "existing_docstring": "Transfer surface normals to mesh points via nearest-neighbor.\n\nFor each mesh point, finds the closest surface face and copies\nthat face's normal vector.\n\nArgs:\n mesh: The mesh to transfer normals to\n coords: Optional coordinates to query. If None, uses mesh.data\n normal_var: Optional existing MeshVariable\n variable_name: Name for new variable\n\nReturns:\n MeshVariable with normal vectors (3 components)", + "existing_docstring": "Transfer surface normals to mesh points via nearest-neighbor.\n\nFor each mesh point, finds the closest surface face and copies\nthat face's normal vector.\n\nArgs:\n mesh: The mesh to transfer normals to\n coords: Optional coordinates to query. If None, uses the mesh's\n own vertex coordinates (model space)\n normal_var: Optional existing MeshVariable\n variable_name: Name for new variable\n\nReturns:\n MeshVariable with normal vectors (3 components)", "harvested_comments": [ "Ensure all surfaces are discretized", "Get query coordinates in model (internal) space", @@ -27825,7 +27614,7 @@ "name": "influence_function", "kind": "method", "file": "src/underworld3/meshing/surfaces.py", - "line": 2174, + "line": 2175, "signature": "(self, mesh: 'Mesh', width: float, value_near: Union[float, sympy.Expr] = 1.0, value_far: Union[float, sympy.Expr] = 0.0, profile: str = 'step') -> sympy.Expr", "parameters": [ { @@ -27871,7 +27660,7 @@ "name": "refinement_metric", "kind": "method", "file": "src/underworld3/meshing/surfaces.py", - "line": 2214, + "line": 2215, "signature": "(self, mesh: 'Mesh', h_near, h_far, width = None, profile: str = 'linear', variable_name: str = 'fault_metric') -> 'MeshVariable'", "parameters": [ { @@ -27925,7 +27714,7 @@ "name": "compute_nearest_fields", "kind": "method", "file": "src/underworld3/meshing/surfaces.py", - "line": 2266, + "line": 2267, "signature": "(self, mesh: 'Mesh', fault_width = None, normal_var_name: str = 'fault_n', id_var_name: str = 'fault_id', distance_var_name: str = 'd_faults', weight_var_name: str = 'fault_w') -> dict", "parameters": [ { @@ -27982,7 +27771,7 @@ "name": "create_weakness_function", "kind": "method", "file": "src/underworld3/meshing/surfaces.py", - "line": 2381, + "line": 2382, "signature": "(self, distance_var: 'MeshVariable', fault_width: float, eta_weak: float = 0.01, eta_background: float = 1.0) -> sympy.Expr", "parameters": [ { @@ -28022,7 +27811,7 @@ "name": "fault_metric_tensor", "kind": "function", "file": "src/underworld3/meshing/surfaces.py", - "line": 2484, + "line": 2485, "signature": "(mesh, faults, refinement = 3.0, width = 'auto', base = 1.0)", "parameters": [ { @@ -28072,7 +27861,7 @@ "name": "fault_comb_metric", "kind": "function", "file": "src/underworld3/meshing/surfaces.py", - "line": 2596, + "line": 2597, "signature": "(mesh, faults, cell_size, n_across = 4, amplitude = 6.0, tooth_width = None, combine = 'sum')", "parameters": [ { @@ -28133,7 +27922,7 @@ "name": "compose_metrics", "kind": "function", "file": "src/underworld3/meshing/surfaces.py", - "line": 2711, + "line": 2712, "signature": "(metrics, compose = 'max')", "parameters": [ { @@ -28163,7 +27952,7 @@ "name": "fault_metric", "kind": "function", "file": "src/underworld3/meshing/surfaces.py", - "line": 2836, + "line": 2837, "signature": "(mesh, faults, method = 'ma', **kwargs)", "parameters": [ { @@ -30272,7 +30061,7 @@ "name": "units", "kind": "property", "file": "src/underworld3/swarm.py", - "line": 366, + "line": 365, "signature": "(self)", "parameters": [], "returns": null, @@ -30289,7 +30078,7 @@ "name": "units", "kind": "method", "file": "src/underworld3/swarm.py", - "line": 371, + "line": 370, "signature": "(self, value)", "parameters": [ { @@ -30315,7 +30104,7 @@ "name": "has_units", "kind": "property", "file": "src/underworld3/swarm.py", - "line": 380, + "line": 379, "signature": "(self)", "parameters": [], "returns": null, @@ -30332,7 +30121,7 @@ "name": "use_legacy_array", "kind": "method", "file": "src/underworld3/swarm.py", - "line": 987, + "line": 986, "signature": "(self)", "parameters": [], "returns": null, @@ -30349,7 +30138,7 @@ "name": "use_enhanced_array", "kind": "method", "file": "src/underworld3/swarm.py", - "line": 991, + "line": 990, "signature": "(self)", "parameters": [], "returns": null, @@ -30366,7 +30155,7 @@ "name": "sync_disabled", "kind": "method", "file": "src/underworld3/swarm.py", - "line": 995, + "line": 994, "signature": "(self, description = 'batch operation')", "parameters": [ { @@ -30392,7 +30181,7 @@ "name": "pack_uw_data_to_petsc", "kind": "method", "file": "src/underworld3/swarm.py", - "line": 1285, + "line": 1283, "signature": "(self, data_array, sync = None)", "parameters": [ { @@ -30428,7 +30217,7 @@ "name": "unpack_uw_data_from_petsc", "kind": "method", "file": "src/underworld3/swarm.py", - "line": 1344, + "line": 1342, "signature": "(self, squeeze = True, sync = None)", "parameters": [ { @@ -30462,7 +30251,7 @@ "name": "pack_raw_data_to_petsc", "kind": "method", "file": "src/underworld3/swarm.py", - "line": 1381, + "line": 1379, "signature": "(self, data_array, sync = None)", "parameters": [ { @@ -30498,7 +30287,7 @@ "name": "unpack_raw_data_from_petsc", "kind": "method", "file": "src/underworld3/swarm.py", - "line": 1422, + "line": 1420, "signature": "(self, squeeze = True, sync = None)", "parameters": [ { @@ -30532,7 +30321,7 @@ "name": "rbf_interpolate", "kind": "method", "file": "src/underworld3/swarm.py", - "line": 1492, + "line": 1490, "signature": "(self, new_coords, verbose = False, nnn = None)", "parameters": [ { @@ -30572,7 +30361,7 @@ "name": "swarm", "kind": "property", "file": "src/underworld3/swarm.py", - "line": 1554, + "line": 1552, "signature": "(self)", "parameters": [], "returns": null, @@ -30589,7 +30378,7 @@ "name": "old_data", "kind": "property", "file": "src/underworld3/swarm.py", - "line": 1571, + "line": 1569, "signature": "(self)", "parameters": [], "returns": null, @@ -30606,7 +30395,7 @@ "name": "data", "kind": "property", "file": "src/underworld3/swarm.py", - "line": 1578, + "line": 1576, "signature": "(self)", "parameters": [], "returns": null, @@ -30629,7 +30418,7 @@ "name": "array", "kind": "property", "file": "src/underworld3/swarm.py", - "line": 1625, + "line": 1623, "signature": "(self)", "parameters": [], "returns": null, @@ -30652,7 +30441,7 @@ "name": "array", "kind": "method", "file": "src/underworld3/swarm.py", - "line": 1667, + "line": 1665, "signature": "(self, array_value)", "parameters": [ { @@ -30680,7 +30469,7 @@ "name": "sym", "kind": "property", "file": "src/underworld3/swarm.py", - "line": 1682, + "line": 1680, "signature": "(self)", "parameters": [], "returns": null, @@ -30699,7 +30488,7 @@ "name": "sym_1d", "kind": "property", "file": "src/underworld3/swarm.py", - "line": 1703, + "line": 1701, "signature": "(self)", "parameters": [], "returns": null, @@ -30718,7 +30507,7 @@ "name": "global_max", "kind": "method", "file": "src/underworld3/swarm.py", - "line": 1724, + "line": 1722, "signature": "(self, axis = None, out = None, keepdims = False)", "parameters": [ { @@ -30754,7 +30543,7 @@ "name": "global_min", "kind": "method", "file": "src/underworld3/swarm.py", - "line": 1762, + "line": 1760, "signature": "(self, axis = None, out = None, keepdims = False)", "parameters": [ { @@ -30788,7 +30577,7 @@ "name": "global_sum", "kind": "method", "file": "src/underworld3/swarm.py", - "line": 1799, + "line": 1797, "signature": "(self, axis = None, out = None, keepdims = False)", "parameters": [ { @@ -30822,7 +30611,7 @@ "name": "global_norm", "kind": "method", "file": "src/underworld3/swarm.py", - "line": 1834, + "line": 1832, "signature": "(self, ord = None)", "parameters": [ { @@ -30844,7 +30633,7 @@ "name": "global_size", "kind": "method", "file": "src/underworld3/swarm.py", - "line": 1867, + "line": 1865, "signature": "(self)", "parameters": [], "returns": null, @@ -30861,7 +30650,7 @@ "name": "save", "kind": "method", "file": "src/underworld3/swarm.py", - "line": 1896, + "line": 1894, "signature": "(self, filename: int, compression: Optional[bool] = False, compressionType: Optional[str] = 'gzip', force_sequential = False)", "parameters": [ { @@ -30905,11 +30694,89 @@ "parent_class": "SwarmVariable", "is_public": true }, + { + "name": "write_proxy", + "kind": "method", + "file": "src/underworld3/swarm.py", + "line": 2030, + "signature": "(self, filename: str)", + "parameters": [ + { + "name": "filename", + "type_hint": "str", + "default": null, + "description": "" + } + ], + "returns": null, + "existing_docstring": "Write this variable's proxy mesh variable to an HDF5 file.\n\nThe proxy is the RBF-interpolated mesh-variable image of the\nparticle data (built when the variable was created with\n``proxy_degree > 0``); this writes that mesh field via\n``MeshVariable.write``, which is often the most convenient\ncheckpoint/visualisation form of particle data.\n\nParameters\n----------\nfilename : str\n Output file path, passed directly to\n ``MeshVariable.write`` (conventionally ``*.h5``).\n\nNotes\n-----\nIf the variable has no proxy (``proxy_degree=0`` /\n``_proxy=False``), nothing is written; a message is printed and\nthe call returns.", + "harvested_comments": [ + "if not proxied, nothing to do. return." + ], + "status": "complete", + "needs": [], + "parent_class": "SwarmVariable", + "is_public": true + }, + { + "name": "read_timestep", + "kind": "method", + "file": "src/underworld3/swarm.py", + "line": 2061, + "signature": "(self, data_filename: str, swarmID: str, data_name: str, index: int, outputPath = '')", + "parameters": [ + { + "name": "data_filename", + "type_hint": "str", + "default": null, + "description": "" + }, + { + "name": "swarmID", + "type_hint": "str", + "default": null, + "description": "" + }, + { + "name": "data_name", + "type_hint": "str", + "default": null, + "description": "" + }, + { + "name": "index", + "type_hint": "int", + "default": null, + "description": "" + }, + { + "name": "outputPath", + "type_hint": null, + "default": "''", + "description": "" + } + ], + "returns": null, + "existing_docstring": "Restore this variable's values from a saved timestep.\n\nReads the checkpoint files written by ``Swarm.write_timestep``\nand maps the saved (coordinate, value) pairs onto the *current*\nparticles by nearest-neighbour interpolation \u2014 the live swarm\nneed not have the same particle count or positions as the saved\none.\n\nFilename convention (matching ``Swarm.write_timestep(\ndata_filename, swarmID, swarmVars=[...], outputPath=...,\nindex=...)``):\n\n* swarm coordinates:\n ``{outputPath}/{data_filename}.{swarmID}.{index:05}.h5``\n* this variable's data:\n ``{outputPath}/{data_filename}.{swarmID}.{data_name}.{index:05}.h5``\n\nBoth files must exist (``RuntimeError`` otherwise).\n\nParameters\n----------\ndata_filename : str\n Base name used when the checkpoint was written. (Note: the\n corresponding parameter on ``Swarm.read_timestep`` is\n spelled ``base_filename`` \u2014 the two signatures predate a\n common convention.)\nswarmID : str\n Swarm identifier used when the checkpoint was written\n (``swarm_id`` on ``Swarm.read_timestep``).\ndata_name : str\n The saved variable's ``name`` (``Swarm.write_timestep``\n embeds each variable's ``.name`` in its data filename).\nindex : int\n Timestep index (zero-padded to five digits in the\n filename).\noutputPath : str, optional\n Directory holding the checkpoint files (default: current\n directory).\n\nNotes\n-----\nMPI-collective. Rank 0 reads the saved data in one shot; the\nsaved points are then routed to their owning ranks with the\nsame migration rule the live swarm uses, so the rank-local\nnearest-neighbour lookup always sees the correct neighbours.", + "harvested_comments": [ + "mesh.write_timestep( \"test\", meshUpdates=False, meshVars=[X], outputPath=\"\", index=0)", + "swarm.write_timestep(\"test\", \"swarm\", swarmVars=[var], outputPath=\"\", index=0)", + "check if swarmFilename exists", + "easier to debug abs path", + "Memory-bounded parallel read. Rank 0 reads the saved file in one" + ], + "status": "partial", + "needs": [ + "NEEDS_RETURNS" + ], + "parent_class": "SwarmVariable", + "is_public": true + }, { "name": "sym", "kind": "property", "file": "src/underworld3/swarm.py", - "line": 2301, + "line": 2365, "signature": "(self)", "parameters": [], "returns": null, @@ -30927,7 +30794,7 @@ "name": "sym_1d", "kind": "property", "file": "src/underworld3/swarm.py", - "line": 2313, + "line": 2377, "signature": "(self)", "parameters": [], "returns": null, @@ -30944,7 +30811,7 @@ "name": "createMask", "kind": "method", "file": "src/underworld3/swarm.py", - "line": 2337, + "line": 2401, "signature": "(self, funcsList)", "parameters": [ { @@ -30970,7 +30837,7 @@ "name": "viewMask", "kind": "method", "file": "src/underworld3/swarm.py", - "line": 2385, + "line": 2449, "signature": "(self, expr)", "parameters": [ { @@ -30998,7 +30865,7 @@ "name": "visMask", "kind": "method", "file": "src/underworld3/swarm.py", - "line": 2420, + "line": 2484, "signature": "(self)", "parameters": [], "returns": null, @@ -31017,7 +30884,7 @@ "name": "view", "kind": "method", "file": "src/underworld3/swarm.py", - "line": 2445, + "line": 2509, "signature": "(self)", "parameters": [], "returns": null, @@ -31034,7 +30901,7 @@ "name": "mesh", "kind": "property", "file": "src/underworld3/swarm.py", - "line": 3009, + "line": 3073, "signature": "(self)", "parameters": [], "returns": null, @@ -31051,7 +30918,7 @@ "name": "mesh", "kind": "method", "file": "src/underworld3/swarm.py", - "line": 3017, + "line": 3081, "signature": "(self, new_mesh)", "parameters": [ { @@ -31081,7 +30948,7 @@ "name": "local_size", "kind": "property", "file": "src/underworld3/swarm.py", - "line": 3092, + "line": 3156, "signature": "(self)", "parameters": [], "returns": null, @@ -31098,7 +30965,7 @@ "name": "data", "kind": "property", "file": "src/underworld3/swarm.py", - "line": 3109, + "line": 3173, "signature": "(self)", "parameters": [], "returns": null, @@ -31115,7 +30982,7 @@ "name": "points", "kind": "property", "file": "src/underworld3/swarm.py", - "line": 3123, + "line": 3187, "signature": "(self)", "parameters": [], "returns": null, @@ -31138,7 +31005,7 @@ "name": "points", "kind": "method", "file": "src/underworld3/swarm.py", - "line": 3234, + "line": 3298, "signature": "(self, value)", "parameters": [ { @@ -31166,7 +31033,7 @@ "name": "coords", "kind": "property", "file": "src/underworld3/swarm.py", - "line": 3293, + "line": 3357, "signature": "(self)", "parameters": [], "returns": null, @@ -31189,7 +31056,7 @@ "name": "coords", "kind": "method", "file": "src/underworld3/swarm.py", - "line": 3343, + "line": 3407, "signature": "(self, value)", "parameters": [ { @@ -31216,7 +31083,7 @@ "name": "units", "kind": "property", "file": "src/underworld3/swarm.py", - "line": 3367, + "line": 3431, "signature": "(self)", "parameters": [], "returns": null, @@ -31239,7 +31106,7 @@ "name": "clip_to_mesh", "kind": "property", "file": "src/underworld3/swarm.py", - "line": 3410, + "line": 3474, "signature": "(self)", "parameters": [], "returns": null, @@ -31256,7 +31123,7 @@ "name": "clip_to_mesh", "kind": "method", "file": "src/underworld3/swarm.py", - "line": 3431, + "line": 3495, "signature": "(self, value)", "parameters": [ { @@ -31280,7 +31147,7 @@ "name": "dont_clip_to_mesh", "kind": "method", "file": "src/underworld3/swarm.py", - "line": 3435, + "line": 3499, "signature": "(self)", "parameters": [], "returns": null, @@ -31300,7 +31167,7 @@ "name": "migration_disabled", "kind": "method", "file": "src/underworld3/swarm.py", - "line": 3463, + "line": 3527, "signature": "(self)", "parameters": [], "returns": null, @@ -31322,7 +31189,7 @@ "name": "migration_control", "kind": "method", "file": "src/underworld3/swarm.py", - "line": 3483, + "line": 3547, "signature": "(self, disable = False)", "parameters": [ { @@ -31352,7 +31219,7 @@ "name": "populate", "kind": "method", "file": "src/underworld3/swarm.py", - "line": 3549, + "line": 3613, "signature": "(self, fill_param: Optional[int] = 1)", "parameters": [ { @@ -31382,7 +31249,7 @@ "name": "migrate", "kind": "method", "file": "src/underworld3/swarm.py", - "line": 3615, + "line": 3679, "signature": "(self, remove_sent_points = True, delete_lost_points = None, max_its = 10)", "parameters": [ { @@ -31425,7 +31292,7 @@ "name": "add_particles_with_coordinates", "kind": "method", "file": "src/underworld3/swarm.py", - "line": 3811, + "line": 3875, "signature": "(self, coordinatesArray) -> int", "parameters": [ { @@ -31453,7 +31320,7 @@ "name": "add_particles_with_global_coordinates", "kind": "method", "file": "src/underworld3/swarm.py", - "line": 3885, + "line": 3949, "signature": "(self, globalCoordinatesArray, migrate = True, delete_lost_points = True) -> int", "parameters": [ { @@ -31493,7 +31360,7 @@ "name": "save", "kind": "method", "file": "src/underworld3/swarm.py", - "line": 3982, + "line": 4046, "signature": "(self, filename: int, compression: Optional[bool] = False, compressionType: Optional[str] = 'gzip', force_sequential = False)", "parameters": [ { @@ -31537,11 +31404,65 @@ "parent_class": "Swarm", "is_public": true }, + { + "name": "read_timestep", + "kind": "method", + "file": "src/underworld3/swarm.py", + "line": 4201, + "signature": "(self, base_filename: str, swarm_id: str, index: int, outputPath: Optional[str] = '', migrate = True)", + "parameters": [ + { + "name": "base_filename", + "type_hint": "str", + "default": null, + "description": "" + }, + { + "name": "swarm_id", + "type_hint": "str", + "default": null, + "description": "" + }, + { + "name": "index", + "type_hint": "int", + "default": null, + "description": "" + }, + { + "name": "outputPath", + "type_hint": "Optional[str]", + "default": "''", + "description": "" + }, + { + "name": "migrate", + "type_hint": null, + "default": "True", + "description": "" + } + ], + "returns": null, + "existing_docstring": "Restore the swarm's particle coordinates from a saved timestep.\n\nAdds particles at the coordinates saved by\n``Swarm.write_timestep``; call this on a freshly-built swarm\n*before* restoring variable values with\n``SwarmVariable.read_timestep``. File read (matching\n``write_timestep(filename, swarmname, index, outputPath=...)``):\n\n``{outputPath}/{base_filename}.{swarm_id}.{index:05}.h5``\n\nParameters\n----------\nbase_filename : str\n Base name used when the checkpoint was written\n (``filename`` on ``write_timestep``; note\n ``SwarmVariable.read_timestep`` spells it\n ``data_filename`` \u2014 the two signatures predate a common\n convention).\nswarm_id : str\n Swarm identifier used when the checkpoint was written\n (``swarmname`` on ``write_timestep``).\nindex : int\n Timestep index (zero-padded to five digits in the\n filename).\noutputPath : str, optional\n Directory holding the checkpoint files (default: current\n directory).\nmigrate : bool, optional\n ``True`` (default): every rank reads the saved coordinates\n and keeps only the points it owns \u2014 the parallel restore\n path. ``False``: every rank keeps a full copy of the saved\n swarm, including points outside the local (or entire)\n domain \u2014 useful for debugging, visualisation, or when the\n mesh has been adapted since the save.", + "harvested_comments": [ + "Keep-local restore: every rank reads the saved coordinates", + "(plain read-only h5py) and add_particles_with_coordinates", + "keeps only the points this rank owns \u2014 no communication, no", + "rank-0 memory hotspot. The cost is np-fold read amplification,", + "which scalable/striped parallel filesystems absorb, so this is" + ], + "status": "partial", + "needs": [ + "NEEDS_RETURNS" + ], + "parent_class": "Swarm", + "is_public": true + }, { "name": "add_variable", "kind": "method", "file": "src/underworld3/swarm.py", - "line": 4176, + "line": 4275, "signature": "(self, name, size = 1, dtype = float, proxy_degree = 2, _nn_proxy = False, units = None)", "parameters": [ { @@ -31598,7 +31519,7 @@ "name": "petsc_save_checkpoint", "kind": "method", "file": "src/underworld3/swarm.py", - "line": 4253, + "line": 4352, "signature": "(self, swarmName: str, index: int, outputPath: Optional[str] = '')", "parameters": [ { @@ -31634,7 +31555,7 @@ "name": "write_timestep", "kind": "method", "file": "src/underworld3/swarm.py", - "line": 4277, + "line": 4376, "signature": "(self, filename: str, swarmname: str, index: int, swarmVars: Optional[list] = None, outputPath: Optional[str] = '', time: Optional[int] = None, compression: Optional[bool] = False, compressionType: Optional[str] = 'gzip', force_sequential: Optional[bool] = False)", "parameters": [ { @@ -31712,7 +31633,7 @@ "name": "vars", "kind": "property", "file": "src/underworld3/swarm.py", - "line": 4427, + "line": 4526, "signature": "(self)", "parameters": [], "returns": null, @@ -31729,7 +31650,7 @@ "name": "snapshot_payload", "kind": "method", "file": "src/underworld3/swarm.py", - "line": 4450, + "line": 4549, "signature": "(self) -> dict", "parameters": [], "returns": "dict", @@ -31747,7 +31668,7 @@ "name": "apply_snapshot_payload", "kind": "method", "file": "src/underworld3/swarm.py", - "line": 4480, + "line": 4579, "signature": "(self, payload: dict) -> None", "parameters": [ { @@ -31778,7 +31699,7 @@ "name": "access", "kind": "method", "file": "src/underworld3/swarm.py", - "line": 4738, + "line": 4696, "signature": "(self, *writeable_vars)", "parameters": [ { @@ -31799,11 +31720,75 @@ "parent_class": "Swarm", "is_public": true }, + { + "name": "advection", + "kind": "method", + "file": "src/underworld3/swarm.py", + "line": 4797, + "signature": "(self, V_fn, delta_t, order = 2, corrector = False, restore_points_to_domain_func = None, evalf = False, step_limit = False)", + "parameters": [ + { + "name": "V_fn", + "type_hint": null, + "default": null, + "description": "" + }, + { + "name": "delta_t", + "type_hint": null, + "default": null, + "description": "" + }, + { + "name": "order", + "type_hint": null, + "default": "2", + "description": "" + }, + { + "name": "corrector", + "type_hint": null, + "default": "False", + "description": "" + }, + { + "name": "restore_points_to_domain_func", + "type_hint": null, + "default": "None", + "description": "" + }, + { + "name": "evalf", + "type_hint": null, + "default": "False", + "description": "" + }, + { + "name": "step_limit", + "type_hint": null, + "default": "False", + "description": "" + } + ], + "returns": null, + "existing_docstring": "Advect the particle swarm through one timestep of a velocity field.\n\nParticle positions are updated with an explicit Runge-Kutta step\nof :math:`\\dot{\\mathbf{x}} = \\mathbf{V}(\\mathbf{x})`. Velocity\nis sampled with a *global* evaluation (off-rank sample points\nare resolved collectively), so the call is MPI-collective: every\nrank must make it, including ranks holding no particles. On\ncompletion the swarm is migrated so each particle lands on the\nrank owning its new location; particles that leave the domain\nare removed (unless ``restore_points_to_domain_func`` or the\nmesh's own ``return_coords_to_bounds`` returns them).\n\nParameters\n----------\nV_fn : vector UW function / sympy expression\n Velocity field, evaluated at particle locations. Any\n expression accepted by :func:`uw.function.evaluate`,\n e.g. ``stokes.u.sym``.\ndelta_t : float or UWQuantity\n Timestep. Non-dimensionalised internally\n (``uw.scaling.non_dimensionalise``), so a dimensional time\n (e.g. ``uw.quantity(1000, \"year\")``) is valid when scaling\n is active; a plain float is taken to be in model units,\n consistent with the model-unit velocity.\norder : int, optional\n Runge-Kutta order: ``2`` (default) is the midpoint scheme;\n any other value falls back to first-order forward Euler.\ncorrector : bool, optional\n Historical predictor-corrector option; currently inert (the\n corrector block is disabled). Retained for call\n compatibility. Default ``False``.\nrestore_points_to_domain_func : callable, optional\n Maps an ``(n, dim)`` coordinate array back into the domain\n (periodic wrap, boundary projection, ...). Applied to the\n updated positions each substep, in addition to the mesh's\n own ``return_coords_to_bounds``.\nevalf : bool, optional\n Historical flag selecting RBF (``evalf``) velocity\n sampling; currently inert \u2014 velocity is always sampled with\n ``uw.function.global_evaluate``. Default ``False``.\nstep_limit : bool, optional\n If ``True``, split ``delta_t`` into substeps no larger than\n :meth:`estimate_dt` (roughly one element crossing per\n substep). Default ``False`` here; note\n :meth:`NodalPointSwarm.advection` defaults it to ``True``.", + "harvested_comments": [ + "Convert delta_t to model units if it has units", + "This ensures consistent arithmetic: velocity is in model units, so time must be too", + "X0 holds the particle location at the start of advection", + "This is needed because the particles may be migrated off-proc", + "during timestepping. Probably not needed - use global evaluation instead" + ], + "status": "complete", + "needs": [], + "parent_class": "Swarm", + "is_public": true + }, { "name": "estimate_dt", "kind": "method", "file": "src/underworld3/swarm.py", - "line": 5015, + "line": 5019, "signature": "(self, V_fn)", "parameters": [ { @@ -31829,6 +31814,66 @@ "parent_class": "Swarm", "is_public": true }, + { + "name": "advection", + "kind": "method", + "file": "src/underworld3/swarm.py", + "line": 5194, + "signature": "(self, V_fn, delta_t, order = 2, corrector = False, restore_points_to_domain_func = None, evalf = False, step_limit = True)", + "parameters": [ + { + "name": "V_fn", + "type_hint": null, + "default": null, + "description": "" + }, + { + "name": "delta_t", + "type_hint": null, + "default": null, + "description": "" + }, + { + "name": "order", + "type_hint": null, + "default": "2", + "description": "" + }, + { + "name": "corrector", + "type_hint": null, + "default": "False", + "description": "" + }, + { + "name": "restore_points_to_domain_func", + "type_hint": null, + "default": "None", + "description": "" + }, + { + "name": "evalf", + "type_hint": null, + "default": "False", + "description": "" + }, + { + "name": "step_limit", + "type_hint": null, + "default": "True", + "description": "" + } + ], + "returns": null, + "existing_docstring": "Advect the nodal-point swarm one timestep (semi-Lagrangian sweep).\n\nRecords each particle's launch point (its home mesh node) and\norigin rank, then delegates to :meth:`Swarm.advection`. The\nrecorded launch data is what lets semi-Lagrangian schemes return\nsampled values to the node the particle departed from after the\n(possibly off-rank) trajectory.\n\nParameters are those of :meth:`Swarm.advection`, with one\ndifference: ``step_limit`` defaults to ``True`` \u2014 trajectories\nare substepped to at most ~one element crossing per substep\n(see :meth:`Swarm.estimate_dt`), which keeps the node-return\nbookkeeping robust for large ``delta_t``.", + "harvested_comments": [], + "status": "partial", + "needs": [ + "NEEDS_RETURNS" + ], + "parent_class": "NodalPointSwarm", + "is_public": true + }, { "name": "state", "kind": "property", @@ -34206,7 +34251,7 @@ } ], "returns": "bool", - "existing_docstring": "Check if multiple expressions have consistent units for addition/comparison.\n\nThis function validates that all provided expressions have the same dimensionality,\nwhich is required for addition, subtraction, and comparison operations.\n\nArgs:\n *expressions: Any number of expressions, quantities, or unit-aware objects\n\nReturns:\n bool: True if all expressions have consistent units, False otherwise\n\nRaises:\n DimensionalityError: If expressions have inconsistent units\n NoUnitsError: If some expressions have units and others don't\n\nExamples:\n >>> velocity1 = EnhancedMeshVariable(\"v1\", mesh, 2, units=\"m/s\")\n >>> velocity2 = EnhancedMeshVariable(\"v2\", mesh, 2, units=\"km/h\")\n >>> pressure = EnhancedMeshVariable(\"p\", mesh, 1, units=\"Pa\")\n\n >>> check_units_consistency(velocity1, velocity2) # True - both velocities\n >>> check_units_consistency(velocity1, pressure) # False - different dimensions", + "existing_docstring": "Check if multiple expressions have consistent units for addition/comparison.\n\nThis function validates that all provided expressions have the same dimensionality,\nwhich is required for addition, subtraction, and comparison operations.\n\nParameters\n----------\n*expressions :\n Any number of expressions, quantities, or unit-aware objects\n\nReturns\n-------\nbool\n True if all expressions have consistent units, False otherwise\n\nRaises\n------\nDimensionalityError\n If expressions have inconsistent units\nNoUnitsError\n If some expressions have units and others don't\n\nExamples\n--------\n>>> velocity1 = EnhancedMeshVariable(\"v1\", mesh, 2, units=\"m/s\")\n>>> velocity2 = EnhancedMeshVariable(\"v2\", mesh, 2, units=\"km/h\")\n>>> pressure = EnhancedMeshVariable(\"p\", mesh, 1, units=\"Pa\")\n\n>>> check_units_consistency(velocity1, velocity2) # True - both velocities\n>>> check_units_consistency(velocity1, pressure) # False - different dimensions", "harvested_comments": [ "True - both velocities", "False - different dimensions", @@ -34223,7 +34268,7 @@ "name": "get_dimensionality", "kind": "function", "file": "src/underworld3/units.py", - "line": 567, + "line": 575, "signature": "(expression) -> Optional[Any]", "parameters": [ { @@ -34234,7 +34279,7 @@ } ], "returns": "Optional[Any]", - "existing_docstring": "Get the dimensionality of an expression or quantity.\n\nArgs:\n expression: Expression, quantity, or unit-aware object\n\nReturns:\n Dimensionality representation (backend-specific) or None if no units\n\nExamples:\n >>> velocity = EnhancedMeshVariable(\"velocity\", mesh, 2, units=\"m/s\")\n >>> dims = get_dimensionality(velocity)\n >>> print(dims) # [length] / [time]", + "existing_docstring": "Get the dimensionality of an expression or quantity.\n\nParameters\n----------\nexpression :\n Expression, quantity, or unit-aware object\n\nReturns\n-------\nDimensionality representation (backend-specific) or None if no units\n\nExamples\n--------\n>>> velocity = EnhancedMeshVariable(\"velocity\", mesh, 2, units=\"m/s\")\n>>> dims = get_dimensionality(velocity)\n>>> print(dims) # [length] / [time]", "harvested_comments": [ "[length] / [time]" ], @@ -34247,7 +34292,7 @@ "name": "get_units", "kind": "function", "file": "src/underworld3/units.py", - "line": 591, + "line": 603, "signature": "(expression, simplify: bool = False) -> Optional[Any]", "parameters": [ { @@ -34264,7 +34309,7 @@ } ], "returns": "Optional[Any]", - "existing_docstring": "Get the units of an expression or quantity.\n\nThis is the unified, public API for extracting units from any object type\n(variables, quantities, SymPy expressions, etc.). It replaces the previous\n`units_of()` function and the internal `function.unit_conversion.get_units()`\nfor a clean, single API surface.\n\nIMPORTANT: This function ALWAYS returns Pint Unit objects (or None), never strings.\nWe accept strings for INPUT (user convenience), but always return Pint objects.\n\nArgs:\n expression: Expression, quantity, or unit-aware object\n simplify: If True, simplify mixed units to base SI (default False).\n\nReturns:\n Pint Unit object or None if no units\n\nExamples:\n >>> velocity = uw.discretisation.MeshVariable(\"velocity\", mesh, 2, units=\"m/s\")\n >>> units = uw.get_units(velocity)\n >>> print(units) # \n\n >>> # Mixed units from composite expressions\n >>> th2 = uw.expression(\"th2\", ((2 * kappa * t_now))**0.5)\n >>> uw.get_units(th2) # megayear ** 0.5 * meter / second ** 0.5\n >>> uw.get_units(th2, simplify=True) # meter (simplified!)", + "existing_docstring": "Get the units of an expression or quantity.\n\nThis is the unified, public API for extracting units from any object type\n(variables, quantities, SymPy expressions, etc.). It replaces the previous\n`units_of()` function and the internal `function.unit_conversion.get_units()`\nfor a clean, single API surface.\n\nIMPORTANT: This function ALWAYS returns Pint Unit objects (or None), never strings.\nWe accept strings for INPUT (user convenience), but always return Pint objects.\n\nParameters\n----------\nexpression :\n Expression, quantity, or unit-aware object\nsimplify : bool, default=False\n If True, simplify mixed units to base SI (default False).\n\nReturns\n-------\npint.Unit or None\n Pint Unit object or None if no units\n\nExamples\n--------\n>>> velocity = uw.discretisation.MeshVariable(\"velocity\", mesh, 2, units=\"m/s\")\n>>> units = uw.get_units(velocity)\n>>> print(units) # \n\n>>> # Mixed units from composite expressions\n>>> th2 = uw.expression(\"th2\", ((2 * kappa * t_now))**0.5)\n>>> uw.get_units(th2) # megayear ** 0.5 * meter / second ** 0.5\n>>> uw.get_units(th2, simplify=True) # meter (simplified!)", "harvested_comments": [ "", "Mixed units from composite expressions", @@ -34281,7 +34326,7 @@ "name": "non_dimensionalise", "kind": "function", "file": "src/underworld3/units.py", - "line": 643, + "line": 661, "signature": "(expression, model = None) -> Any", "parameters": [ { @@ -34298,7 +34343,7 @@ } ], "returns": "Any", - "existing_docstring": "Convert expression to non-dimensional form using model reference scales.\n\nThis function uses dimensional analysis to compute appropriate scaling factors\nfrom the model's reference quantities, then divides the expression by those\nscales to produce dimensionless values. Dimensionality information is preserved\nto enable re-dimensionalization.\n\nProtocol-based approach works with:\n- MeshVariable/SwarmVariable (via .non_dimensional_value() method)\n- UWQuantity objects (extracts dimensionality, computes scale)\n- UnitAwareArray (extracts dimensionality from units)\n- Plain numbers (pass through unchanged)\n\nArgs:\n expression: Expression, quantity, or unit-aware object to non-dimensionalise\n model: Model instance with reference quantities (uses default if None)\n\nReturns:\n Non-dimensional value(s) with preserved dimensionality metadata\n\nRaises:\n NoUnitsError: If expression has no units and model has reference quantities\n ValueError: If model has no reference quantities\n\nExamples:\n >>> # With variables (uses existing method)\n >>> velocity_var = MeshVariable(\"v\", mesh, 2, units=\"m/s\")\n >>> nondim_v = non_dimensionalise(velocity_var)\n\n >>> # With UWQuantity\n >>> velocity_qty = uw.quantity(5.0, \"cm/year\")\n >>> nondim_qty = non_dimensionalise(velocity_qty, model)\n >>> # Result is dimensionless but remembers it was velocity\n\n >>> # With plain number (no model reference quantities)\n >>> plain_value = 2.5\n >>> result = non_dimensionalise(plain_value) # Returns 2.5", + "existing_docstring": "Convert expression to non-dimensional form using model reference scales.\n\nThis function uses dimensional analysis to compute appropriate scaling factors\nfrom the model's reference quantities, then divides the expression by those\nscales to produce dimensionless values. Dimensionality information is preserved\nto enable re-dimensionalization.\n\nProtocol-based approach works with:\n- MeshVariable/SwarmVariable (via .non_dimensional_value() method)\n- UWQuantity objects (extracts dimensionality, computes scale)\n- UnitAwareArray (extracts dimensionality from units)\n- Plain numbers (pass through unchanged)\n\nParameters\n----------\nexpression :\n Expression, quantity, or unit-aware object to non-dimensionalise\nmodel : Model, optional\n Model instance with reference quantities (uses default if None)\n\nReturns\n-------\nNon-dimensional value(s) with preserved dimensionality metadata\n\nRaises\n------\nNoUnitsError\n If expression has no units and model has reference quantities\nValueError\n If model has no reference quantities\n\nExamples\n--------\n>>> # With variables (uses existing method)\n>>> velocity_var = MeshVariable(\"v\", mesh, 2, units=\"m/s\")\n>>> nondim_v = non_dimensionalise(velocity_var)\n\n>>> # With UWQuantity\n>>> velocity_qty = uw.quantity(5.0, \"cm/year\")\n>>> nondim_qty = non_dimensionalise(velocity_qty, model)\n>>> # Result is dimensionless but remembers it was velocity\n\n>>> # With plain number (no model reference quantities)\n>>> plain_value = 2.5\n>>> result = non_dimensionalise(plain_value) # Returns 2.5", "harvested_comments": [ "With variables (uses existing method)", "With UWQuantity", @@ -34315,7 +34360,7 @@ "name": "show_nondimensional_form", "kind": "function", "file": "src/underworld3/units.py", - "line": 887, + "line": 913, "signature": "(expression, model = None)", "parameters": [ { @@ -34332,7 +34377,7 @@ } ], "returns": null, - "existing_docstring": "Display the non-dimensionalized form of a complex expression.\n\nThis function unwraps the expression (expanding UW wrappers to SymPy),\napplies non-dimensional scaling, and returns the result for inspection.\nUseful for seeing what will actually be compiled into C code when\nscaling is active.\n\nArgs:\n expression: Any SymPy expression, UW expression, or variable\n model: Model instance with reference quantities (uses default if None)\n\nReturns:\n SymPy expression with non-dimensional scaling applied\n\nExamples:\n >>> # See what the Stokes flux looks like non-dimensionally\n >>> flux = stokes.constitutive_model.flux\n >>> nondim_flux = uw.show_nondimensional_form(flux)\n >>> print(nondim_flux) # Should show values close to 1.0, not 1e21\n\n >>> # Check a parameter\n >>> viscosity = model.Parameters.shear_viscosity_0\n >>> print(uw.show_nondimensional_form(viscosity)) # Should be ~1.0", + "existing_docstring": "Display the non-dimensionalized form of a complex expression.\n\nThis function unwraps the expression (expanding UW wrappers to SymPy),\napplies non-dimensional scaling, and returns the result for inspection.\nUseful for seeing what will actually be compiled into C code when\nscaling is active.\n\nParameters\n----------\nexpression :\n Any SymPy expression, UW expression, or variable\nmodel : Model, optional\n Model instance with reference quantities (uses default if None)\n\nReturns\n-------\nSymPy expression with non-dimensional scaling applied\n\nExamples\n--------\n>>> # See what the Stokes flux looks like non-dimensionally\n>>> flux = stokes.constitutive_model.flux\n>>> nondim_flux = uw.show_nondimensional_form(flux)\n>>> print(nondim_flux) # Should show values close to 1.0, not 1e21\n\n>>> # Check a parameter\n>>> viscosity = model.Parameters.shear_viscosity_0\n>>> print(uw.show_nondimensional_form(viscosity)) # Should be ~1.0", "harvested_comments": [ "See what the Stokes flux looks like non-dimensionally", "Should show values close to 1.0, not 1e21", @@ -34349,7 +34394,7 @@ "name": "dimensionalise", "kind": "function", "file": "src/underworld3/units.py", - "line": 933, + "line": 964, "signature": "(expression, target_dimensionality = None, model = None) -> Any", "parameters": [ { @@ -34389,7 +34434,7 @@ "name": "simplify_units", "kind": "function", "file": "src/underworld3/units.py", - "line": 1092, + "line": 1123, "signature": "(expression) -> Any", "parameters": [ { @@ -34400,7 +34445,7 @@ } ], "returns": "Any", - "existing_docstring": "Simplify and cancel units in an expression.\n\nThis function performs dimensional analysis to simplify unit expressions,\ncanceling common factors and reducing to fundamental units.\n\nArgs:\n expression: Expression with units to simplify\n\nReturns:\n Expression with simplified units\n\nExamples:\n >>> # Force per area = pressure\n >>> force_per_area = force / area # N/m\u00b2\n >>> simplified = simplify_units(force_per_area) # Pa", + "existing_docstring": "Simplify and cancel units in an expression.\n\nThis function performs dimensional analysis to simplify unit expressions,\ncanceling common factors and reducing to fundamental units.\n\nParameters\n----------\nexpression :\n Expression with units to simplify\n\nReturns\n-------\nExpression with simplified units\n\nExamples\n--------\n>>> # Force per area = pressure\n>>> force_per_area = force / area # N/m\u00b2\n>>> simplified = simplify_units(force_per_area) # Pa", "harvested_comments": [ "Force per area = pressure", "This would need backend-specific implementation", @@ -34415,7 +34460,7 @@ "name": "create_quantity", "kind": "function", "file": "src/underworld3/units.py", - "line": 1121, + "line": 1156, "signature": "(value, units: Union[str, Any], backend: Optional[str] = None) -> Any", "parameters": [ { @@ -34438,7 +34483,7 @@ } ], "returns": "Any", - "existing_docstring": "Create a dimensional quantity from a value and units.\n\n.. deprecated:: 2026-07\n ``uw.quantity`` is THE quantity factory (maintainer decision D14):\n it returns a :class:`~underworld3.function.quantities.UWQuantity`,\n which composes with expressions and non-dimensionalisation. This\n function returns a raw Pint ``Quantity`` and will be removed after one\n deprecation cycle.\n\nArgs:\n value: Numeric value or array\n units: Units specification (string or units object)\n backend: Backend to use ('pint' or 'sympy'), defaults to 'pint'\n\nReturns:\n Dimensional quantity (raw Pint ``Quantity``)\n\nExamples:\n >>> velocity_qty = create_quantity([1.0, 2.0], \"m/s\")\n >>> pressure_qty = create_quantity(101325, \"Pa\")", + "existing_docstring": "Create a dimensional quantity from a value and units.\n\n.. deprecated:: 2026-07\n ``uw.quantity`` is THE quantity factory (maintainer decision D14):\n it returns a :class:`~underworld3.function.quantities.UWQuantity`,\n which composes with expressions and non-dimensionalisation. This\n function returns a raw Pint ``Quantity`` and will be removed after one\n deprecation cycle.\n\nParameters\n----------\nvalue :\n Numeric value or array\nunits : str or units object\n Units specification (string or units object)\nbackend : str, optional\n Backend to use ('pint' or 'sympy'), defaults to 'pint'\n\nReturns\n-------\nDimensional quantity (raw Pint ``Quantity``)\n\nExamples\n--------\n>>> velocity_qty = create_quantity([1.0, 2.0], \"m/s\")\n>>> pressure_qty = create_quantity(101325, \"Pa\")", "harvested_comments": [ "backend parameter is deprecated - Pint is the only supported backend" ], @@ -34451,7 +34496,7 @@ "name": "convert_units", "kind": "function", "file": "src/underworld3/units.py", - "line": 1155, + "line": 1196, "signature": "(quantity, target_units: Union[str, Any]) -> Any", "parameters": [ { @@ -34468,7 +34513,7 @@ } ], "returns": "Any", - "existing_docstring": "Convert quantity to different units.\n\nThis is the SINGLE SOURCE OF TRUTH for unit conversion in UW3.\nAll .to() methods on unit-aware types should delegate to this function.\n\nHandles:\n- UWQuantity \u2192 returns new UWQuantity with converted value\n- UWexpression \u2192 returns new UWexpression with converted value\n- UnitAwareArray \u2192 returns new UnitAwareArray with converted values\n- Pint Quantity \u2192 returns converted Pint Quantity\n\nArgs:\n quantity: Quantity to convert (UWQuantity, UWexpression, UnitAwareArray, Pint)\n target_units: Target units for conversion (str or Pint Unit)\n\nReturns:\n Same type as input, converted to target units\n\nRaises:\n DimensionalityError: If units are not compatible for conversion\n NoUnitsError: If quantity has no units\n\nExamples:\n >>> velocity = uw.quantity(10, \"m/s\")\n >>> velocity_kmh = uw.convert_units(velocity, \"km/h\")\n >>> print(velocity_kmh) # 36.0 [kilometer / hour]\n\n >>> radius = uw.expression(\"r\", uw.quantity(6370, \"km\"))\n >>> radius_m = uw.convert_units(radius, \"m\")\n >>> print(radius_m.value) # 6370000.0", + "existing_docstring": "Convert quantity to different units.\n\nThis is the SINGLE SOURCE OF TRUTH for unit conversion in UW3.\nAll .to() methods on unit-aware types should delegate to this function.\n\nHandles:\n- UWQuantity \u2192 returns new UWQuantity with converted value\n- UWexpression \u2192 returns new UWexpression with converted value\n- UnitAwareArray \u2192 returns new UnitAwareArray with converted values\n- Pint Quantity \u2192 returns converted Pint Quantity\n\nParameters\n----------\nquantity :\n Quantity to convert (UWQuantity, UWexpression, UnitAwareArray, Pint)\ntarget_units : str or pint.Unit\n Target units for conversion (str or Pint Unit)\n\nReturns\n-------\nSame type as input, converted to target units\n\nRaises\n------\nDimensionalityError\n If units are not compatible for conversion\nNoUnitsError\n If quantity has no units\n\nExamples\n--------\n>>> velocity = uw.quantity(10, \"m/s\")\n>>> velocity_kmh = uw.convert_units(velocity, \"km/h\")\n>>> print(velocity_kmh) # 36.0 [kilometer / hour]\n\n>>> radius = uw.expression(\"r\", uw.quantity(6370, \"km\"))\n>>> radius_m = uw.convert_units(radius, \"m\")\n>>> print(radius_m.value) # 6370000.0", "harvested_comments": [ "36.0 [kilometer / hour]", "Get current units info", @@ -34485,7 +34530,7 @@ "name": "to_base_units", "kind": "function", "file": "src/underworld3/units.py", - "line": 1289, + "line": 1338, "signature": "(quantity) -> Any", "parameters": [ { @@ -34496,7 +34541,7 @@ } ], "returns": "Any", - "existing_docstring": "Convert quantity to SI base units.\n\nThis is a convenience function that converts any unit-aware quantity\nto its SI base unit representation.\n\nArgs:\n quantity: Quantity to convert (UWQuantity, UWexpression, UnitAwareArray, Pint)\n\nReturns:\n Same type as input, converted to SI base units\n\nRaises:\n NoUnitsError: If quantity has no units\n\nExamples:\n >>> velocity = uw.quantity(36, \"km/h\")\n >>> velocity_si = uw.to_base_units(velocity)\n >>> print(velocity_si) # 10.0 [meter / second]\n\n >>> radius = uw.expression(\"r\", uw.quantity(6370, \"km\"))\n >>> radius_si = uw.to_base_units(radius)\n >>> print(radius_si.value) # 6370000.0", + "existing_docstring": "Convert quantity to SI base units.\n\nThis is a convenience function that converts any unit-aware quantity\nto its SI base unit representation.\n\nParameters\n----------\nquantity :\n Quantity to convert (UWQuantity, UWexpression, UnitAwareArray, Pint)\n\nReturns\n-------\nSame type as input, converted to SI base units\n\nRaises\n------\nNoUnitsError\n If quantity has no units\n\nExamples\n--------\n>>> velocity = uw.quantity(36, \"km/h\")\n>>> velocity_si = uw.to_base_units(velocity)\n>>> print(velocity_si) # 10.0 [meter / second]\n\n>>> radius = uw.expression(\"r\", uw.quantity(6370, \"km\"))\n>>> radius_si = uw.to_base_units(radius)\n>>> print(radius_si.value) # 6370000.0", "harvested_comments": [ "10.0 [meter / second]", "Get current units info", @@ -34513,7 +34558,7 @@ "name": "to_reduced_units", "kind": "function", "file": "src/underworld3/units.py", - "line": 1383, + "line": 1438, "signature": "(quantity) -> Any", "parameters": [ { @@ -34524,7 +34569,7 @@ } ], "returns": "Any", - "existing_docstring": "Simplify units by canceling common factors.\n\nThis is useful for complex unit expressions like (kg * m / s\u00b2) / (kg / m\u00b3)\nwhich would simplify to m\u2074 / s\u00b2.\n\nArgs:\n quantity: Quantity to simplify (UWQuantity, UWexpression, UnitAwareArray, Pint)\n\nReturns:\n Same type as input, with simplified units\n\nRaises:\n NoUnitsError: If quantity has no units\n\nExamples:\n >>> force = uw.quantity(100, \"kg*m/s**2\")\n >>> force_simplified = uw.to_reduced_units(force)\n >>> print(force_simplified) # 100.0 [newton]", + "existing_docstring": "Simplify units by canceling common factors.\n\nThis is useful for complex unit expressions like (kg * m / s\u00b2) / (kg / m\u00b3)\nwhich would simplify to m\u2074 / s\u00b2.\n\nParameters\n----------\nquantity :\n Quantity to simplify (UWQuantity, UWexpression, UnitAwareArray, Pint)\n\nReturns\n-------\nSame type as input, with simplified units\n\nRaises\n------\nNoUnitsError\n If quantity has no units\n\nExamples\n--------\n>>> force = uw.quantity(100, \"kg*m/s**2\")\n>>> force_simplified = uw.to_reduced_units(force)\n>>> print(force_simplified) # 100.0 [newton]", "harvested_comments": [ "100.0 [newton]", "Get current units info", @@ -34541,7 +34586,7 @@ "name": "to_compact", "kind": "function", "file": "src/underworld3/units.py", - "line": 1469, + "line": 1530, "signature": "(quantity) -> Any", "parameters": [ { @@ -34552,7 +34597,7 @@ } ], "returns": "Any", - "existing_docstring": "Convert quantity to most human-readable unit representation.\n\nThis automatically chooses unit prefixes (kilo, mega, micro, etc.)\nto make the number more readable. For example, 0.001 km becomes 1 m.\n\nArgs:\n quantity: Quantity to make compact (UWQuantity, UWexpression, UnitAwareArray, Pint)\n\nReturns:\n Same type as input, with compact units\n\nRaises:\n NoUnitsError: If quantity has no units\n\nExamples:\n >>> length = uw.quantity(0.001, \"km\")\n >>> length_compact = uw.to_compact(length)\n >>> print(length_compact) # 1.0 [meter]\n\n >>> big_length = uw.quantity(1e9, \"m\")\n >>> big_compact = uw.to_compact(big_length)\n >>> print(big_compact) # 1.0 [gigameter]", + "existing_docstring": "Convert quantity to most human-readable unit representation.\n\nThis automatically chooses unit prefixes (kilo, mega, micro, etc.)\nto make the number more readable. For example, 0.001 km becomes 1 m.\n\nParameters\n----------\nquantity :\n Quantity to make compact (UWQuantity, UWexpression, UnitAwareArray, Pint)\n\nReturns\n-------\nSame type as input, with compact units\n\nRaises\n------\nNoUnitsError\n If quantity has no units\n\nExamples\n--------\n>>> length = uw.quantity(0.001, \"km\")\n>>> length_compact = uw.to_compact(length)\n>>> print(length_compact) # 1.0 [meter]\n\n>>> big_length = uw.quantity(1e9, \"m\")\n>>> big_compact = uw.to_compact(big_length)\n>>> print(big_compact) # 1.0 [gigameter]", "harvested_comments": [ "1.0 [meter]", "1.0 [gigameter]", @@ -34569,11 +34614,11 @@ "name": "get_scaling_coefficients", "kind": "function", "file": "src/underworld3/units.py", - "line": 1559, + "line": 1626, "signature": "() -> Dict[str, Any]", "parameters": [], "returns": "Dict[str, Any]", - "existing_docstring": "Get the current scaling coefficients used for non-dimensionalisation.\n\nReturns:\n Dictionary of scaling coefficients for fundamental dimensions\n\nExamples:\n >>> coeffs = get_scaling_coefficients()\n >>> print(coeffs['[length]']) # 1.0 meter\n >>> print(coeffs['[time]']) # 1.0 year", + "existing_docstring": "Get the current scaling coefficients used for non-dimensionalisation.\n\nReturns\n-------\ndict\n Dictionary of scaling coefficients for fundamental dimensions\n\nExamples\n--------\n>>> coeffs = get_scaling_coefficients()\n>>> print(coeffs['[length]']) # 1.0 meter\n>>> print(coeffs['[time]']) # 1.0 year", "harvested_comments": [ "Use the existing scaling module" ], @@ -34588,7 +34633,7 @@ "name": "set_scaling_coefficients", "kind": "function", "file": "src/underworld3/units.py", - "line": 1577, + "line": 1647, "signature": "(coefficients: Dict[str, Any]) -> None", "parameters": [ { @@ -34599,7 +34644,7 @@ } ], "returns": "None", - "existing_docstring": "Set custom scaling coefficients for non-dimensionalisation.\n\nArgs:\n coefficients: Dictionary mapping dimension names to scaling quantities\n\nExamples:\n >>> coeffs = get_scaling_coefficients()\n >>> coeffs['[length]'] = create_quantity(1000, \"km\") # Geological scale\n >>> coeffs['[time]'] = create_quantity(1e6, \"year\") # Geological time\n >>> set_scaling_coefficients(coeffs)", + "existing_docstring": "Set custom scaling coefficients for non-dimensionalisation.\n\nParameters\n----------\ncoefficients : dict\n Dictionary mapping dimension names to scaling quantities\n\nExamples\n--------\n>>> coeffs = get_scaling_coefficients()\n>>> coeffs['[length]'] = create_quantity(1000, \"km\") # Geological scale\n>>> coeffs['[time]'] = create_quantity(1e6, \"year\") # Geological time\n>>> set_scaling_coefficients(coeffs)", "harvested_comments": [ "Geological scale", "Geological time", @@ -34616,7 +34661,7 @@ "name": "is_dimensionless", "kind": "function", "file": "src/underworld3/units.py", - "line": 1595, + "line": 1668, "signature": "(expression) -> bool", "parameters": [ { @@ -34640,7 +34685,7 @@ "name": "has_units", "kind": "function", "file": "src/underworld3/units.py", - "line": 1600, + "line": 1673, "signature": "(expression) -> bool", "parameters": [ { @@ -34664,7 +34709,7 @@ "name": "same_units", "kind": "function", "file": "src/underworld3/units.py", - "line": 1605, + "line": 1678, "signature": "(expr1, expr2) -> bool", "parameters": [ { @@ -34694,7 +34739,7 @@ "name": "is_velocity", "kind": "function", "file": "src/underworld3/units.py", - "line": 1613, + "line": 1686, "signature": "(expression) -> bool", "parameters": [ { @@ -34721,7 +34766,7 @@ "name": "is_pressure", "kind": "function", "file": "src/underworld3/units.py", - "line": 1623, + "line": 1696, "signature": "(expression) -> bool", "parameters": [ { @@ -34747,7 +34792,7 @@ "name": "validate_expression_units", "kind": "function", "file": "src/underworld3/units.py", - "line": 1633, + "line": 1706, "signature": "(expression, expected_units: Union[str, Any]) -> bool", "parameters": [ { @@ -34764,7 +34809,7 @@ } ], "returns": "bool", - "existing_docstring": "Validate that an expression has the expected units.\n\nArgs:\n expression: Expression to validate\n expected_units: Expected units (string or units object)\n\nReturns:\n True if units match, False otherwise\n\nRaises:\n NoUnitsError: If expression has no units but units are expected", + "existing_docstring": "Validate that an expression has the expected units.\n\nParameters\n----------\nexpression :\n Expression to validate\nexpected_units : str or units object\n Expected units (string or units object)\n\nReturns\n-------\nbool\n True if units match, False otherwise\n\nRaises\n------\nNoUnitsError\n If expression has no units but units are expected", "harvested_comments": [], "status": "complete", "needs": [], @@ -34775,7 +34820,7 @@ "name": "assert_dimensionality", "kind": "function", "file": "src/underworld3/units.py", - "line": 1658, + "line": 1738, "signature": "(value, expected_dimensionality: str, value_name: str = 'value', allow_dimensionless: bool = True, strict: bool = False) -> None", "parameters": [ { @@ -34810,7 +34855,7 @@ } ], "returns": "None", - "existing_docstring": "Assert that a value has the expected dimensionality.\n\nThis is a general type-safety gatekeeper that validates physical dimensionality\nat various points in the code. Complements get_dimensionality() by providing\nenforcement rather than just inspection.\n\nArgs:\n value: The value to validate (quantity, expression, variable, array, etc.)\n expected_dimensionality: Expected dimensionality as a string\n - Specific dimensionality: \"[length]\", \"[length]/[time]\", \"[mass]*[length]/[time]**2\"\n - Dimensionless: \"dimensionless\" or \"\"\n value_name: Name of the value being validated (for error messages)\n allow_dimensionless: If True, accept dimensionless values even when dimensional\n expected (default: True, as dimensionless is valid for solver operations)\n strict: If True, raise error on dimensionless when dimensional expected\n (default: False, overrides allow_dimensionless)\n\nRaises:\n DimensionalityError: If dimensionality doesn't match expected\n NoUnitsError: If strict=True and value is dimensionless when dimensional expected\n\nExamples:\n >>> # Validate coordinates have length dimensionality\n >>> coords = mesh.X.coords\n >>> assert_dimensionality(coords, \"[length]\", \"coordinates\")\n\n >>> # Validate velocity has correct dimensionality\n >>> velocity = uw.discretisation.MeshVariable(\"v\", mesh, 2, units=\"m/s\")\n >>> assert_dimensionality(velocity, \"[length]/[time]\", \"velocity\")\n\n >>> # Validate pressure\n >>> pressure = uw.quantity(1e5, \"Pa\")\n >>> assert_dimensionality(pressure, \"[mass]/([length]*[time]**2)\", \"pressure\")\n\n >>> # Accept dimensionless when dimensional expected (default)\n >>> dimensionless_coords = np.array([[0, 1], [1, 1]])\n >>> assert_dimensionality(dimensionless_coords, \"[length]\", \"coords\") # OK\n\n >>> # Strict mode: reject dimensionless when dimensional expected\n >>> assert_dimensionality(\n ... dimensionless_coords, \"[length]\", \"coords\", strict=True\n ... ) # Raises NoUnitsError", + "existing_docstring": "Assert that a value has the expected dimensionality.\n\nThis is a general type-safety gatekeeper that validates physical dimensionality\nat various points in the code. Complements get_dimensionality() by providing\nenforcement rather than just inspection.\n\nParameters\n----------\nvalue :\n The value to validate (quantity, expression, variable, array, etc.)\nexpected_dimensionality : str\n Expected dimensionality as a string\n\n - Specific dimensionality: \"[length]\", \"[length]/[time]\", \"[mass]*[length]/[time]**2\"\n - Dimensionless: \"dimensionless\" or \"\"\nvalue_name : str, default=\"value\"\n Name of the value being validated (for error messages)\nallow_dimensionless : bool, default=True\n If True, accept dimensionless values even when dimensional\n expected (default: True, as dimensionless is valid for solver operations)\nstrict : bool, default=False\n If True, raise error on dimensionless when dimensional expected\n (default: False, overrides allow_dimensionless)\n\nRaises\n------\nDimensionalityError\n If dimensionality doesn't match expected\nNoUnitsError\n If strict=True and value is dimensionless when dimensional expected\n\nExamples\n--------\n>>> # Validate coordinates have length dimensionality\n>>> coords = mesh.X.coords\n>>> assert_dimensionality(coords, \"[length]\", \"coordinates\")\n\n>>> # Validate velocity has correct dimensionality\n>>> velocity = uw.discretisation.MeshVariable(\"v\", mesh, 2, units=\"m/s\")\n>>> assert_dimensionality(velocity, \"[length]/[time]\", \"velocity\")\n\n>>> # Validate pressure\n>>> pressure = uw.quantity(1e5, \"Pa\")\n>>> assert_dimensionality(pressure, \"[mass]/([length]*[time]**2)\", \"pressure\")\n\n>>> # Accept dimensionless when dimensional expected (default)\n>>> dimensionless_coords = np.array([[0, 1], [1, 1]])\n>>> assert_dimensionality(dimensionless_coords, \"[length]\", \"coords\") # OK\n\n>>> # Strict mode: reject dimensionless when dimensional expected\n>>> assert_dimensionality(\n... dimensionless_coords, \"[length]\", \"coords\", strict=True\n... ) # Raises NoUnitsError", "harvested_comments": [ "Validate coordinates have length dimensionality", "Validate velocity has correct dimensionality", @@ -34829,7 +34874,7 @@ "name": "validate_coordinates_dimensionality", "kind": "function", "file": "src/underworld3/units.py", - "line": 1789, + "line": 1880, "signature": "(coords) -> None", "parameters": [ { @@ -34840,7 +34885,7 @@ } ], "returns": "None", - "existing_docstring": "Validate that coordinates have length dimensionality [L].\n\nThis function checks that the provided coordinates are either dimensionless\n(which is valid for solver operations) or have length dimensionality. It will\nraise an error if coordinates have the wrong dimensionality (e.g., time,\ntemperature, velocity).\n\nArgs:\n coords: Coordinate array to validate\n\nRaises:\n DimensionalityError: If coordinates have units but not length dimensionality\n\nExamples:\n >>> # Valid: dimensionless coords (for solvers)\n >>> validate_coordinates_dimensionality(np.array([[0, 1], [1, 1]]))\n\n >>> # Valid: coords with length units\n >>> coords = uw.function.UnitAwareArray([[0, 1000], [1000, 1000]], units=\"meter\")\n >>> validate_coordinates_dimensionality(coords)\n\n >>> # Invalid: coords with time units (would raise error)\n >>> time_coords = uw.quantity(5.0, \"second\")\n >>> validate_coordinates_dimensionality(time_coords) # Raises DimensionalityError", + "existing_docstring": "Validate that coordinates have length dimensionality [L].\n\nThis function checks that the provided coordinates are either dimensionless\n(which is valid for solver operations) or have length dimensionality. It will\nraise an error if coordinates have the wrong dimensionality (e.g., time,\ntemperature, velocity).\n\nParameters\n----------\ncoords :\n Coordinate array to validate\n\nRaises\n------\nDimensionalityError\n If coordinates have units but not length dimensionality\n\nExamples\n--------\n>>> # Valid: dimensionless coords (for solvers)\n>>> validate_coordinates_dimensionality(np.array([[0, 1], [1, 1]]))\n\n>>> # Valid: coords with length units\n>>> coords = uw.function.UnitAwareArray([[0, 1000], [1000, 1000]], units=\"meter\")\n>>> validate_coordinates_dimensionality(coords)\n\n>>> # Invalid: coords with time units (would raise error)\n>>> time_coords = uw.quantity(5.0, \"second\")\n>>> validate_coordinates_dimensionality(time_coords) # Raises DimensionalityError", "harvested_comments": [ "Valid: dimensionless coords (for solvers)", "Valid: coords with length units", @@ -34859,7 +34904,7 @@ "name": "enforce_units_consistency", "kind": "function", "file": "src/underworld3/units.py", - "line": 1844, + "line": 1940, "signature": "(*expressions) -> None", "parameters": [ { @@ -34870,7 +34915,7 @@ } ], "returns": "None", - "existing_docstring": "Enforce units consistency, raising an error if inconsistent.\n\nArgs:\n *expressions: Expressions that must have consistent units\n\nRaises:\n DimensionalityError: If units are inconsistent\n NoUnitsError: If some have units and others don't", + "existing_docstring": "Enforce units consistency, raising an error if inconsistent.\n\nParameters\n----------\n*expressions :\n Expressions that must have consistent units\n\nRaises\n------\nDimensionalityError\n If units are inconsistent\nNoUnitsError\n If some have units and others don't", "harvested_comments": [ "This already raises appropriate errors" ], @@ -34885,7 +34930,7 @@ "name": "require_units_if_active", "kind": "function", "file": "src/underworld3/units.py", - "line": 1864, + "line": 1965, "signature": "(value, name: str, expected_dimensionality: str = None, default_unit: str = None) -> float", "parameters": [ { @@ -34914,7 +34959,7 @@ } ], "returns": "float", - "existing_docstring": "Validate input and return nondimensional value when units are active.\n\nThis is a gatekeeper function for mesh creation and similar contexts where:\n- When Model with units is active: inputs MUST have units (enforces explicitness)\n- When no units active: raw numbers are accepted\n\nThis prevents ambiguity in dimensional problems where a raw number like `400`\ncould mean meters, kilometers, or a nondimensional value.\n\nArgs:\n value: Input value (quantity, expression, or raw number)\n name: Parameter name for error messages (e.g., \"depth_max\")\n expected_dimensionality: Expected dimensionality string (e.g., \"[length]\")\n If provided, validates the input has correct dimensionality.\n default_unit: Default unit to assume for raw values when units not active.\n Only used for documentation in error messages.\n\nReturns:\n float: Nondimensional value (divided by appropriate reference scale)\n\nRaises:\n ValueError: If units are active but value has no units\n DimensionalityError: If value has wrong dimensionality\n\nExamples:\n >>> # With units active - requires quantity\n >>> model = uw.Model()\n >>> model.set_reference_quantities(length=uw.quantity(1000, \"km\"), ...)\n >>> depth = require_units_if_active(\n ... uw.quantity(400, \"km\"),\n ... \"depth_max\",\n ... expected_dimensionality=\"[length]\"\n ... )\n >>> depth # Returns 0.4 (400 km / 1000 km reference)\n\n >>> # Without units - raw numbers accepted\n >>> depth = require_units_if_active(400, \"depth_max\")\n >>> depth # Returns 400 (unchanged)\n\n >>> # Error case - units active but raw number provided\n >>> model.set_reference_quantities(...)\n >>> require_units_if_active(400, \"depth_max\") # Raises ValueError", + "existing_docstring": "Validate input and return nondimensional value when units are active.\n\nThis is a gatekeeper function for mesh creation and similar contexts where:\n- When Model with units is active: inputs MUST have units (enforces explicitness)\n- When no units active: raw numbers are accepted\n\nThis prevents ambiguity in dimensional problems where a raw number like `400`\ncould mean meters, kilometers, or a nondimensional value.\n\nParameters\n----------\nvalue :\n Input value (quantity, expression, or raw number)\nname : str\n Parameter name for error messages (e.g., \"depth_max\")\nexpected_dimensionality : str, optional\n Expected dimensionality string (e.g., \"[length]\")\n If provided, validates the input has correct dimensionality.\ndefault_unit : str, optional\n Default unit to assume for raw values when units not active.\n Only used for documentation in error messages.\n\nReturns\n-------\nfloat\n Nondimensional value (divided by appropriate reference scale)\n\nRaises\n------\nValueError\n If units are active but value has no units\nDimensionalityError\n If value has wrong dimensionality\n\nExamples\n--------\n>>> # With units active - requires quantity\n>>> model = uw.Model()\n>>> model.set_reference_quantities(length=uw.quantity(1000, \"km\"), ...)\n>>> depth = require_units_if_active(\n... uw.quantity(400, \"km\"),\n... \"depth_max\",\n... expected_dimensionality=\"[length]\"\n... )\n>>> depth # Returns 0.4 (400 km / 1000 km reference)\n\n>>> # Without units - raw numbers accepted\n>>> depth = require_units_if_active(400, \"depth_max\")\n>>> depth # Returns 400 (unchanged)\n\n>>> # Error case - units active but raw number provided\n>>> model.set_reference_quantities(...)\n>>> require_units_if_active(400, \"depth_max\") # Raises ValueError", "harvested_comments": [ "With units active - requires quantity", "Returns 0.4 (400 km / 1000 km reference)", @@ -34931,7 +34976,7 @@ "name": "convert_angle_to_degrees", "kind": "function", "file": "src/underworld3/units.py", - "line": 1964, + "line": 2076, "signature": "(value, name: str = 'angle') -> float", "parameters": [ { @@ -34948,7 +34993,7 @@ } ], "returns": "float", - "existing_docstring": "Convert an angle value to degrees.\n\nAccepts:\n- Raw numbers: assumed to be degrees\n- Quantities with degree units: extracted as degrees\n- Quantities with radian units: converted to degrees\n\nArgs:\n value: Angle value (quantity or raw number)\n name: Parameter name for error messages\n\nReturns:\n float: Angle in degrees\n\nExamples:\n >>> convert_angle_to_degrees(45) # Raw number \u2192 45 degrees\n >>> convert_angle_to_degrees(uw.quantity(45, \"degree\")) # \u2192 45\n >>> convert_angle_to_degrees(uw.quantity(np.pi/4, \"radian\")) # \u2192 45", + "existing_docstring": "Convert an angle value to degrees.\n\nAccepts:\n- Raw numbers: assumed to be degrees\n- Quantities with degree units: extracted as degrees\n- Quantities with radian units: converted to degrees\n\nParameters\n----------\nvalue :\n Angle value (quantity or raw number)\nname : str, default=\"angle\"\n Parameter name for error messages\n\nReturns\n-------\nfloat\n Angle in degrees\n\nExamples\n--------\n>>> convert_angle_to_degrees(45) # Raw number \u2192 45 degrees\n>>> convert_angle_to_degrees(uw.quantity(45, \"degree\")) # \u2192 45\n>>> convert_angle_to_degrees(uw.quantity(np.pi/4, \"radian\")) # \u2192 45", "harvested_comments": [ "Raw number \u2192 45 degrees", "Raw number - assume degrees (conventional for geographic)", @@ -37981,7 +38026,7 @@ } ], "returns": null, - "existing_docstring": "Static method to create a global delay context for all NDArray_With_Callback instances.\n\nThis is useful when you don't have a specific array instance but want to delay\ncallbacks from multiple arrays.\n\nExample\n-------\n>>> with NDArray_With_Callback.delay_callbacks_global(\"mesh update\"):\n... mesh.data[0] = new_pos\n... swarm.data += displacement\n# All callbacks from all arrays fire here", + "existing_docstring": "Static method to create a global delay context for all NDArray_With_Callback instances.\n\nThis is useful when you don't have a specific array instance but want to delay\ncallbacks from multiple arrays.\n\nExample\n-------\n>>> with NDArray_With_Callback.delay_callbacks_global(\"field update\"):\n... temperature.array[...] = new_T\n... material.array[...] = new_material\n# All callbacks from all arrays fire here", "harvested_comments": [ "All callbacks from all arrays fire here", "MPI barrier to ensure all processes enter delay context together", @@ -42026,7 +42071,7 @@ "name": "_Unknowns", "kind": "class", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 5088, + "line": 5097, "signature": "class _Unknowns(SolverBaseClass._Unknowns):", "parameters": [], "returns": null, @@ -42097,7 +42142,7 @@ "name": "__init__", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 2394, + "line": 2403, "signature": "def __init__(self,\n mesh : uw.discretisation.Mesh,\n u_Field : uw.discretisation.MeshVariable = None,\n degree: int = 2,\n verbose = False,\n DuDt : Union[uw.systems.ddt.SemiLagrangian, uw.systems.ddt.Lagrangian] = None,\n DFDt : Union[uw.systems.ddt.SemiLagrangian, uw.systems.ddt.Lagrangian] = None,\n ):", "parameters": [], "returns": null, @@ -42115,7 +42160,7 @@ "name": "__init__", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 3330, + "line": 3339, "signature": "def __init__(self,\n mesh : uw.discretisation.Mesh,\n u_Field : uw.discretisation.MeshVariable = None,\n degree = 2,\n verbose = False,\n DuDt : Union[uw.systems.ddt.SemiLagrangian, uw.systems.ddt.Lagrangian] = None,\n DFDt : Union[uw.systems.ddt.SemiLagrangian, uw.systems.ddt.Lagrangian] = None,\n ):", "parameters": [], "returns": null, @@ -42133,7 +42178,7 @@ "name": "__init__", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 4363, + "line": 4372, "signature": "def __init__(self,\n mesh : uw.discretisation.Mesh,\n u_Field : uw.discretisation.MeshVariable = None,\n n_components : int = None,\n degree = 2,\n verbose = False,\n DuDt : Union[uw.systems.ddt.SemiLagrangian, uw.systems.ddt.Lagrangian] = None,\n DFDt : Union[uw.systems.ddt.SemiLagrangian, uw.systems.ddt.Lagrangian] = None,\n ):", "parameters": [], "returns": null, @@ -42151,7 +42196,7 @@ "name": "__init__", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 5091, + "line": 5100, "signature": "def __init__(inner_self, owning_solver):", "parameters": [], "returns": null, @@ -42169,7 +42214,7 @@ "name": "__init__", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 5113, + "line": 5122, "signature": "def __init__(self,\n mesh : underworld3.discretisation.Mesh,\n velocityField : Optional[underworld3.discretisation.MeshVariable] = None,\n pressureField : Optional[underworld3.discretisation.MeshVariable] = None,\n degree : Optional[int] = 2,\n p_continuous : Optional[bool] = True,\n verbose : Optional[bool] =False,\n DuDt : Union[uw.systems.ddt.SemiLagrangian, uw.systems.ddt.Lagrangian] = None,\n DFDt : Union[uw.systems.ddt.SemiLagrangian, uw.systems.ddt.Lagrangian] = None,\n ):", "parameters": [], "returns": null, @@ -43547,7 +43592,7 @@ "name": "_setup_discretisation", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 2604, + "line": 2613, "signature": "def _setup_discretisation(self, verbose=False):", "parameters": [], "returns": null, @@ -43565,7 +43610,7 @@ "name": "_setup_pointwise_functions", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 2793, + "line": 2802, "signature": "def _setup_pointwise_functions(self, verbose=False, debug=False, debug_name=None):", "parameters": [], "returns": null, @@ -43583,7 +43628,7 @@ "name": "_setup_solver", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 2951, + "line": 2960, "signature": "def _setup_solver(self, verbose=False, _rewire_only=False):", "parameters": [], "returns": null, @@ -43601,7 +43646,7 @@ "name": "_setup_pointwise_functions", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 3766, + "line": 3775, "signature": "def _setup_pointwise_functions(self, verbose=False, debug=False, debug_name=None):", "parameters": [], "returns": null, @@ -43619,7 +43664,7 @@ "name": "_setup_solver", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 4002, + "line": 4011, "signature": "def _setup_solver(self, verbose=False, _rewire_only=False):", "parameters": [], "returns": null, @@ -43637,7 +43682,7 @@ "name": "_setup_discretisation", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 4464, + "line": 4473, "signature": "def _setup_discretisation(self, verbose=False):", "parameters": [], "returns": null, @@ -43655,7 +43700,7 @@ "name": "_setup_pointwise_functions", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 4590, + "line": 4599, "signature": "def _setup_pointwise_functions(self, verbose=False, debug=False, debug_name=None):", "parameters": [], "returns": null, @@ -43673,7 +43718,7 @@ "name": "_setup_solver", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 4792, + "line": 4801, "signature": "def _setup_solver(self, verbose=False, _rewire_only=False):", "parameters": [], "returns": null, @@ -43691,7 +43736,7 @@ "name": "_object_viewer", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 4981, + "line": 4990, "signature": "def _object_viewer(self):", "parameters": [], "returns": null, @@ -43709,7 +43754,7 @@ "name": "_setup_history_terms", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 5732, + "line": 5744, "signature": "def _setup_history_terms(self):", "parameters": [], "returns": null, @@ -43727,7 +43772,7 @@ "name": "_reset_stokes_nullspace", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 6141, + "line": 6153, "signature": "def _reset_stokes_nullspace(self):", "parameters": [], "returns": null, @@ -43745,7 +43790,7 @@ "name": "_setup_pointwise_functions", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 6559, + "line": 6571, "signature": "def _setup_pointwise_functions(self, verbose=False, debug=False, debug_name=None):", "parameters": [], "returns": null, @@ -43763,7 +43808,7 @@ "name": "_setup_solver", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 7304, + "line": 7316, "signature": "def _setup_solver(self, verbose=False, _rewire_only=False):", "parameters": [], "returns": null, @@ -44558,7 +44603,7 @@ "name": "__init__", "kind": "method", "file": "src/underworld3/coordinates.py", - "line": 1351, + "line": 1352, "signature": "(self, mesh, system: Optional[CoordinateSystemType] = CoordinateSystemType.CARTESIAN)", "parameters": [ { @@ -44944,7 +44989,7 @@ "name": "_setup_tau_projection", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 1992, + "line": 2001, "signature": "def _setup_tau_projection(self):", "parameters": [], "returns": null, @@ -44961,7 +45006,7 @@ "name": "_get_dof_partition_by_field_id", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 2122, + "line": 2131, "signature": "def _get_dof_partition_by_field_id(self,\n section_type: str,\n field_id: int,\n filename: Optional[str | None] = None,\n outputPath: Optional[str] = \"\"):", "parameters": [], "returns": null, @@ -44978,7 +45023,7 @@ "name": "_assemble_volume_reaction", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 2211, + "line": 2220, "signature": "def _assemble_volume_reaction(self, time=None, verbose=False):", "parameters": [], "returns": null, @@ -44996,7 +45041,7 @@ "name": "_attach_constant_nullspace", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 2505, + "line": 2514, "signature": "def _attach_constant_nullspace(self):", "parameters": [], "returns": null, @@ -45013,7 +45058,7 @@ "name": "_object_viewer", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 3209, + "line": 3218, "signature": "def _object_viewer(self):", "parameters": [], "returns": null, @@ -45030,7 +45075,7 @@ "name": "_setup_discretisation", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 3616, + "line": 3625, "signature": "def _setup_discretisation(self, verbose=False):", "parameters": [], "returns": null, @@ -45047,7 +45092,7 @@ "name": "_object_viewer", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 4289, + "line": 4298, "signature": "def _object_viewer(self):", "parameters": [], "returns": null, @@ -45064,7 +45109,7 @@ "name": "_residual_is_nonlinear", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 5412, + "line": 5424, "signature": "def _residual_is_nonlinear(self, tol=1e-8):", "parameters": [], "returns": null, @@ -45082,7 +45127,7 @@ "name": "_pressure_dirichlet_bcs", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 6149, + "line": 6161, "signature": "def _pressure_dirichlet_bcs(self):", "parameters": [], "returns": null, @@ -45099,7 +45144,7 @@ "name": "_build_pressure_nullspace_vector", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 6158, + "line": 6170, "signature": "def _build_pressure_nullspace_vector(self):", "parameters": [], "returns": null, @@ -45116,7 +45161,7 @@ "name": "_build_velocity_nullspace_vector", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 6176, + "line": 6188, "signature": "def _build_velocity_nullspace_vector(self, mode):", "parameters": [], "returns": null, @@ -45133,7 +45178,7 @@ "name": "_build_block_gauge_nullspace_vector", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 6211, + "line": 6223, "signature": "def _build_block_gauge_nullspace_vector(self):", "parameters": [], "returns": null, @@ -45151,7 +45196,7 @@ "name": "_build_stokes_nullspace", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 6244, + "line": 6256, "signature": "def _build_stokes_nullspace(self):", "parameters": [], "returns": null, @@ -45168,7 +45213,7 @@ "name": "_setup_block_fieldsplit_options", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 6287, + "line": 6299, "signature": "def _setup_block_fieldsplit_options(self):", "parameters": [], "returns": null, @@ -45186,7 +45231,7 @@ "name": "_attach_stokes_nullspace", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 6322, + "line": 6334, "signature": "def _attach_stokes_nullspace(self):", "parameters": [], "returns": null, @@ -45203,7 +45248,7 @@ "name": "_build_velocity_rotation_nullspace", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 6368, + "line": 6380, "signature": "def _build_velocity_rotation_nullspace(self):", "parameters": [], "returns": null, @@ -45221,7 +45266,7 @@ "name": "_remove_velocity_rotation_gauge", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 6398, + "line": 6410, "signature": "def _remove_velocity_rotation_gauge(self, gvec):", "parameters": [], "returns": null, @@ -45239,7 +45284,7 @@ "name": "_object_viewer", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 6445, + "line": 6457, "signature": "def _object_viewer(self):", "parameters": [], "returns": null, @@ -45256,7 +45301,7 @@ "name": "_setup_discretisation", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 6911, + "line": 6923, "signature": "def _setup_discretisation(self, verbose=False):", "parameters": [], "returns": null, @@ -45273,7 +45318,7 @@ "name": "_constrain_interior_multipliers_in_section", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 7147, + "line": 7159, "signature": "def _constrain_interior_multipliers_in_section(self):", "parameters": [], "returns": null, @@ -45291,7 +45336,7 @@ "name": "_setup_region_ds", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 7622, + "line": 7634, "signature": "def _setup_region_ds(self):", "parameters": [], "returns": null, @@ -45309,7 +45354,7 @@ "name": "_ensure_local_field_index_sets", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 7929, + "line": 7941, "signature": "def _ensure_local_field_index_sets(self, clvec, local_section):", "parameters": [], "returns": null, @@ -45327,7 +45372,7 @@ "name": "_scatter_global_to_fields", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 7992, + "line": 8004, "signature": "def _scatter_global_to_fields(self, gvec):", "parameters": [], "returns": null, @@ -45345,7 +45390,7 @@ "name": "_gather_fields_to_global", "kind": "method", "file": "src/underworld3/cython/petsc_generic_snes_solvers.pyx", - "line": 8041, + "line": 8053, "signature": "def _gather_fields_to_global(self, gvec):", "parameters": [], "returns": null, @@ -46075,7 +46120,7 @@ "name": "__init__", "kind": "method", "file": "src/underworld3/swarm.py", - "line": 2181, + "line": 2245, "signature": "(self, name, swarm, indices = 1, proxy_degree = 1, proxy_continuous = True, update_type = 0, npoints = 5, radius = 0.5, npoints_bc = 2, ind_bc = None, varsymbol = None)", "parameters": [ { @@ -46166,7 +46211,7 @@ "name": "__init__", "kind": "method", "file": "src/underworld3/swarm.py", - "line": 2659, + "line": 2723, "signature": "(self, mesh, recycle_rate = 0, verbose = False, clip_to_mesh = True)", "parameters": [ { @@ -46215,7 +46260,7 @@ "name": "__init__", "kind": "method", "file": "src/underworld3/swarm.py", - "line": 5091, + "line": 5095, "signature": "(self, trackedVariable: uw.discretisation.MeshVariable, verbose = False)", "parameters": [ { @@ -47613,7 +47658,7 @@ "name": "__init__", "kind": "method", "file": "src/underworld3/coordinates.py", - "line": 956, + "line": 957, "signature": "(self, coordinate_system)", "parameters": [ { @@ -48200,7 +48245,7 @@ "name": "_dm_stack_bcs", "kind": "function", "file": "src/underworld3/adaptivity.py", - "line": 451, + "line": 449, "signature": "(dm, boundaries, stacked_bc_label_name)", "parameters": [ { @@ -49071,7 +49116,7 @@ "name": "__del__", "kind": "method", "file": "src/underworld3/discretisation/discretisation_mesh.py", - "line": 3013, + "line": 3012, "signature": "(self)", "parameters": [], "returns": null, @@ -49089,7 +49134,7 @@ "name": "_build_kd_tree_index_DS", "kind": "method", "file": "src/underworld3/discretisation/discretisation_mesh.py", - "line": 4483, + "line": 4482, "signature": "(self)", "parameters": [], "returns": null, @@ -49110,7 +49155,7 @@ "name": "_build_kd_tree_index", "kind": "method", "file": "src/underworld3/discretisation/discretisation_mesh.py", - "line": 4506, + "line": 4505, "signature": "(self)", "parameters": [], "returns": null, @@ -49134,7 +49179,7 @@ "name": "_build_kd_tree_index_PIC", "kind": "method", "file": "src/underworld3/discretisation/discretisation_mesh.py", - "line": 4597, + "line": 4596, "signature": "(self)", "parameters": [], "returns": null, @@ -49158,7 +49203,7 @@ "name": "_get_domain_centroids", "kind": "method", "file": "src/underworld3/discretisation/discretisation_mesh.py", - "line": 5554, + "line": 5553, "signature": "(self)", "parameters": [], "returns": null, @@ -49176,7 +49221,7 @@ "name": "_get_domain_kdtree", "kind": "method", "file": "src/underworld3/discretisation/discretisation_mesh.py", - "line": 5563, + "line": 5562, "signature": "(self)", "parameters": [], "returns": null, @@ -49374,7 +49419,7 @@ "name": "_dmswarm_get_migrate_type", "kind": "function", "file": "src/underworld3/function/_function.pyx", - "line": 1550, + "line": 1549, "signature": "def _dmswarm_get_migrate_type(sdm):", "parameters": [], "returns": null, @@ -49392,7 +49437,7 @@ "name": "_dmswarm_set_migrate_type", "kind": "function", "file": "src/underworld3/function/_function.pyx", - "line": 1560, + "line": 1559, "signature": "def _dmswarm_set_migrate_type(sdm, mtype:PETsc.DMSwarm.MigrateType):", "parameters": [], "returns": null, @@ -49972,7 +50017,7 @@ "name": "__repr__", "kind": "method", "file": "src/underworld3/meshing/surfaces.py", - "line": 2412, + "line": 2413, "signature": "(self) -> str", "parameters": [], "returns": "str", @@ -50206,7 +50251,7 @@ "name": "_data_layout", "kind": "method", "file": "src/underworld3/swarm.py", - "line": 1009, + "line": 1008, "signature": "(self, i, j = None)", "parameters": [ { @@ -50237,7 +50282,7 @@ "name": "_create_proxy_variable", "kind": "method", "file": "src/underworld3/swarm.py", - "line": 1056, + "line": 1055, "signature": "(self)", "parameters": [], "returns": null, @@ -50261,7 +50306,7 @@ "name": "__getitem__", "kind": "method", "file": "src/underworld3/swarm.py", - "line": 2334, + "line": 2398, "signature": "(self, index)", "parameters": [ { @@ -50286,7 +50331,7 @@ "name": "_particle_coordinates", "kind": "property", "file": "src/underworld3/swarm.py", - "line": 3289, + "line": 3353, "signature": "(self)", "parameters": [], "returns": null, @@ -50304,7 +50349,7 @@ "name": "_data_layout", "kind": "method", "file": "src/underworld3/swarm.py", - "line": 4790, + "line": 4748, "signature": "(self, i, j = None)", "parameters": [ { @@ -50335,7 +50380,7 @@ "name": "_get_map", "kind": "method", "file": "src/underworld3/swarm.py", - "line": 4819, + "line": 4777, "signature": "(self, var)", "parameters": [ { @@ -51165,7 +51210,7 @@ "name": "_dm_unstack_bcs", "kind": "function", "file": "src/underworld3/adaptivity.py", - "line": 475, + "line": 473, "signature": "(dm, boundaries, stacked_bc_label_name)", "parameters": [ { @@ -52829,7 +52874,7 @@ "name": "__repr__", "kind": "method", "file": "src/underworld3/coordinates.py", - "line": 846, + "line": 847, "signature": "(self)", "parameters": [], "returns": null, @@ -52846,7 +52891,7 @@ "name": "_invalidate_cache", "kind": "method", "file": "src/underworld3/coordinates.py", - "line": 980, + "line": 981, "signature": "(self)", "parameters": [], "returns": null, @@ -52863,7 +52908,7 @@ "name": "_compute_coordinates", "kind": "method", "file": "src/underworld3/coordinates.py", - "line": 984, + "line": 985, "signature": "(self)", "parameters": [], "returns": null, @@ -52884,7 +52929,7 @@ "name": "__getitem__", "kind": "method", "file": "src/underworld3/coordinates.py", - "line": 1072, + "line": 1073, "signature": "(self, idx)", "parameters": [ { @@ -52910,7 +52955,7 @@ "name": "__repr__", "kind": "method", "file": "src/underworld3/coordinates.py", - "line": 1253, + "line": 1254, "signature": "(self)", "parameters": [], "returns": null, @@ -52927,7 +52972,7 @@ "name": "_apply_units_scaling", "kind": "method", "file": "src/underworld3/coordinates.py", - "line": 1792, + "line": 1793, "signature": "(self)", "parameters": [], "returns": null, @@ -52950,7 +52995,7 @@ "name": "__getitem__", "kind": "method", "file": "src/underworld3/coordinates.py", - "line": 1848, + "line": 1849, "signature": "(self, idx)", "parameters": [ { @@ -52974,7 +53019,7 @@ "name": "__iter__", "kind": "method", "file": "src/underworld3/coordinates.py", - "line": 1852, + "line": 1853, "signature": "(self)", "parameters": [], "returns": null, @@ -52991,7 +53036,7 @@ "name": "__len__", "kind": "method", "file": "src/underworld3/coordinates.py", - "line": 1856, + "line": 1857, "signature": "(self)", "parameters": [], "returns": null, @@ -53008,7 +53053,7 @@ "name": "_sympy_", "kind": "method", "file": "src/underworld3/coordinates.py", - "line": 1976, + "line": 1977, "signature": "(self)", "parameters": [], "returns": null, @@ -53026,7 +53071,7 @@ "name": "__sympy__", "kind": "method", "file": "src/underworld3/coordinates.py", - "line": 1988, + "line": 1989, "signature": "(self)", "parameters": [], "returns": null, @@ -53043,7 +53088,7 @@ "name": "__getattr__", "kind": "method", "file": "src/underworld3/coordinates.py", - "line": 2020, + "line": 2021, "signature": "(self, name)", "parameters": [ { @@ -53074,7 +53119,7 @@ "name": "__add__", "kind": "method", "file": "src/underworld3/coordinates.py", - "line": 2053, + "line": 2054, "signature": "(self, other)", "parameters": [ { @@ -53098,7 +53143,7 @@ "name": "__radd__", "kind": "method", "file": "src/underworld3/coordinates.py", - "line": 2057, + "line": 2058, "signature": "(self, other)", "parameters": [ { @@ -53122,7 +53167,7 @@ "name": "__sub__", "kind": "method", "file": "src/underworld3/coordinates.py", - "line": 2061, + "line": 2062, "signature": "(self, other)", "parameters": [ { @@ -53146,7 +53191,7 @@ "name": "__rsub__", "kind": "method", "file": "src/underworld3/coordinates.py", - "line": 2065, + "line": 2066, "signature": "(self, other)", "parameters": [ { @@ -53170,7 +53215,7 @@ "name": "__mul__", "kind": "method", "file": "src/underworld3/coordinates.py", - "line": 2069, + "line": 2070, "signature": "(self, other)", "parameters": [ { @@ -53194,7 +53239,7 @@ "name": "__rmul__", "kind": "method", "file": "src/underworld3/coordinates.py", - "line": 2073, + "line": 2074, "signature": "(self, other)", "parameters": [ { @@ -53218,7 +53263,7 @@ "name": "__truediv__", "kind": "method", "file": "src/underworld3/coordinates.py", - "line": 2077, + "line": 2078, "signature": "(self, other)", "parameters": [ { @@ -53242,7 +53287,7 @@ "name": "__rtruediv__", "kind": "method", "file": "src/underworld3/coordinates.py", - "line": 2081, + "line": 2082, "signature": "(self, other)", "parameters": [ { @@ -53266,7 +53311,7 @@ "name": "__pow__", "kind": "method", "file": "src/underworld3/coordinates.py", - "line": 2085, + "line": 2086, "signature": "(self, other)", "parameters": [ { @@ -53290,7 +53335,7 @@ "name": "__neg__", "kind": "method", "file": "src/underworld3/coordinates.py", - "line": 2089, + "line": 2090, "signature": "(self)", "parameters": [], "returns": null, @@ -53307,7 +53352,7 @@ "name": "_cartesian_to_natural_coords", "kind": "method", "file": "src/underworld3/coordinates.py", - "line": 2592, + "line": 2593, "signature": "(self, cartesian_coords)", "parameters": [ { @@ -53335,7 +53380,7 @@ "name": "_create_cartesian_profile", "kind": "method", "file": "src/underworld3/coordinates.py", - "line": 2686, + "line": 2687, "signature": "(self, profile_type, **params)", "parameters": [ { @@ -53370,7 +53415,7 @@ "name": "_create_cylindrical_profile", "kind": "method", "file": "src/underworld3/coordinates.py", - "line": 2759, + "line": 2760, "signature": "(self, profile_type, **params)", "parameters": [ { @@ -53406,7 +53451,7 @@ "name": "_create_spherical_profile", "kind": "method", "file": "src/underworld3/coordinates.py", - "line": 2827, + "line": 2828, "signature": "(self, profile_type, **params)", "parameters": [ { @@ -53796,7 +53841,7 @@ "name": "_assert_coord_mutation_allowed", "kind": "method", "file": "src/underworld3/discretisation/discretisation_mesh.py", - "line": 3063, + "line": 3062, "signature": "(self)", "parameters": [], "returns": null, @@ -53814,7 +53859,7 @@ "name": "_coord_mutation", "kind": "method", "file": "src/underworld3/discretisation/discretisation_mesh.py", - "line": 3099, + "line": 3098, "signature": "(self)", "parameters": [], "returns": null, @@ -53832,7 +53877,7 @@ "name": "_deform_mesh", "kind": "method", "file": "src/underworld3/discretisation/discretisation_mesh.py", - "line": 3189, + "line": 3188, "signature": "(self, new_coords: numpy.ndarray, verbose = False, active_vars = None)", "parameters": [ { @@ -53875,7 +53920,7 @@ "name": "_legacy_access", "kind": "method", "file": "src/underworld3/discretisation/discretisation_mesh.py", - "line": 3273, + "line": 3272, "signature": "(self, *writeable_vars)", "parameters": [ { @@ -53905,7 +53950,7 @@ "name": "_write_petsc_reload_variable", "kind": "method", "file": "src/underworld3/discretisation/discretisation_mesh.py", - "line": 3961, + "line": 3960, "signature": "(self, viewer, var)", "parameters": [ { @@ -53935,7 +53980,7 @@ "name": "_write_petsc_reload_file", "kind": "method", "file": "src/underworld3/discretisation/discretisation_mesh.py", - "line": 3980, + "line": 3979, "signature": "(self, checkpoint_file, variables, mode = 'w')", "parameters": [ { @@ -53971,7 +54016,7 @@ "name": "_get_coords_for_var", "kind": "method", "file": "src/underworld3/discretisation/discretisation_mesh.py", - "line": 4417, + "line": 4416, "signature": "(self, var)", "parameters": [ { @@ -53997,7 +54042,7 @@ "name": "_get_coords_for_basis", "kind": "method", "file": "src/underworld3/discretisation/discretisation_mesh.py", - "line": 4432, + "line": 4431, "signature": "(self, degree, continuous)", "parameters": [ { @@ -54031,7 +54076,7 @@ "name": "_mark_faces_inside_and_out", "kind": "method", "file": "src/underworld3/discretisation/discretisation_mesh.py", - "line": 4653, + "line": 4652, "signature": "(self)", "parameters": [], "returns": null, @@ -54055,7 +54100,7 @@ "name": "_get_owned_cells_mask", "kind": "method", "file": "src/underworld3/discretisation/discretisation_mesh.py", - "line": 4771, + "line": 4770, "signature": "(self)", "parameters": [], "returns": null, @@ -54075,7 +54120,7 @@ "name": "_test_if_points_in_cells_internal", "kind": "method", "file": "src/underworld3/discretisation/discretisation_mesh.py", - "line": 4813, + "line": 4812, "signature": "(self, points, cells, on_boundary = True, tol = 0.0)", "parameters": [ { @@ -54123,7 +54168,7 @@ "name": "_mark_local_boundary_faces_inside_and_out", "kind": "method", "file": "src/underworld3/discretisation/discretisation_mesh.py", - "line": 4928, + "line": 4927, "signature": "(self)", "parameters": [], "returns": null, @@ -54147,7 +54192,7 @@ "name": "_get_closest_local_cells_internal", "kind": "method", "file": "src/underworld3/discretisation/discretisation_mesh.py", - "line": 5209, + "line": 5208, "signature": "(self, coords: numpy.ndarray, on_boundary: bool = True, tol: float = 0.0) -> numpy.ndarray", "parameters": [ { @@ -54187,7 +54232,7 @@ "name": "_robust_owning_cells", "kind": "method", "file": "src/underworld3/discretisation/discretisation_mesh.py", - "line": 5446, + "line": 5445, "signature": "(self, coords: numpy.ndarray) -> numpy.ndarray", "parameters": [ { @@ -54211,7 +54256,7 @@ "name": "_eval_use_robust_location", "kind": "method", "file": "src/underworld3/discretisation/discretisation_mesh.py", - "line": 5473, + "line": 5472, "signature": "(self) -> bool", "parameters": [], "returns": "bool", @@ -54228,7 +54273,7 @@ "name": "_get_mesh_sizes", "kind": "method", "file": "src/underworld3/discretisation/discretisation_mesh.py", - "line": 5501, + "line": 5500, "signature": "(self, verbose = False)", "parameters": [ { @@ -54254,7 +54299,7 @@ "name": "_get_mesh_centroids", "kind": "method", "file": "src/underworld3/discretisation/discretisation_mesh.py", - "line": 5535, + "line": 5534, "signature": "(self)", "parameters": [], "returns": null, @@ -54274,7 +54319,7 @@ "name": "_increment_mesh_version", "kind": "method", "file": "src/underworld3/discretisation/discretisation_mesh.py", - "line": 5733, + "line": 5732, "signature": "(self)", "parameters": [], "returns": null, @@ -54292,7 +54337,7 @@ "name": "_write_compat_groups", "kind": "function", "file": "src/underworld3/discretisation/discretisation_mesh.py", - "line": 6181, + "line": 6180, "signature": "(mesh, var, var_h5_path)", "parameters": [ { @@ -55027,7 +55072,7 @@ "name": "_gather_transfer_vars", "kind": "function", "file": "src/underworld3/discretisation/remesh.py", - "line": 132, + "line": 159, "signature": "(mesh: 'Mesh') -> dict", "parameters": [ { @@ -55054,29 +55099,68 @@ "is_public": false }, { - "name": "_snapshot_remap_data", + "name": "_snapshot_var_data", "kind": "function", "file": "src/underworld3/discretisation/remesh.py", - "line": 173, - "signature": "(remap_vars)", + "line": 200, + "signature": "(vars_)", "parameters": [ { - "name": "remap_vars", + "name": "vars_", "type_hint": null, "default": null, "description": "" } ], "returns": null, - "existing_docstring": "Copy the current ``.data`` array of every REMAP var (defensive copy).", + "existing_docstring": "Copy the current ``.data`` array of each given var (defensive copy).\n\nUsed for both the REMAP bucket and the operator-managed bucket in\n:func:`remesh_with_field_transfer`. Vars that cannot be snapshotted\nare omitted from the returned dict.", "harvested_comments": [ - "If a var's data is not addressable yet (lazy alloc, etc.),", - "skip it \u2014 nothing to snapshot. The transfer pass will just", - "not touch it." + "Sanctioned swallow: a var whose storage is unallocated or", + "size-0 on this rank (lazy allocation / empty local partition)", + "has nothing to snapshot. It is absent from the returned dict,", + "so the transfer pass never touches it (the write-back twin,", + "_write_var_data, skips the same vars)." ], - "status": "minimal", + "status": "partial", "needs": [ - "NEEDS_PARAMETERS" + "NEEDS_PARAMETERS", + "NEEDS_RETURNS" + ], + "parent_class": null, + "is_public": false + }, + { + "name": "_write_var_data", + "kind": "function", + "file": "src/underworld3/discretisation/remesh.py", + "line": 224, + "signature": "(var, values)", + "parameters": [ + { + "name": "var", + "type_hint": null, + "default": null, + "description": "" + }, + { + "name": "values", + "type_hint": null, + "default": null, + "description": "" + } + ], + "returns": null, + "existing_docstring": "Overwrite ``var``'s DOF values in place, tolerating unwritable storage.\n\nParameters\n----------\nvar : MeshVariable\n Target variable; its full ``.data`` buffer is overwritten.\nvalues : array_like or float\n Replacement values, broadcastable to ``var.data``'s shape\n (a scalar such as ``0.0`` zeros the whole buffer).", + "harvested_comments": [ + "Sanctioned swallow: a var whose storage is unallocated or size-0", + "on this rank (lazy allocation / empty local partition) has nowhere", + "to write. Skipping leaves the variable exactly as the snapshot", + "pass found it \u2014 the same vars are skipped by _snapshot_var_data,", + "so no transfer is silently half-applied." + ], + "status": "partial", + "needs": [ + "NEEDS_RETURNS" ], "parent_class": null, "is_public": false @@ -55085,7 +55169,7 @@ "name": "_remap_one_var", "kind": "function", "file": "src/underworld3/discretisation/remesh.py", - "line": 190, + "line": 246, "signature": "(var, old_X, new_X, mesh)", "parameters": [ { @@ -55128,7 +55212,7 @@ "name": "_new_coord_cache", "kind": "function", "file": "src/underworld3/discretisation/remesh.py", - "line": 200, + "line": 256, "signature": "(mesh, remap_vars)", "parameters": [ { @@ -55158,7 +55242,7 @@ "name": "_remesh_with_field_transfer_impl", "kind": "function", "file": "src/underworld3/discretisation/remesh.py", - "line": 290, + "line": 351, "signature": "(mesh, do_move) -> bool", "parameters": [ { @@ -55194,7 +55278,7 @@ "name": "_iter_active_hooks", "kind": "function", "file": "src/underworld3/discretisation/remesh.py", - "line": 358, + "line": 425, "signature": "(mesh)", "parameters": [ { @@ -55217,66 +55301,11 @@ "parent_class": null, "is_public": false }, - { - "name": "_remap_var_set", - "kind": "function", - "file": "src/underworld3/discretisation/remesh.py", - "line": 385, - "signature": "(mesh, vars_, old_X, new_X, old_data)", - "parameters": [ - { - "name": "mesh", - "type_hint": null, - "default": null, - "description": "" - }, - { - "name": "vars_", - "type_hint": null, - "default": null, - "description": "" - }, - { - "name": "old_X", - "type_hint": null, - "default": null, - "description": "" - }, - { - "name": "new_X", - "type_hint": null, - "default": null, - "description": "" - }, - { - "name": "old_data", - "type_hint": null, - "default": null, - "description": "" - } - ], - "returns": null, - "existing_docstring": "One-shot REMAP dance for a set of variables.\n\nUsed by the generic per-variable pass in\n:func:`remesh_with_field_transfer` AND exposed (as\n:func:`remap_var_set`) so an operator's ``on_remesh`` hook can\nforce-REMAP its CARRY-managed vars on an adapt that is\nALE-incompatible (e.g. an OT_adapt reset, where the linear\n``\u0394x/dt \u2192 v_mesh`` interpretation breaks down).\n\nContract: on entry the mesh is at ``new_X`` and each var's\n``.data`` may hold *either* the original snapshot value (CARRY:\noperator-managed vars that the generic pass skipped) or the\nnot-yet-restored value (REMAP: the snapshot has not been written\nback). ``old_data`` is the snapshot keyed by var, captured *before*\n``do_move`` ran. On exit the mesh is back at ``new_X`` and every\nvar's ``.data`` holds the OLD field evaluated at the var's NEW DOF\ncoordinates.\n\nThe set may be empty (no-op). Operations are MPI-collective; every\nrank must call with the same set.", - "harvested_comments": [ - "Capture target DOF coords on the NEW mesh first (we are sitting", - "on new_X right now). var.coords reads from the live mesh state.", - "Deform back to the old coords, restore data so global_evaluate", - "sees the old field, evaluate at each var's new DOF coords,", - "then deform forward and write the resampled values back." - ], - "status": "partial", - "needs": [ - "NEEDS_PARAMETERS", - "NEEDS_RETURNS" - ], - "parent_class": null, - "is_public": false - }, { "name": "_mark_reinit_stale", "kind": "function", "file": "src/underworld3/discretisation/remesh.py", - "line": 478, + "line": 522, "signature": "(var)", "parameters": [ { @@ -56487,16 +56516,18 @@ } ], "returns": null, - "existing_docstring": "Evaluate expression at coordinates with automatic unit handling.\n\nInternal implementation of :func:`evaluate`. The public wrapper\ndelegates here and then optionally applies the ``monotone``\nbounded-interpolation post-process. This body is unchanged from the\nhistorical ``evaluate`` so that ``monotone=False`` is bit-identical.\n\nThis function wraps the Cython evaluate_nd implementation to automatically\nhandle unit conversions and return unit-aware results.\n\nParameters\n----------\nexpr : sympy expression or UWexpression\n Expression to evaluate\ncoords : numpy.ndarray or UnitAwareArray\n Coordinates at which to evaluate. Supported forms:\n - numpy array of doubles (shape: n_points x n_dims) in model\n (non-dimensional) units\n - UnitAwareArray with dimensional coordinates (e.g., from mesh.X.coords)\n - Both work transparently - dimensional coords are auto-converted\n\n Python lists/tuples of coordinates \u2014 including quantity-valued\n lists such as ``[(x_qty, y_qty)]`` \u2014 are NOT supported and raise\n ``TypeError`` (the coordinate-units family is unsupported;\n maintainer ruling D7, 2026-07). Convert dimensional coordinates\n explicitly, e.g. ``float(uw.non_dimensionalise(x_qty))``, and\n pass a plain array.\ncoord_sys : mesh.N vector coordinate system, optional\n Coordinate system to use (default: None)\nother_arguments : dict, optional\n Additional arguments for evaluation (default: None)\nsimplify : bool, optional\n Whether to simplify expression (default: True)\nverbose : bool, optional\n Verbose output (default: False)\nevalf : bool, optional\n Force numerical evaluation via sympy evalf (default: False)\nmode : str, optional\n Evaluation mode controlling accuracy vs speed tradeoff.\n Options: ``\"default\"`` (accurate, projection for derivatives),\n ``\"fast\"`` (Clement gradient, RBF everywhere),\n ``\"projection\"`` (always L2 projection).\n Default: ``\"default\"``\ndata_layout : callable, optional\n Data layout specification (default: None)\ncheck_extrapolated : bool, optional\n Check for extrapolated values (default: False)\nsmoothing : float, optional\n Smoothing parameter for L2 projection (dimensionless).\n Only used when projection is active. Default: 1e-6\nrbf : bool, optional\n Expert override: Force RBF interpolation everywhere. Overrides mode.\nforce_l2 : bool, optional\n Expert override: Force L2 projection path. Overrides mode.\n\nReturns\n-------\nUWQuantity, UnitAwareArray, or ndarray\n If non-dimensional scaling is active, returns plain ndarray.\n If expression has units, returns UWQuantity (scalar) or UnitAwareArray.\n Otherwise returns plain ndarray.\n\nNotes\n-----\n**Evaluation Modes:**\n\n- ``\"fast\"``: Clement gradient (no solve), direct calculation, RBF everywhere\n- ``\"default\"``: Projection for derivatives (solve), direct otherwise, DMInterp + RBF\n- ``\"projection\"``: Always use L2 projection (solve), DMInterp + RBF\n\nThe `rbf` and `force_l2` parameters are expert overrides that take\nprecedence over the mode setting when explicitly provided.\n\nExamples\n--------\n>>> # Works with both dimensional and non-dimensional coords\n>>> result = uw.function.evaluate(T.sym, T.coords) # dimensional coords\n>>> result = uw.function.evaluate(T.sym, mesh.data[:, :2]) # non-dimensional\n>>> if hasattr(result, 'to'):\n... result_K = result.to('K') # Unit conversion", + "existing_docstring": "Evaluate expression at coordinates with automatic unit handling.\n\nInternal implementation of :func:`evaluate`. The public wrapper\ndelegates here and then optionally applies the ``monotone``\nbounded-interpolation post-process. This body is unchanged from the\nhistorical ``evaluate`` so that ``monotone=False`` is bit-identical.\n\nThis function wraps the Cython evaluate_nd implementation to\nautomatically handle unit conversions and return unit-aware results.\n\nParameters, return values, and the evaluation-mode notes are\ndocumented on the public wrapper, :func:`evaluate` \u2014 every parameter\nhere has the same meaning (the wrapper adds only ``monotone``).", "harvested_comments": [ "Expert overrides (override mode settings)", - "Works with both dimensional and non-dimensional coords", - "dimensional coords", - "non-dimensional", - "Unit conversion" + "NEW: Use evaluate-specific unwrapper", + "Map mode to internal flags (rbf, force_l2)", + "Expert overrides take precedence when explicitly provided", + "Use mode settings" + ], + "status": "partial", + "needs": [ + "NEEDS_RETURNS" ], - "status": "complete", - "needs": [], "parent_class": null, "is_public": false }, @@ -56504,7 +56535,7 @@ "name": "_global_evaluate_impl", "kind": "function", "file": "src/underworld3/function/functions_unit_system.py", - "line": 410, + "line": 343, "signature": "(expr, coords = None, coord_sys = None, other_arguments = None, simplify = False, verbose = False, evalf = False, mode = 'default', data_layout = None, check_extrapolated = False, smoothing = 1e-06, rbf = None, force_l2 = None, local_fallback = True)", "parameters": [ { @@ -56610,7 +56641,7 @@ "name": "_normalize_monotone", "kind": "function", "file": "src/underworld3/function/functions_unit_system.py", - "line": 656, + "line": 589, "signature": "(monotone)", "parameters": [ { @@ -56635,7 +56666,7 @@ "name": "_apply_monotone_limit", "kind": "function", "file": "src/underworld3/function/functions_unit_system.py", - "line": 675, + "line": 608, "signature": "(expr, coords, value, mode, coord_sys = None, other_arguments = None)", "parameters": [ { @@ -59704,7 +59735,7 @@ "name": "_fault_seg_distance_sym", "kind": "function", "file": "src/underworld3/meshing/surfaces.py", - "line": 2423, + "line": 2424, "signature": "(X, a, b)", "parameters": [ { @@ -59741,7 +59772,7 @@ "name": "_fault_collect_polylines", "kind": "function", "file": "src/underworld3/meshing/surfaces.py", - "line": 2440, + "line": 2441, "signature": "(faults)", "parameters": [ { @@ -59767,7 +59798,7 @@ "name": "_fault_collect_segments", "kind": "function", "file": "src/underworld3/meshing/surfaces.py", - "line": 2477, + "line": 2478, "signature": "(faults)", "parameters": [ { @@ -59792,7 +59823,7 @@ "name": "_mesh_h0", "kind": "function", "file": "src/underworld3/meshing/surfaces.py", - "line": 2779, + "line": 2780, "signature": "(mesh)", "parameters": [ { @@ -59819,7 +59850,7 @@ "name": "_fault_min_distance_np", "kind": "function", "file": "src/underworld3/meshing/surfaces.py", - "line": 2798, + "line": 2799, "signature": "(P, polylines)", "parameters": [ { @@ -59849,7 +59880,7 @@ "name": "_fault_mmg_metric", "kind": "function", "file": "src/underworld3/meshing/surfaces.py", - "line": 2815, + "line": 2816, "signature": "(mesh, faults, cell_size, n_across, h_far, name)", "parameters": [ { @@ -60919,7 +60950,7 @@ "name": "_create_variable_array", "kind": "method", "file": "src/underworld3/swarm.py", - "line": 384, + "line": 383, "signature": "(self, initial_data = None)", "parameters": [ { @@ -60947,7 +60978,7 @@ "name": "_create_canonical_data_array", "kind": "method", "file": "src/underworld3/swarm.py", - "line": 441, + "line": 440, "signature": "(self, initial_data = None)", "parameters": [ { @@ -60975,7 +61006,7 @@ "name": "_create_array_view", "kind": "method", "file": "src/underworld3/swarm.py", - "line": 526, + "line": 525, "signature": "(self)", "parameters": [], "returns": null, @@ -60992,7 +61023,7 @@ "name": "_is_simple_variable", "kind": "method", "file": "src/underworld3/swarm.py", - "line": 544, + "line": 543, "signature": "(self)", "parameters": [], "returns": null, @@ -61009,7 +61040,7 @@ "name": "_create_simple_array_view", "kind": "method", "file": "src/underworld3/swarm.py", - "line": 548, + "line": 547, "signature": "(self)", "parameters": [], "returns": null, @@ -61032,7 +61063,7 @@ "name": "_create_tensor_array_view", "kind": "method", "file": "src/underworld3/swarm.py", - "line": 761, + "line": 760, "signature": "(self)", "parameters": [], "returns": null, @@ -61055,7 +61086,7 @@ "name": "_pack_array_to_data_format", "kind": "method", "file": "src/underworld3/swarm.py", - "line": 972, + "line": 971, "signature": "(self, array_data)", "parameters": [ { @@ -61085,7 +61116,7 @@ "name": "_update", "kind": "method", "file": "src/underworld3/swarm.py", - "line": 1086, + "line": 1085, "signature": "(self)", "parameters": [], "returns": null, @@ -61105,7 +61136,7 @@ "name": "_update_proxy_if_stale", "kind": "method", "file": "src/underworld3/swarm.py", - "line": 1106, + "line": 1105, "signature": "(self)", "parameters": [], "returns": null, @@ -61128,7 +61159,7 @@ "name": "_rbf_to_meshVar", "kind": "method", "file": "src/underworld3/swarm.py", - "line": 1152, + "line": 1151, "signature": "(self, meshVar, nnn = None, verbose = False)", "parameters": [ { @@ -61171,7 +61202,7 @@ "name": "_rbf_reduce_to_meshVar", "kind": "method", "file": "src/underworld3/swarm.py", - "line": 1208, + "line": 1207, "signature": "(self, meshVar, verbose = False)", "parameters": [ { @@ -61208,7 +61239,7 @@ "name": "_warn_deprecated_sync", "kind": "method", "file": "src/underworld3/swarm.py", - "line": 1275, + "line": 1273, "signature": "(sync)", "parameters": [ { @@ -61232,7 +61263,7 @@ "name": "_object_viewer", "kind": "method", "file": "src/underworld3/swarm.py", - "line": 1470, + "line": 1468, "signature": "(self)", "parameters": [], "returns": null, @@ -61251,7 +61282,7 @@ "name": "_update", "kind": "method", "file": "src/underworld3/swarm.py", - "line": 2248, + "line": 2312, "signature": "(self)", "parameters": [], "returns": null, @@ -61268,7 +61299,7 @@ "name": "_on_data_changed", "kind": "method", "file": "src/underworld3/swarm.py", - "line": 2256, + "line": 2320, "signature": "(self)", "parameters": [], "returns": null, @@ -61286,7 +61317,7 @@ "name": "_update_proxy_if_stale", "kind": "method", "file": "src/underworld3/swarm.py", - "line": 2265, + "line": 2329, "signature": "(self)", "parameters": [], "returns": null, @@ -61309,7 +61340,7 @@ "name": "_update_proxy_variables", "kind": "method", "file": "src/underworld3/swarm.py", - "line": 2452, + "line": 2516, "signature": "(self)", "parameters": [], "returns": null, @@ -61333,7 +61364,7 @@ "name": "__del__", "kind": "method", "file": "src/underworld3/swarm.py", - "line": 2804, + "line": 2868, "signature": "(self)", "parameters": [], "returns": null, @@ -61355,7 +61386,7 @@ "name": "_invalidate_canonical_data", "kind": "method", "file": "src/underworld3/swarm.py", - "line": 2839, + "line": 2903, "signature": "(self)", "parameters": [], "returns": null, @@ -61379,7 +61410,7 @@ "name": "_flush_pending_petsc_sync", "kind": "method", "file": "src/underworld3/swarm.py", - "line": 2868, + "line": 2932, "signature": "(self)", "parameters": [], "returns": null, @@ -61400,7 +61431,7 @@ "name": "_sync_before_assembly", "kind": "method", "file": "src/underworld3/swarm.py", - "line": 2901, + "line": 2965, "signature": "(self)", "parameters": [], "returns": null, @@ -61424,7 +61455,7 @@ "name": "_get_kdtree", "kind": "method", "file": "src/underworld3/swarm.py", - "line": 2962, + "line": 3026, "signature": "(self)", "parameters": [], "returns": null, @@ -61445,7 +61476,7 @@ "name": "_route_by_nearest_centroid", "kind": "method", "file": "src/underworld3/swarm.py", - "line": 2975, + "line": 3039, "signature": "(self)", "parameters": [], "returns": null, @@ -61467,7 +61498,7 @@ "name": "_force_migration_after_mesh_change", "kind": "method", "file": "src/underworld3/swarm.py", - "line": 3777, + "line": 3841, "signature": "(self)", "parameters": [], "returns": null, @@ -61491,7 +61522,7 @@ "name": "_snapshot_stable_name", "kind": "method", "file": "src/underworld3/swarm.py", - "line": 4446, + "line": 4545, "signature": "(self) -> str", "parameters": [], "returns": "str", @@ -61504,36 +61535,6 @@ "parent_class": "Swarm", "is_public": false }, - { - "name": "_legacy_access", - "kind": "method", - "file": "src/underworld3/swarm.py", - "line": 4597, - "signature": "(self, *writeable_vars)", - "parameters": [ - { - "name": "*writeable_vars", - "type_hint": "SwarmVariable", - "default": null, - "description": "" - } - ], - "returns": null, - "existing_docstring": "This context manager makes the underlying swarm variables data available to\nthe user. The data should be accessed via the variables `data` handle.\n\nAs default, all data is read-only. To enable writeable data, the user should\nspecify which variable they wish to modify.\n\nAt the conclusion of the users context managed block, numerous further operations\nwill be automatically executed. This includes swarm parallel migration routines\nwhere the swarm's `particle_coordinates` variable has been modified. The swarm\nvariable proxy mesh variables will also be updated for modifed swarm variables.\n\nParameters\n----------\nwriteable_vars\n The variables for which data write access is required.\n\nExample\n-------\n\n>>> import underworld3 as uw\n>>> someMesh = uw.discretisation.FeMesh_Cartesian()\n>>> with someMesh._deform_mesh():\n... someMesh.data[0] = [0.1,0.1]\n>>> someMesh.data[0]\narray([ 0.1, 0.1])", - "harvested_comments": [ - "if already accessed within higher level context manager, continue.", - "set flag so variable status can be known elsewhere", - "add to de-access list to rewind this later", - "grab numpy object, setting read only if necessary", - "increment variable state" - ], - "status": "partial", - "needs": [ - "NEEDS_RETURNS" - ], - "parent_class": "Swarm", - "is_public": false - }, { "name": "_as_float", "kind": "function", diff --git a/docs/docstrings/review_queue.md b/docs/docstrings/review_queue.md index 8add038f..6c143e25 100644 --- a/docs/docstrings/review_queue.md +++ b/docs/docstrings/review_queue.md @@ -6,10 +6,10 @@ Generated by `docstring_sweep.py` | Status | Count | |--------|-------| -| none | 383 | -| minimal | 854 | -| partial | 863 | -| complete | 377 | +| none | 378 | +| minimal | 853 | +| partial | 867 | +| complete | 379 | ## By File @@ -19,13 +19,13 @@ Generated by `docstring_sweep.py` - 📝 `SolverBaseClass` [class] L52 - NEEDS_PARAMETERS, NEEDS_RETURNS -- 📝 `SNES_Scalar` [class] L2327 +- 📝 `SNES_Scalar` [class] L2336 - NEEDS_RETURNS -- 📝 `SNES_Vector` [class] L3263 +- 📝 `SNES_Vector` [class] L3272 - NEEDS_RETURNS -- 📝 `SNES_MultiComponent` [class] L4334 +- 📝 `SNES_MultiComponent` [class] L4343 - NEEDS_RETURNS -- 📝 `SNES_Stokes_SaddlePt` [class] L4998 +- 📝 `SNES_Stokes_SaddlePt` [class] L5007 - NEEDS_RETURNS - ❌ `consistent_jacobian` [method] L185 - NEEDS_OVERVIEW, NEEDS_PARAMETERS @@ -39,51 +39,51 @@ Generated by `docstring_sweep.py` - NEEDS_OVERVIEW, NEEDS_PARAMETERS - ❌ `DFDt` [method] L851 - NEEDS_OVERVIEW, NEEDS_PARAMETERS -- ❌ `F0` [method] L1811 +- ❌ `F0` [method] L1820 - NEEDS_OVERVIEW, NEEDS_PARAMETERS -- ❌ `F1` [method] L1815 +- ❌ `F1` [method] L1824 - NEEDS_OVERVIEW, NEEDS_PARAMETERS -- ❌ `u` [method] L1830 +- ❌ `u` [method] L1839 - NEEDS_OVERVIEW, NEEDS_PARAMETERS -- ❌ `DuDt` [method] L1845 +- ❌ `DuDt` [method] L1854 - NEEDS_OVERVIEW, NEEDS_PARAMETERS -- ❌ `DFDt` [method] L1860 +- ❌ `DFDt` [method] L1869 - NEEDS_OVERVIEW, NEEDS_PARAMETERS -- ❌ `constitutive_model` [method] L1881 +- ❌ `constitutive_model` [method] L1890 - NEEDS_OVERVIEW, NEEDS_PARAMETERS -- ❌ `constant_nullspace` [method] L2502 +- ❌ `constant_nullspace` [method] L2511 - NEEDS_OVERVIEW, NEEDS_PARAMETERS -- ❌ `petsc_use_constant_nullspace` [method] L2571 +- ❌ `petsc_use_constant_nullspace` [method] L2580 - NEEDS_OVERVIEW, NEEDS_PARAMETERS -- ❌ `tolerance` [method] L2597 +- ❌ `tolerance` [method] L2606 - NEEDS_OVERVIEW, NEEDS_PARAMETERS -- ❌ `tolerance` [method] L3440 +- ❌ `tolerance` [method] L3449 - NEEDS_OVERVIEW, NEEDS_PARAMETERS -- ❌ `tolerance` [method] L4453 +- ❌ `tolerance` [method] L4462 - NEEDS_OVERVIEW, NEEDS_PARAMETERS -- ❌ `tolerance` [method] L4457 +- ❌ `tolerance` [method] L4466 - NEEDS_OVERVIEW, NEEDS_PARAMETERS -- ❌ `p` [method] L5102 +- ❌ `p` [method] L5111 - NEEDS_OVERVIEW, NEEDS_PARAMETERS -- ❌ `p` [method] L5106 +- ❌ `p` [method] L5115 - NEEDS_OVERVIEW, NEEDS_PARAMETERS -- ❌ `tolerance` [method] L5792 +- ❌ `tolerance` [method] L5804 - NEEDS_OVERVIEW, NEEDS_PARAMETERS -- ❌ `strategy` [method] L5823 +- ❌ `strategy` [method] L5835 - NEEDS_OVERVIEW, NEEDS_PARAMETERS -- ❌ `PF0` [method] L5911 +- ❌ `PF0` [method] L5923 - NEEDS_OVERVIEW, NEEDS_PARAMETERS -- ❌ `p` [method] L5936 +- ❌ `p` [method] L5948 - NEEDS_OVERVIEW, NEEDS_PARAMETERS -- ❌ `saddle_preconditioner` [method] L5956 +- ❌ `saddle_preconditioner` [method] L5968 - NEEDS_OVERVIEW, NEEDS_PARAMETERS -- ❌ `petsc_use_nullspace` [method] L5974 +- ❌ `petsc_use_nullspace` [method] L5986 - NEEDS_OVERVIEW, NEEDS_PARAMETERS -- ❌ `petsc_use_pressure_nullspace` [method] L6025 +- ❌ `petsc_use_pressure_nullspace` [method] L6037 - NEEDS_OVERVIEW, NEEDS_PARAMETERS -- ❌ `multiplier_schur_pc` [method] L6066 +- ❌ `multiplier_schur_pc` [method] L6078 - NEEDS_OVERVIEW, NEEDS_PARAMETERS -- ❌ `petsc_velocity_nullspace_basis` [method] L6121 +- ❌ `petsc_velocity_nullspace_basis` [method] L6133 - NEEDS_OVERVIEW, NEEDS_PARAMETERS - 📝 `consistent_jacobian` [method] L142 - NEEDS_PARAMETERS, NEEDS_RETURNS @@ -121,116 +121,116 @@ Generated by `docstring_sweep.py` - NEEDS_RETURNS - ⚠️ `is_numeric_only` [method] L1574 - NEEDS_PARAMETERS -- 📝 `add_essential_bc` [method] L1655 +- 📝 `add_essential_bc` [method] L1664 - NEEDS_RETURNS -- 📝 `add_natural_bc` [method] L1698 +- 📝 `add_natural_bc` [method] L1707 - NEEDS_RETURNS -- 📝 `add_dirichlet_bc` [method] L1756 +- 📝 `add_dirichlet_bc` [method] L1765 - NEEDS_RETURNS -- 📝 `u` [method] L1819 +- 📝 `u` [method] L1828 - NEEDS_PARAMETERS, NEEDS_RETURNS -- 📝 `DuDt` [method] L1835 +- 📝 `DuDt` [method] L1844 - NEEDS_PARAMETERS, NEEDS_RETURNS -- 📝 `DFDt` [method] L1850 +- 📝 `DFDt` [method] L1859 - NEEDS_PARAMETERS, NEEDS_RETURNS -- 📝 `constitutive_model` [method] L1866 +- 📝 `constitutive_model` [method] L1875 - NEEDS_PARAMETERS, NEEDS_RETURNS -- 📝 `tau` [method] L1925 +- 📝 `tau` [method] L1934 - NEEDS_PARAMETERS -- ⚠️ `validate_solver` [method] L2076 +- ⚠️ `validate_solver` [method] L2085 - NEEDS_PARAMETERS -- 📝 `get_dof_partition` [method] L2093 +- 📝 `get_dof_partition` [method] L2102 - NEEDS_RETURNS -- 📝 `boundary_flux` [method] L2290 +- 📝 `boundary_flux` [method] L2299 - NEEDS_PARAMETERS -- 📝 `boundary_flux_field` [method] L2308 +- 📝 `boundary_flux_field` [method] L2317 - NEEDS_PARAMETERS -- 📝 `constant_nullspace` [method] L2485 +- 📝 `constant_nullspace` [method] L2494 - NEEDS_PARAMETERS, NEEDS_RETURNS -- 📝 `petsc_use_constant_nullspace` [method] L2559 +- 📝 `petsc_use_constant_nullspace` [method] L2568 - NEEDS_PARAMETERS, NEEDS_RETURNS -- 📝 `tolerance` [method] L2575 +- 📝 `tolerance` [method] L2584 - NEEDS_PARAMETERS -- ✅ `solve` [method] L3053 -- 📝 `tolerance` [method] L3423 +- ✅ `solve` [method] L3062 +- 📝 `tolerance` [method] L3432 - NEEDS_PARAMETERS -- 📝 `add_nitsche_bc` [method] L3447 +- 📝 `add_nitsche_bc` [method] L3456 - NEEDS_RETURNS -- ✅ `solve` [method] L4140 -- ⚠️ `n_components` [method] L4448 +- ✅ `solve` [method] L4149 +- ⚠️ `n_components` [method] L4457 - NEEDS_PARAMETERS -- 📝 `solve` [method] L4913 +- 📝 `solve` [method] L4922 - NEEDS_RETURNS -- 📝 `add_rotated_freeslip_bc` [method] L5338 +- 📝 `add_rotated_freeslip_bc` [method] L5347 - NEEDS_RETURNS -- 📝 `boundary_normal_traction` [method] L5460 +- 📝 `boundary_normal_traction` [method] L5472 - NEEDS_PARAMETERS, NEEDS_RETURNS -- 📝 `dynamic_topography` [method] L5479 +- 📝 `dynamic_topography` [method] L5491 - NEEDS_PARAMETERS, NEEDS_RETURNS -- 📝 `add_nitsche_bc` [method] L5500 +- 📝 `add_nitsche_bc` [method] L5512 - NEEDS_RETURNS -- 📝 `tolerance` [method] L5766 +- 📝 `tolerance` [method] L5778 - NEEDS_PARAMETERS -- 📝 `strategy` [method] L5804 +- 📝 `strategy` [method] L5816 - NEEDS_PARAMETERS -- 📝 `PF0` [method] L5890 +- 📝 `PF0` [method] L5902 - NEEDS_PARAMETERS -- 📝 `p` [method] L5917 +- 📝 `p` [method] L5929 - NEEDS_PARAMETERS -- 📝 `saddle_preconditioner` [method] L5941 +- 📝 `saddle_preconditioner` [method] L5953 - NEEDS_PARAMETERS -- 📝 `petsc_use_nullspace` [method] L5961 +- 📝 `petsc_use_nullspace` [method] L5973 - NEEDS_PARAMETERS, NEEDS_RETURNS -- 📝 `petsc_use_pressure_nullspace` [method] L5990 +- 📝 `petsc_use_pressure_nullspace` [method] L6002 - NEEDS_PARAMETERS, NEEDS_RETURNS -- 📝 `multiplier_schur_pc` [method] L6035 +- 📝 `multiplier_schur_pc` [method] L6047 - NEEDS_PARAMETERS, NEEDS_RETURNS -- 📝 `petsc_velocity_nullspace_basis` [method] L6071 +- 📝 `petsc_velocity_nullspace_basis` [method] L6083 - NEEDS_PARAMETERS, NEEDS_RETURNS -- ⚠️ `validate_solver` [method] L6498 +- ⚠️ `validate_solver` [method] L6510 - NEEDS_PARAMETERS -- 📝 `get_dof_partition` [method] L6520 +- 📝 `get_dof_partition` [method] L6532 - NEEDS_RETURNS -- 📝 `set_active_region` [method] L7605 +- 📝 `set_active_region` [method] L7617 - NEEDS_RETURNS -- 📝 `compute_volume_residual_fields` [method] L7665 +- 📝 `compute_volume_residual_fields` [method] L7677 - NEEDS_PARAMETERS -- 📝 `compute_boundary_residual_fields` [method] L7804 +- 📝 `compute_boundary_residual_fields` [method] L7816 - NEEDS_PARAMETERS, NEEDS_RETURNS -- ⚠️ `get_local_field_is` [method] L7943 +- ⚠️ `get_local_field_is` [method] L7955 - NEEDS_PARAMETERS -- ✅ `solve` [method] L8054 -- ⚠️ `estimate_dt` [method] L8348 +- ✅ `solve` [method] L8066 +- ⚠️ `estimate_dt` [method] L8360 - NEEDS_PARAMETERS
Private/Internal (69 items) - `_Unknowns` [class] L769 - partial -- `_Unknowns` [class] L5088 - minimal +- `_Unknowns` [class] L5097 - minimal - `__init__` [method] L62 - none - `__init__` [method] L795 - none -- `__init__` [method] L2394 - none -- `__init__` [method] L3330 - none -- `__init__` [method] L4363 - none -- `__init__` [method] L5091 - none -- `__init__` [method] L5113 - none +- `__init__` [method] L2403 - none +- `__init__` [method] L3339 - none +- `__init__` [method] L4372 - none +- `__init__` [method] L5100 - none +- `__init__` [method] L5122 - none - `_reset` [method] L893 - none - `_build` [method] L1227 - none - `_setup_problem_description` [method] L1437 - none -- `_setup_discretisation` [method] L2604 - none -- `_setup_pointwise_functions` [method] L2793 - none -- `_setup_solver` [method] L2951 - none -- `_setup_pointwise_functions` [method] L3766 - none -- `_setup_solver` [method] L4002 - none -- `_setup_discretisation` [method] L4464 - none -- `_setup_pointwise_functions` [method] L4590 - none -- `_setup_solver` [method] L4792 - none -- `_object_viewer` [method] L4981 - none -- `_setup_history_terms` [method] L5732 - none -- `_reset_stokes_nullspace` [method] L6141 - none -- `_setup_pointwise_functions` [method] L6559 - none -- `_setup_solver` [method] L7304 - none +- `_setup_discretisation` [method] L2613 - none +- `_setup_pointwise_functions` [method] L2802 - none +- `_setup_solver` [method] L2960 - none +- `_setup_pointwise_functions` [method] L3775 - none +- `_setup_solver` [method] L4011 - none +- `_setup_discretisation` [method] L4473 - none +- `_setup_pointwise_functions` [method] L4599 - none +- `_setup_solver` [method] L4801 - none +- `_object_viewer` [method] L4990 - none +- `_setup_history_terms` [method] L5744 - none +- `_reset_stokes_nullspace` [method] L6153 - none +- `_setup_pointwise_functions` [method] L6571 - none +- `_setup_solver` [method] L7316 - none - `_jacobian_unwrap` [function] L24 - partial - `_jacobian_source` [method] L195 - partial - `_newton_flux` [method] L236 - partial @@ -251,30 +251,30 @@ Generated by `docstring_sweep.py` - `_set_constants_on_ds` [method] L1393 - partial - `_update_constants` [method] L1414 - partial - `_value_first_bc_args` [method] L1610 - partial -- `_setup_tau_projection` [method] L1992 - minimal -- `_get_dof_partition_by_field_id` [method] L2122 - partial -- `_assemble_volume_reaction` [method] L2211 - partial -- `_attach_constant_nullspace` [method] L2505 - minimal -- `_object_viewer` [method] L3209 - minimal -- `_setup_discretisation` [method] L3616 - minimal -- `_object_viewer` [method] L4289 - minimal -- `_residual_is_nonlinear` [method] L5412 - partial -- `_pressure_dirichlet_bcs` [method] L6149 - minimal -- `_build_pressure_nullspace_vector` [method] L6158 - minimal -- `_build_velocity_nullspace_vector` [method] L6176 - minimal -- `_build_block_gauge_nullspace_vector` [method] L6211 - partial -- `_build_stokes_nullspace` [method] L6244 - minimal -- `_setup_block_fieldsplit_options` [method] L6287 - partial -- `_attach_stokes_nullspace` [method] L6322 - minimal -- `_build_velocity_rotation_nullspace` [method] L6368 - partial -- `_remove_velocity_rotation_gauge` [method] L6398 - partial -- `_object_viewer` [method] L6445 - minimal -- `_setup_discretisation` [method] L6911 - minimal -- `_constrain_interior_multipliers_in_section` [method] L7147 - partial -- `_setup_region_ds` [method] L7622 - partial -- `_ensure_local_field_index_sets` [method] L7929 - partial -- `_scatter_global_to_fields` [method] L7992 - partial -- `_gather_fields_to_global` [method] L8041 - partial +- `_setup_tau_projection` [method] L2001 - minimal +- `_get_dof_partition_by_field_id` [method] L2131 - partial +- `_assemble_volume_reaction` [method] L2220 - partial +- `_attach_constant_nullspace` [method] L2514 - minimal +- `_object_viewer` [method] L3218 - minimal +- `_setup_discretisation` [method] L3625 - minimal +- `_object_viewer` [method] L4298 - minimal +- `_residual_is_nonlinear` [method] L5424 - partial +- `_pressure_dirichlet_bcs` [method] L6161 - minimal +- `_build_pressure_nullspace_vector` [method] L6170 - minimal +- `_build_velocity_nullspace_vector` [method] L6188 - minimal +- `_build_block_gauge_nullspace_vector` [method] L6223 - partial +- `_build_stokes_nullspace` [method] L6256 - minimal +- `_setup_block_fieldsplit_options` [method] L6299 - partial +- `_attach_stokes_nullspace` [method] L6334 - minimal +- `_build_velocity_rotation_nullspace` [method] L6380 - partial +- `_remove_velocity_rotation_gauge` [method] L6410 - partial +- `_object_viewer` [method] L6457 - minimal +- `_setup_discretisation` [method] L6923 - minimal +- `_constrain_interior_multipliers_in_section` [method] L7159 - partial +- `_setup_region_ds` [method] L7634 - partial +- `_ensure_local_field_index_sets` [method] L7941 - partial +- `_scatter_global_to_fields` [method] L8004 - partial +- `_gather_fields_to_global` [method] L8053 - partial
@@ -1381,9 +1381,9 @@ Generated by `docstring_sweep.py` - NEEDS_PARAMETERS, NEEDS_RETURNS - 📝 `GeographicCoordinateAccessor` [class] L475 - NEEDS_PARAMETERS, NEEDS_RETURNS -- 📝 `SphericalCoordinateAccessor` [class] L925 +- 📝 `SphericalCoordinateAccessor` [class] L926 - NEEDS_PARAMETERS, NEEDS_RETURNS -- 📝 `CoordinateSystem` [class] L1325 +- 📝 `CoordinateSystem` [class] L1326 - NEEDS_PARAMETERS, NEEDS_RETURNS - 📝 `sym` (UWCoordinate) [property] L166 - NEEDS_PARAMETERS @@ -1430,128 +1430,128 @@ Generated by `docstring_sweep.py` - NEEDS_PARAMETERS - ✅ `to_cartesian` (GeographicCoordinateAccessor) [method] L704 - ✅ `from_cartesian` (GeographicCoordinateAccessor) [method] L746 -- ✅ `points_to_cartesian` (GeographicCoordinateAccessor) [method] L788 -- ✅ `points_from_cartesian` (GeographicCoordinateAccessor) [method] L820 -- 📝 `view` (GeographicCoordinateAccessor) [method] L861 +- ✅ `points_to_cartesian` (GeographicCoordinateAccessor) [method] L789 +- ✅ `points_from_cartesian` (GeographicCoordinateAccessor) [method] L821 +- 📝 `view` (GeographicCoordinateAccessor) [method] L862 - NEEDS_PARAMETERS, NEEDS_RETURNS -- ⚠️ `r` (SphericalCoordinateAccessor) [property] L1010 +- ⚠️ `r` (SphericalCoordinateAccessor) [property] L1011 - NEEDS_PARAMETERS -- ⚠️ `theta` (SphericalCoordinateAccessor) [property] L1016 +- ⚠️ `theta` (SphericalCoordinateAccessor) [property] L1017 - NEEDS_PARAMETERS -- ⚠️ `phi` (SphericalCoordinateAccessor) [property] L1022 +- ⚠️ `phi` (SphericalCoordinateAccessor) [property] L1023 - NEEDS_PARAMETERS -- 📝 `coords` (SphericalCoordinateAccessor) [property] L1033 +- 📝 `coords` (SphericalCoordinateAccessor) [property] L1034 - NEEDS_PARAMETERS -- ⚠️ `r_sym` (SphericalCoordinateAccessor) [property] L1093 +- ⚠️ `r_sym` (SphericalCoordinateAccessor) [property] L1094 - NEEDS_PARAMETERS -- ⚠️ `theta_sym` (SphericalCoordinateAccessor) [property] L1098 +- ⚠️ `theta_sym` (SphericalCoordinateAccessor) [property] L1099 - NEEDS_PARAMETERS -- ⚠️ `phi_sym` (SphericalCoordinateAccessor) [property] L1103 +- ⚠️ `phi_sym` (SphericalCoordinateAccessor) [property] L1104 - NEEDS_PARAMETERS -- ⚠️ `unit_r` (SphericalCoordinateAccessor) [property] L1115 +- ⚠️ `unit_r` (SphericalCoordinateAccessor) [property] L1116 - NEEDS_PARAMETERS -- ⚠️ `unit_theta` (SphericalCoordinateAccessor) [property] L1120 +- ⚠️ `unit_theta` (SphericalCoordinateAccessor) [property] L1121 - NEEDS_PARAMETERS -- ⚠️ `unit_phi` (SphericalCoordinateAccessor) [property] L1125 +- ⚠️ `unit_phi` (SphericalCoordinateAccessor) [property] L1126 - NEEDS_PARAMETERS -- ⚠️ `unit_radial` (SphericalCoordinateAccessor) [property] L1137 +- ⚠️ `unit_radial` (SphericalCoordinateAccessor) [property] L1138 - NEEDS_PARAMETERS -- ⚠️ `unit_outward` (SphericalCoordinateAccessor) [property] L1142 +- ⚠️ `unit_outward` (SphericalCoordinateAccessor) [property] L1143 - NEEDS_PARAMETERS -- ⚠️ `unit_inward` (SphericalCoordinateAccessor) [property] L1147 +- ⚠️ `unit_inward` (SphericalCoordinateAccessor) [property] L1148 - NEEDS_PARAMETERS -- ✅ `to_cartesian` (SphericalCoordinateAccessor) [method] L1153 -- ✅ `from_cartesian` (SphericalCoordinateAccessor) [method] L1181 -- ✅ `points_to_cartesian` (SphericalCoordinateAccessor) [method] L1213 -- ✅ `points_from_cartesian` (SphericalCoordinateAccessor) [method] L1233 -- 📝 `view` (SphericalCoordinateAccessor) [method] L1264 +- ✅ `to_cartesian` (SphericalCoordinateAccessor) [method] L1154 +- ✅ `from_cartesian` (SphericalCoordinateAccessor) [method] L1182 +- ✅ `points_to_cartesian` (SphericalCoordinateAccessor) [method] L1214 +- ✅ `points_from_cartesian` (SphericalCoordinateAccessor) [method] L1234 +- 📝 `view` (SphericalCoordinateAccessor) [method] L1265 - NEEDS_PARAMETERS, NEEDS_RETURNS -- 📝 `coords` (CoordinateSystem) [property] L1861 +- 📝 `coords` (CoordinateSystem) [property] L1862 - NEEDS_PARAMETERS -- 📝 `units` (CoordinateSystem) [property] L1921 +- 📝 `units` (CoordinateSystem) [property] L1922 - NEEDS_PARAMETERS -- 📝 `with_units` (CoordinateSystem) [property] L1948 +- 📝 `with_units` (CoordinateSystem) [property] L1949 - NEEDS_PARAMETERS -- ⚠️ `shape` (CoordinateSystem) [property] L1970 +- ⚠️ `shape` (CoordinateSystem) [property] L1971 - NEEDS_PARAMETERS -- ⚠️ `is_symbol` (CoordinateSystem) [property] L1996 +- ⚠️ `is_symbol` (CoordinateSystem) [property] L1997 - NEEDS_PARAMETERS -- ⚠️ `is_Matrix` (CoordinateSystem) [property] L2001 +- ⚠️ `is_Matrix` (CoordinateSystem) [property] L2002 - NEEDS_PARAMETERS -- ⚠️ `is_scalar` (CoordinateSystem) [property] L2006 +- ⚠️ `is_scalar` (CoordinateSystem) [property] L2007 - NEEDS_PARAMETERS -- ⚠️ `is_number` (CoordinateSystem) [property] L2011 +- ⚠️ `is_number` (CoordinateSystem) [property] L2012 - NEEDS_PARAMETERS -- ⚠️ `is_commutative` (CoordinateSystem) [property] L2016 +- ⚠️ `is_commutative` (CoordinateSystem) [property] L2017 - NEEDS_PARAMETERS -- 📝 `X` (CoordinateSystem) [property] L2096 +- 📝 `X` (CoordinateSystem) [property] L2097 - NEEDS_PARAMETERS -- ⚠️ `x` (CoordinateSystem) [property] L2136 +- ⚠️ `x` (CoordinateSystem) [property] L2137 - NEEDS_PARAMETERS -- ⚠️ `N` (CoordinateSystem) [property] L2141 +- ⚠️ `N` (CoordinateSystem) [property] L2142 - NEEDS_PARAMETERS -- ⚠️ `R` (CoordinateSystem) [property] L2146 +- ⚠️ `R` (CoordinateSystem) [property] L2147 - NEEDS_PARAMETERS -- ⚠️ `r` (CoordinateSystem) [property] L2151 +- ⚠️ `r` (CoordinateSystem) [property] L2152 - NEEDS_PARAMETERS -- ⚠️ `xR` (CoordinateSystem) [property] L2156 +- ⚠️ `xR` (CoordinateSystem) [property] L2157 - NEEDS_PARAMETERS -- 📝 `geo` (CoordinateSystem) [property] L2161 +- 📝 `geo` (CoordinateSystem) [property] L2162 - NEEDS_PARAMETERS -- 📝 `spherical` (CoordinateSystem) [property] L2212 +- 📝 `spherical` (CoordinateSystem) [property] L2213 - NEEDS_PARAMETERS -- 📝 `rRotN` (CoordinateSystem) [property] L2264 +- 📝 `rRotN` (CoordinateSystem) [property] L2265 - NEEDS_PARAMETERS, NEEDS_RETURNS -- ⚠️ `xRotN` (CoordinateSystem) [property] L2273 +- ⚠️ `xRotN` (CoordinateSystem) [property] L2274 - NEEDS_PARAMETERS -- 📝 `geoRotN` (CoordinateSystem) [property] L2278 +- 📝 `geoRotN` (CoordinateSystem) [property] L2279 - NEEDS_PARAMETERS -- ⚠️ `unit_e_0` (CoordinateSystem) [property] L2312 +- ⚠️ `unit_e_0` (CoordinateSystem) [property] L2313 - NEEDS_PARAMETERS -- ⚠️ `unit_e_1` (CoordinateSystem) [property] L2317 +- ⚠️ `unit_e_1` (CoordinateSystem) [property] L2318 - NEEDS_PARAMETERS -- ⚠️ `unit_e_2` (CoordinateSystem) [property] L2322 +- ⚠️ `unit_e_2` (CoordinateSystem) [property] L2323 - NEEDS_PARAMETERS -- ⚠️ `unit_i` (CoordinateSystem) [property] L2330 +- ⚠️ `unit_i` (CoordinateSystem) [property] L2331 - NEEDS_PARAMETERS -- ⚠️ `unit_j` (CoordinateSystem) [property] L2335 +- ⚠️ `unit_j` (CoordinateSystem) [property] L2336 - NEEDS_PARAMETERS -- ⚠️ `unit_k` (CoordinateSystem) [property] L2340 +- ⚠️ `unit_k` (CoordinateSystem) [property] L2341 - NEEDS_PARAMETERS -- ⚠️ `unit_ijk` (CoordinateSystem) [method] L2347 +- ⚠️ `unit_ijk` (CoordinateSystem) [method] L2348 - NEEDS_PARAMETERS -- ⚠️ `unit_vertical` (CoordinateSystem) [property] L2356 +- ⚠️ `unit_vertical` (CoordinateSystem) [property] L2357 - NEEDS_PARAMETERS -- ⚠️ `unit_horizontal` (CoordinateSystem) [property] L2376 +- ⚠️ `unit_horizontal` (CoordinateSystem) [property] L2377 - NEEDS_PARAMETERS -- ⚠️ `unit_horizontal_0` (CoordinateSystem) [property] L2392 +- ⚠️ `unit_horizontal_0` (CoordinateSystem) [property] L2393 - NEEDS_PARAMETERS -- ⚠️ `unit_horizontal_1` (CoordinateSystem) [property] L2397 +- ⚠️ `unit_horizontal_1` (CoordinateSystem) [property] L2398 - NEEDS_PARAMETERS -- ⚠️ `unit_radial` (CoordinateSystem) [property] L2414 +- ⚠️ `unit_radial` (CoordinateSystem) [property] L2415 - NEEDS_PARAMETERS -- ⚠️ `unit_tangential` (CoordinateSystem) [property] L2429 +- ⚠️ `unit_tangential` (CoordinateSystem) [property] L2430 - NEEDS_PARAMETERS -- ⚠️ `unit_meridional` (CoordinateSystem) [property] L2442 +- ⚠️ `unit_meridional` (CoordinateSystem) [property] L2443 - NEEDS_PARAMETERS -- ⚠️ `unit_azimuthal` (CoordinateSystem) [property] L2452 +- ⚠️ `unit_azimuthal` (CoordinateSystem) [property] L2453 - NEEDS_PARAMETERS -- ⚠️ `geometric_dimension_names` (CoordinateSystem) [property] L2462 +- ⚠️ `geometric_dimension_names` (CoordinateSystem) [property] L2463 - NEEDS_PARAMETERS -- ⚠️ `primary_directions` (CoordinateSystem) [property] L2479 +- ⚠️ `primary_directions` (CoordinateSystem) [property] L2480 - NEEDS_PARAMETERS -- ✅ `create_line_sample` (CoordinateSystem) [method] L2527 -- ✅ `create_profile_sample` (CoordinateSystem) [method] L2652 -- 📝 `zero_matrix` (CoordinateSystem) [method] L2911 +- ✅ `create_line_sample` (CoordinateSystem) [method] L2528 +- ✅ `create_profile_sample` (CoordinateSystem) [method] L2653 +- 📝 `zero_matrix` (CoordinateSystem) [method] L2912 - NEEDS_PARAMETERS, NEEDS_RETURNS
Private/Internal (45 items) - `__init__` [method] L93 - none -- `__init__` [method] L1351 - none +- `__init__` [method] L1352 - none - `__init__` [method] L502 - partial -- `__init__` [method] L956 - partial +- `__init__` [method] L957 - partial - `__new__` [method] L88 - none - `__repr__` [method] L248 - none - `__eq__` [method] L107 - partial @@ -1567,32 +1567,32 @@ Generated by `docstring_sweep.py` - `_invalidate_cache` [method] L521 - minimal - `_compute_coordinates` [method] L525 - minimal - `__getitem__` [method] L629 - partial -- `__repr__` [method] L846 - minimal -- `_invalidate_cache` [method] L980 - minimal -- `_compute_coordinates` [method] L984 - minimal -- `__getitem__` [method] L1072 - partial -- `__repr__` [method] L1253 - minimal -- `_apply_units_scaling` [method] L1792 - minimal -- `__getitem__` [method] L1848 - minimal -- `__iter__` [method] L1852 - minimal -- `__len__` [method] L1856 - minimal -- `_sympy_` [method] L1976 - partial -- `__sympy__` [method] L1988 - minimal -- `__getattr__` [method] L2020 - partial -- `__add__` [method] L2053 - minimal -- `__radd__` [method] L2057 - minimal -- `__sub__` [method] L2061 - minimal -- `__rsub__` [method] L2065 - minimal -- `__mul__` [method] L2069 - minimal -- `__rmul__` [method] L2073 - minimal -- `__truediv__` [method] L2077 - minimal -- `__rtruediv__` [method] L2081 - minimal -- `__pow__` [method] L2085 - minimal -- `__neg__` [method] L2089 - minimal -- `_cartesian_to_natural_coords` [method] L2592 - complete -- `_create_cartesian_profile` [method] L2686 - minimal -- `_create_cylindrical_profile` [method] L2759 - minimal -- `_create_spherical_profile` [method] L2827 - minimal +- `__repr__` [method] L847 - minimal +- `_invalidate_cache` [method] L981 - minimal +- `_compute_coordinates` [method] L985 - minimal +- `__getitem__` [method] L1073 - partial +- `__repr__` [method] L1254 - minimal +- `_apply_units_scaling` [method] L1793 - minimal +- `__getitem__` [method] L1849 - minimal +- `__iter__` [method] L1853 - minimal +- `__len__` [method] L1857 - minimal +- `_sympy_` [method] L1977 - partial +- `__sympy__` [method] L1989 - minimal +- `__getattr__` [method] L2021 - partial +- `__add__` [method] L2054 - minimal +- `__radd__` [method] L2058 - minimal +- `__sub__` [method] L2062 - minimal +- `__rsub__` [method] L2066 - minimal +- `__mul__` [method] L2070 - minimal +- `__rmul__` [method] L2074 - minimal +- `__truediv__` [method] L2078 - minimal +- `__rtruediv__` [method] L2082 - minimal +- `__pow__` [method] L2086 - minimal +- `__neg__` [method] L2090 - minimal +- `_cartesian_to_natural_coords` [method] L2593 - complete +- `_create_cartesian_profile` [method] L2687 - minimal +- `_create_cylindrical_profile` [method] L2760 - minimal +- `_create_spherical_profile` [method] L2828 - minimal
@@ -1635,7 +1635,7 @@ Generated by `docstring_sweep.py` - NEEDS_RETURNS - ❌ `extend_enum` [function] L82 - NEEDS_OVERVIEW, NEEDS_PARAMETERS -- ❌ `checkpoint_xdmf` [function] L6232 +- ❌ `checkpoint_xdmf` [function] L6231 - NEEDS_OVERVIEW, NEEDS_PARAMETERS - 📝 `dim` (Mesh) [property] L1092 - NEEDS_PARAMETERS @@ -1682,99 +1682,99 @@ Generated by `docstring_sweep.py` - NEEDS_PARAMETERS, NEEDS_RETURNS - 📝 `update_lvec` (Mesh) [method] L2938 - NEEDS_PARAMETERS, NEEDS_RETURNS -- ⚠️ `lvec` (Mesh) [property] L3004 +- ⚠️ `lvec` (Mesh) [property] L3003 - NEEDS_PARAMETERS -- 📝 `register_remesh_hook` (Mesh) [method] L3017 +- 📝 `register_remesh_hook` (Mesh) [method] L3016 - NEEDS_PARAMETERS, NEEDS_RETURNS -- ⚠️ `unregister_remesh_hook` (Mesh) [method] L3049 +- ⚠️ `unregister_remesh_hook` (Mesh) [method] L3048 - NEEDS_PARAMETERS -- 📝 `ephemeral_coords` (Mesh) [method] L3114 +- 📝 `ephemeral_coords` (Mesh) [method] L3113 - NEEDS_PARAMETERS, NEEDS_RETURNS -- ✅ `deform` (Mesh) [method] L3133 -- ✅ `access` (Mesh) [method] L3386 -- 📝 `N` (Mesh) [property] L3436 +- ✅ `deform` (Mesh) [method] L3132 +- ✅ `access` (Mesh) [method] L3385 +- 📝 `N` (Mesh) [property] L3435 - NEEDS_PARAMETERS -- 📝 `Gamma_N` (Mesh) [property] L3456 +- 📝 `Gamma_N` (Mesh) [property] L3455 - NEEDS_PARAMETERS -- 📝 `Gamma` (Mesh) [property] L3472 +- 📝 `Gamma` (Mesh) [property] L3471 - NEEDS_PARAMETERS -- 📝 `X` (Mesh) [property] L3486 +- 📝 `X` (Mesh) [property] L3485 - NEEDS_PARAMETERS -- ⚠️ `CoordinateSystem` (Mesh) [property] L3514 +- ⚠️ `CoordinateSystem` (Mesh) [property] L3513 - NEEDS_PARAMETERS -- 📝 `t` (Mesh) [property] L3519 +- 📝 `t` (Mesh) [property] L3518 - NEEDS_PARAMETERS, NEEDS_RETURNS -- 📝 `nullspace_rotations` (Mesh) [property] L3545 +- 📝 `nullspace_rotations` (Mesh) [property] L3544 - NEEDS_PARAMETERS -- 📝 `r` (Mesh) [property] L3570 +- 📝 `r` (Mesh) [property] L3569 - NEEDS_PARAMETERS -- 📝 `rvec` (Mesh) [property] L3585 +- 📝 `rvec` (Mesh) [property] L3584 - NEEDS_PARAMETERS -- 📝 `data` (Mesh) [property] L3605 +- 📝 `data` (Mesh) [property] L3604 - NEEDS_PARAMETERS, NEEDS_RETURNS -- 📝 `points` (Mesh) [property] L3624 +- 📝 `points` (Mesh) [property] L3623 - NEEDS_PARAMETERS -- 📝 `points` (Mesh) [method] L3666 +- 📝 `points` (Mesh) [method] L3665 - NEEDS_PARAMETERS, NEEDS_RETURNS -- 📝 `physical_coordinates` (Mesh) [property] L3685 +- 📝 `physical_coordinates` (Mesh) [property] L3684 - NEEDS_PARAMETERS -- 📝 `physical_bounds` (Mesh) [property] L3710 +- 📝 `physical_bounds` (Mesh) [property] L3709 - NEEDS_PARAMETERS -- 📝 `physical_extent` (Mesh) [property] L3741 +- 📝 `physical_extent` (Mesh) [property] L3740 - NEEDS_PARAMETERS -- 📝 `write_timestep` (Mesh) [method] L3769 +- 📝 `write_timestep` (Mesh) [method] L3768 - NEEDS_RETURNS -- 📝 `petsc_save_checkpoint` (Mesh) [method] L3903 +- 📝 `petsc_save_checkpoint` (Mesh) [method] L3902 - NEEDS_RETURNS -- 📝 `write_checkpoint` (Mesh) [method] L4004 +- 📝 `write_checkpoint` (Mesh) [method] L4003 - NEEDS_RETURNS -- 📝 `snapshot_payload` (Mesh) [method] L4144 +- 📝 `snapshot_payload` (Mesh) [method] L4143 - NEEDS_PARAMETERS, NEEDS_RETURNS -- 📝 `apply_snapshot_payload` (Mesh) [method] L4177 +- 📝 `apply_snapshot_payload` (Mesh) [method] L4176 - NEEDS_PARAMETERS, NEEDS_RETURNS -- 📝 `write` (Mesh) [method] L4241 +- 📝 `write` (Mesh) [method] L4240 - NEEDS_RETURNS -- ⚠️ `vtk` (Mesh) [method] L4371 +- ⚠️ `vtk` (Mesh) [method] L4370 - NEEDS_PARAMETERS -- 📝 `generate_xdmf` (Mesh) [method] L4380 +- 📝 `generate_xdmf` (Mesh) [method] L4379 - NEEDS_RETURNS -- ⚠️ `vars` (Mesh) [property] L4402 +- ⚠️ `vars` (Mesh) [property] L4401 - NEEDS_PARAMETERS -- ⚠️ `block_vars` (Mesh) [property] L4411 +- ⚠️ `block_vars` (Mesh) [property] L4410 - NEEDS_PARAMETERS -- 📝 `points_in_domain` (Mesh) [method] L5078 +- 📝 `points_in_domain` (Mesh) [method] L5077 - NEEDS_RETURNS -- ✅ `get_closest_cells` (Mesh) [method] L5165 -- ✅ `test_if_points_in_cells` (Mesh) [method] L5326 -- ✅ `get_closest_local_cells` (Mesh) [method] L5381 -- 📝 `get_min_radius_old` (Mesh) [method] L5575 +- ✅ `get_closest_cells` (Mesh) [method] L5164 +- ✅ `test_if_points_in_cells` (Mesh) [method] L5325 +- ✅ `get_closest_local_cells` (Mesh) [method] L5380 +- 📝 `get_min_radius_old` (Mesh) [method] L5574 - NEEDS_PARAMETERS -- 📝 `get_min_radius` (Mesh) [method] L5593 +- 📝 `get_min_radius` (Mesh) [method] L5592 - NEEDS_PARAMETERS -- ⚠️ `get_max_radius` (Mesh) [method] L5610 +- ⚠️ `get_max_radius` (Mesh) [method] L5609 - NEEDS_PARAMETERS -- 📝 `get_mean_radius` (Mesh) [method] L5625 +- 📝 `get_mean_radius` (Mesh) [method] L5624 - NEEDS_PARAMETERS, NEEDS_RETURNS -- 📝 `stats` (Mesh) [method] L5654 +- 📝 `stats` (Mesh) [method] L5653 - NEEDS_PARAMETERS -- ⚠️ `meshVariable_mask_from_label` (Mesh) [method] L5690 +- ⚠️ `meshVariable_mask_from_label` (Mesh) [method] L5689 - NEEDS_PARAMETERS -- ⚠️ `register_swarm` (Mesh) [method] L5716 +- ⚠️ `register_swarm` (Mesh) [method] L5715 - NEEDS_PARAMETERS -- ⚠️ `unregister_swarm` (Mesh) [method] L5720 +- ⚠️ `unregister_swarm` (Mesh) [method] L5719 - NEEDS_PARAMETERS -- ⚠️ `register_surface` (Mesh) [method] L5725 +- ⚠️ `register_surface` (Mesh) [method] L5724 - NEEDS_PARAMETERS -- ⚠️ `unregister_surface` (Mesh) [method] L5729 +- ⚠️ `unregister_surface` (Mesh) [method] L5728 - NEEDS_PARAMETERS -- ✅ `OT_adapt` (Mesh) [method] L5744 -- 📝 `OT_adapt_reset_reference` (Mesh) [method] L5883 +- ✅ `OT_adapt` (Mesh) [method] L5743 +- 📝 `OT_adapt_reset_reference` (Mesh) [method] L5882 - NEEDS_PARAMETERS, NEEDS_RETURNS -- 📝 `adapt` (Mesh) [method] L5899 +- 📝 `adapt` (Mesh) [method] L5898 - NEEDS_RETURNS -- 📝 `meshVariable_lookup_by_symbol` [function] L6517 +- 📝 `meshVariable_lookup_by_symbol` [function] L6516 - NEEDS_PARAMETERS, NEEDS_RETURNS -- 📝 `petsc_dm_find_labeled_points_local` [function] L6534 +- 📝 `petsc_dm_find_labeled_points_local` [function] L6533 - NEEDS_PARAMETERS, NEEDS_RETURNS
@@ -1782,12 +1782,12 @@ Generated by `docstring_sweep.py` - `__init__` [method] L257 - none - `_temporary_petsc_option` [function] L32 - none -- `__del__` [method] L3013 - none -- `_build_kd_tree_index_DS` [method] L4483 - none -- `_build_kd_tree_index` [method] L4506 - none -- `_build_kd_tree_index_PIC` [method] L4597 - none -- `_get_domain_centroids` [method] L5554 - none -- `_get_domain_kdtree` [method] L5563 - none +- `__del__` [method] L3012 - none +- `_build_kd_tree_index_DS` [method] L4482 - none +- `_build_kd_tree_index` [method] L4505 - none +- `_build_kd_tree_index_PIC` [method] L4596 - none +- `_get_domain_centroids` [method] L5553 - none +- `_get_domain_kdtree` [method] L5562 - none - `_clear_gmsh_import_options` [function] L65 - minimal - `_from_gmsh` [function] L95 - partial - `_from_plexh5` [function] L160 - partial @@ -1800,25 +1800,25 @@ Generated by `docstring_sweep.py` - `_cell_size_var` [method] L2644 - partial - `_assemble_cell_size` [method] L2674 - partial - `_resolve_slip_spec` [method] L2747 - partial -- `_assert_coord_mutation_allowed` [method] L3063 - partial -- `_coord_mutation` [method] L3099 - partial -- `_deform_mesh` [method] L3189 - partial -- `_legacy_access` [method] L3273 - partial -- `_write_petsc_reload_variable` [method] L3961 - minimal -- `_write_petsc_reload_file` [method] L3980 - minimal -- `_get_coords_for_var` [method] L4417 - partial -- `_get_coords_for_basis` [method] L4432 - partial -- `_mark_faces_inside_and_out` [method] L4653 - partial -- `_get_owned_cells_mask` [method] L4771 - partial -- `_test_if_points_in_cells_internal` [method] L4813 - partial -- `_mark_local_boundary_faces_inside_and_out` [method] L4928 - partial -- `_get_closest_local_cells_internal` [method] L5209 - complete -- `_robust_owning_cells` [method] L5446 - partial -- `_eval_use_robust_location` [method] L5473 - partial -- `_get_mesh_sizes` [method] L5501 - minimal -- `_get_mesh_centroids` [method] L5535 - partial -- `_increment_mesh_version` [method] L5733 - partial -- `_write_compat_groups` [function] L6181 - partial +- `_assert_coord_mutation_allowed` [method] L3062 - partial +- `_coord_mutation` [method] L3098 - partial +- `_deform_mesh` [method] L3188 - partial +- `_legacy_access` [method] L3272 - partial +- `_write_petsc_reload_variable` [method] L3960 - minimal +- `_write_petsc_reload_file` [method] L3979 - minimal +- `_get_coords_for_var` [method] L4416 - partial +- `_get_coords_for_basis` [method] L4431 - partial +- `_mark_faces_inside_and_out` [method] L4652 - partial +- `_get_owned_cells_mask` [method] L4770 - partial +- `_test_if_points_in_cells_internal` [method] L4812 - partial +- `_mark_local_boundary_faces_inside_and_out` [method] L4927 - partial +- `_get_closest_local_cells_internal` [method] L5208 - complete +- `_robust_owning_cells` [method] L5445 - partial +- `_eval_use_robust_location` [method] L5472 - partial +- `_get_mesh_sizes` [method] L5500 - minimal +- `_get_mesh_centroids` [method] L5534 - partial +- `_increment_mesh_version` [method] L5732 - partial +- `_write_compat_groups` [function] L6180 - partial
@@ -1969,26 +1969,28 @@ Generated by `docstring_sweep.py` **Public API:** -- 📝 `RemeshPolicy` [class] L56 +- 📝 `RemeshPolicy` [class] L75 - NEEDS_PARAMETERS, NEEDS_RETURNS -- 📝 `RemeshContext` [class] L97 +- 📝 `RemeshContext` [class] L116 - NEEDS_PARAMETERS, NEEDS_RETURNS -- ⚠️ `total_disp` (RemeshContext) [property] L127 +- ⚠️ `total_disp` (RemeshContext) [property] L154 - NEEDS_PARAMETERS -- 📝 `remesh_with_field_transfer` [function] L218 +- 📝 `remesh_with_field_transfer` [function] L274 - NEEDS_PARAMETERS +- 📝 `remap_var_set` [function] L452 + - NEEDS_PARAMETERS, NEEDS_RETURNS
Private/Internal (8 items) -- `_gather_transfer_vars` [function] L132 - partial -- `_snapshot_remap_data` [function] L173 - minimal -- `_remap_one_var` [function] L190 - partial -- `_new_coord_cache` [function] L200 - partial -- `_remesh_with_field_transfer_impl` [function] L290 - minimal -- `_iter_active_hooks` [function] L358 - partial -- `_remap_var_set` [function] L385 - partial -- `_mark_reinit_stale` [function] L478 - partial +- `_gather_transfer_vars` [function] L159 - partial +- `_snapshot_var_data` [function] L200 - partial +- `_write_var_data` [function] L224 - partial +- `_remap_one_var` [function] L246 - partial +- `_new_coord_cache` [function] L256 - partial +- `_remesh_with_field_transfer_impl` [function] L351 - minimal +- `_iter_active_hooks` [function] L425 - partial +- `_mark_reinit_stale` [function] L522 - partial
@@ -2025,16 +2027,16 @@ Generated by `docstring_sweep.py` - ⚠️ `fdiff` [method] L130 - NEEDS_PARAMETERS - ✅ `global_evaluate_nd` [function] L350 -- 📝 `evaluate_nd` [function] L901 +- 📝 `evaluate_nd` [function] L900 - NEEDS_RETURNS -- 📝 `petsc_interpolate` [function] L1091 +- 📝 `petsc_interpolate` [function] L1090 - NEEDS_RETURNS -- ⚠️ `interpolate_vars_on_mesh` [method] L1222 +- ⚠️ `interpolate_vars_on_mesh` [method] L1221 - NEEDS_PARAMETERS -- 📝 `rbf_evaluate` [function] L1381 +- 📝 `rbf_evaluate` [function] L1380 - NEEDS_RETURNS -- ✅ `dm_swarm_get_migrate_type` [function] L1503 -- 📝 `dm_swarm_set_migrate_type` [function] L1528 +- ✅ `dm_swarm_get_migrate_type` [function] L1502 +- 📝 `dm_swarm_set_migrate_type` [function] L1527 - NEEDS_RETURNS
@@ -2042,8 +2044,8 @@ Generated by `docstring_sweep.py` - `_latex` [method] L91 - none - `__new__` [method] L170 - none -- `_dmswarm_get_migrate_type` [function] L1550 - none -- `_dmswarm_set_migrate_type` [function] L1560 - none +- `_dmswarm_get_migrate_type` [function] L1549 - none +- `_dmswarm_set_migrate_type` [function] L1559 - none - `_collect_mesh_varfns` [function] L222 - complete - `_lambdify_and_evaluate` [function] L244 - complete - `_project_to_work_variable` [function] L648 - complete @@ -2543,14 +2545,14 @@ Generated by `docstring_sweep.py` - NEEDS_PARAMETERS - ✅ `compute_distance_field` (SurfaceCollection) [method] L2051 - ✅ `transfer_normals` (SurfaceCollection) [method] L2111 -- ✅ `influence_function` (SurfaceCollection) [method] L2174 -- ✅ `refinement_metric` (SurfaceCollection) [method] L2214 -- ✅ `compute_nearest_fields` (SurfaceCollection) [method] L2266 -- ✅ `create_weakness_function` (SurfaceCollection) [method] L2381 -- ✅ `fault_metric_tensor` [function] L2484 -- ✅ `fault_comb_metric` [function] L2596 -- ✅ `compose_metrics` [function] L2711 -- ✅ `fault_metric` [function] L2836 +- ✅ `influence_function` (SurfaceCollection) [method] L2175 +- ✅ `refinement_metric` (SurfaceCollection) [method] L2215 +- ✅ `compute_nearest_fields` (SurfaceCollection) [method] L2267 +- ✅ `create_weakness_function` (SurfaceCollection) [method] L2382 +- ✅ `fault_metric_tensor` [function] L2485 +- ✅ `fault_comb_metric` [function] L2597 +- ✅ `compose_metrics` [function] L2712 +- ✅ `fault_metric` [function] L2837
Private/Internal (31 items) @@ -2560,7 +2562,7 @@ Generated by `docstring_sweep.py` - `__init__` [method] L1975 - minimal - `__repr__` [method] L595 - none - `__repr__` [method] L1937 - none -- `__repr__` [method] L2412 - none +- `__repr__` [method] L2413 - none - `_to_nd_length` [function] L58 - complete - `_require_pyvista` [function] L100 - minimal - `_depth_to_km` [function] L113 - partial @@ -2580,12 +2582,12 @@ Generated by `docstring_sweep.py` - `__getitem__` [method] L2034 - minimal - `__iter__` [method] L2038 - minimal - `__len__` [method] L2042 - minimal -- `_fault_seg_distance_sym` [function] L2423 - partial -- `_fault_collect_polylines` [function] L2440 - partial -- `_fault_collect_segments` [function] L2477 - partial -- `_mesh_h0` [function] L2779 - partial -- `_fault_min_distance_np` [function] L2798 - minimal -- `_fault_mmg_metric` [function] L2815 - partial +- `_fault_seg_distance_sym` [function] L2424 - partial +- `_fault_collect_polylines` [function] L2441 - partial +- `_fault_collect_segments` [function] L2478 - partial +- `_mesh_h0` [function] L2780 - partial +- `_fault_min_distance_np` [function] L2799 - minimal +- `_fault_mmg_metric` [function] L2816 - partial
@@ -2819,164 +2821,161 @@ Generated by `docstring_sweep.py` - NEEDS_PARAMETERS, NEEDS_RETURNS - 📝 `SwarmVariable` [class] L75 - NEEDS_RETURNS -- 📝 `IndexSwarmVariable` [class] L2146 +- 📝 `IndexSwarmVariable` [class] L2210 - NEEDS_RETURNS -- 📝 `Swarm` [class] L2603 +- 📝 `Swarm` [class] L2667 - NEEDS_RETURNS -- 📝 `NodalPointSwarm` [class] L5076 +- 📝 `NodalPointSwarm` [class] L5080 - NEEDS_PARAMETERS, NEEDS_RETURNS -- ❌ `write_proxy` (SwarmVariable) [method] L2032 - - NEEDS_OVERVIEW, NEEDS_PARAMETERS -- ❌ `read_timestep` (SwarmVariable) [method] L2043 - - NEEDS_OVERVIEW, NEEDS_PARAMETERS -- ❌ `read_timestep` (Swarm) [method] L4137 - - NEEDS_OVERVIEW, NEEDS_PARAMETERS -- ❌ `advection` (Swarm) [method] L4839 - - NEEDS_OVERVIEW, NEEDS_PARAMETERS -- ❌ `advection` (NodalPointSwarm) [method] L5191 - - NEEDS_OVERVIEW, NEEDS_PARAMETERS -- ⚠️ `units` (SwarmVariable) [property] L366 +- ⚠️ `units` (SwarmVariable) [property] L365 - NEEDS_PARAMETERS -- ⚠️ `units` (SwarmVariable) [method] L371 +- ⚠️ `units` (SwarmVariable) [method] L370 - NEEDS_PARAMETERS -- ⚠️ `has_units` (SwarmVariable) [property] L380 +- ⚠️ `has_units` (SwarmVariable) [property] L379 - NEEDS_PARAMETERS -- ⚠️ `use_legacy_array` (SwarmVariable) [method] L987 +- ⚠️ `use_legacy_array` (SwarmVariable) [method] L986 - NEEDS_PARAMETERS -- ⚠️ `use_enhanced_array` (SwarmVariable) [method] L991 +- ⚠️ `use_enhanced_array` (SwarmVariable) [method] L990 - NEEDS_PARAMETERS -- 📝 `sync_disabled` (SwarmVariable) [method] L995 +- 📝 `sync_disabled` (SwarmVariable) [method] L994 - NEEDS_RETURNS -- 📝 `pack_uw_data_to_petsc` (SwarmVariable) [method] L1285 +- 📝 `pack_uw_data_to_petsc` (SwarmVariable) [method] L1283 - NEEDS_RETURNS -- 📝 `unpack_uw_data_from_petsc` (SwarmVariable) [method] L1344 +- 📝 `unpack_uw_data_from_petsc` (SwarmVariable) [method] L1342 - NEEDS_RETURNS -- 📝 `pack_raw_data_to_petsc` (SwarmVariable) [method] L1381 +- 📝 `pack_raw_data_to_petsc` (SwarmVariable) [method] L1379 - NEEDS_RETURNS -- ✅ `unpack_raw_data_from_petsc` (SwarmVariable) [method] L1422 -- ✅ `rbf_interpolate` (SwarmVariable) [method] L1492 -- ⚠️ `swarm` (SwarmVariable) [property] L1554 +- ✅ `unpack_raw_data_from_petsc` (SwarmVariable) [method] L1420 +- ✅ `rbf_interpolate` (SwarmVariable) [method] L1490 +- ⚠️ `swarm` (SwarmVariable) [property] L1552 - NEEDS_PARAMETERS -- ⚠️ `old_data` (SwarmVariable) [property] L1571 +- ⚠️ `old_data` (SwarmVariable) [property] L1569 - NEEDS_PARAMETERS -- 📝 `data` (SwarmVariable) [property] L1578 +- 📝 `data` (SwarmVariable) [property] L1576 - NEEDS_PARAMETERS -- 📝 `array` (SwarmVariable) [property] L1625 +- 📝 `array` (SwarmVariable) [property] L1623 - NEEDS_PARAMETERS -- ⚠️ `array` (SwarmVariable) [method] L1667 +- ⚠️ `array` (SwarmVariable) [method] L1665 - NEEDS_PARAMETERS -- 📝 `sym` (SwarmVariable) [property] L1682 +- 📝 `sym` (SwarmVariable) [property] L1680 - NEEDS_PARAMETERS -- 📝 `sym_1d` (SwarmVariable) [property] L1703 +- 📝 `sym_1d` (SwarmVariable) [property] L1701 - NEEDS_PARAMETERS -- ✅ `global_max` (SwarmVariable) [method] L1724 -- ✅ `global_min` (SwarmVariable) [method] L1762 -- ✅ `global_sum` (SwarmVariable) [method] L1799 -- ✅ `global_norm` (SwarmVariable) [method] L1834 -- 📝 `global_size` (SwarmVariable) [method] L1867 +- ✅ `global_max` (SwarmVariable) [method] L1722 +- ✅ `global_min` (SwarmVariable) [method] L1760 +- ✅ `global_sum` (SwarmVariable) [method] L1797 +- ✅ `global_norm` (SwarmVariable) [method] L1832 +- 📝 `global_size` (SwarmVariable) [method] L1865 - NEEDS_PARAMETERS -- 📝 `save` (SwarmVariable) [method] L1896 +- 📝 `save` (SwarmVariable) [method] L1894 + - NEEDS_RETURNS +- ✅ `write_proxy` (SwarmVariable) [method] L2030 +- 📝 `read_timestep` (SwarmVariable) [method] L2061 - NEEDS_RETURNS -- 📝 `sym` (IndexSwarmVariable) [property] L2301 +- 📝 `sym` (IndexSwarmVariable) [property] L2365 - NEEDS_PARAMETERS, NEEDS_RETURNS -- 📝 `sym_1d` (IndexSwarmVariable) [property] L2313 +- 📝 `sym_1d` (IndexSwarmVariable) [property] L2377 - NEEDS_PARAMETERS -- ✅ `createMask` (IndexSwarmVariable) [method] L2337 -- ✅ `viewMask` (IndexSwarmVariable) [method] L2385 -- 📝 `visMask` (IndexSwarmVariable) [method] L2420 +- ✅ `createMask` (IndexSwarmVariable) [method] L2401 +- ✅ `viewMask` (IndexSwarmVariable) [method] L2449 +- 📝 `visMask` (IndexSwarmVariable) [method] L2484 - NEEDS_PARAMETERS -- ⚠️ `view` (IndexSwarmVariable) [method] L2445 +- ⚠️ `view` (IndexSwarmVariable) [method] L2509 - NEEDS_PARAMETERS -- ⚠️ `mesh` (Swarm) [property] L3009 +- ⚠️ `mesh` (Swarm) [property] L3073 - NEEDS_PARAMETERS -- 📝 `mesh` (Swarm) [method] L3017 +- 📝 `mesh` (Swarm) [method] L3081 - NEEDS_RETURNS -- 📝 `local_size` (Swarm) [property] L3092 +- 📝 `local_size` (Swarm) [property] L3156 - NEEDS_PARAMETERS -- 📝 `data` (Swarm) [property] L3109 +- 📝 `data` (Swarm) [property] L3173 - NEEDS_PARAMETERS -- 📝 `points` (Swarm) [property] L3123 +- 📝 `points` (Swarm) [property] L3187 - NEEDS_PARAMETERS -- 📝 `points` (Swarm) [method] L3234 +- 📝 `points` (Swarm) [method] L3298 - NEEDS_RETURNS -- 📝 `coords` (Swarm) [property] L3293 +- 📝 `coords` (Swarm) [property] L3357 - NEEDS_PARAMETERS -- 📝 `coords` (Swarm) [method] L3343 +- 📝 `coords` (Swarm) [method] L3407 - NEEDS_RETURNS -- 📝 `units` (Swarm) [property] L3367 +- 📝 `units` (Swarm) [property] L3431 - NEEDS_PARAMETERS -- 📝 `clip_to_mesh` (Swarm) [property] L3410 +- 📝 `clip_to_mesh` (Swarm) [property] L3474 - NEEDS_PARAMETERS -- ⚠️ `clip_to_mesh` (Swarm) [method] L3431 +- ⚠️ `clip_to_mesh` (Swarm) [method] L3495 - NEEDS_PARAMETERS -- 📝 `dont_clip_to_mesh` (Swarm) [method] L3435 +- 📝 `dont_clip_to_mesh` (Swarm) [method] L3499 - NEEDS_PARAMETERS, NEEDS_RETURNS -- 📝 `migration_disabled` (Swarm) [method] L3463 +- 📝 `migration_disabled` (Swarm) [method] L3527 - NEEDS_PARAMETERS, NEEDS_RETURNS -- 📝 `migration_control` (Swarm) [method] L3483 +- 📝 `migration_control` (Swarm) [method] L3547 - NEEDS_RETURNS -- 📝 `populate` (Swarm) [method] L3549 +- 📝 `populate` (Swarm) [method] L3613 - NEEDS_RETURNS -- 📝 `migrate` (Swarm) [method] L3615 +- 📝 `migrate` (Swarm) [method] L3679 - NEEDS_PARAMETERS, NEEDS_RETURNS -- ✅ `add_particles_with_coordinates` (Swarm) [method] L3811 -- ✅ `add_particles_with_global_coordinates` (Swarm) [method] L3885 -- 📝 `save` (Swarm) [method] L3982 +- ✅ `add_particles_with_coordinates` (Swarm) [method] L3875 +- ✅ `add_particles_with_global_coordinates` (Swarm) [method] L3949 +- 📝 `save` (Swarm) [method] L4046 + - NEEDS_RETURNS +- 📝 `read_timestep` (Swarm) [method] L4201 - NEEDS_RETURNS -- ✅ `add_variable` (Swarm) [method] L4176 -- 📝 `petsc_save_checkpoint` (Swarm) [method] L4253 +- ✅ `add_variable` (Swarm) [method] L4275 +- 📝 `petsc_save_checkpoint` (Swarm) [method] L4352 - NEEDS_RETURNS -- 📝 `write_timestep` (Swarm) [method] L4277 +- 📝 `write_timestep` (Swarm) [method] L4376 - NEEDS_RETURNS -- 📝 `vars` (Swarm) [property] L4427 +- 📝 `vars` (Swarm) [property] L4526 - NEEDS_PARAMETERS -- 📝 `snapshot_payload` (Swarm) [method] L4450 +- 📝 `snapshot_payload` (Swarm) [method] L4549 - NEEDS_PARAMETERS, NEEDS_RETURNS -- 📝 `apply_snapshot_payload` (Swarm) [method] L4480 +- 📝 `apply_snapshot_payload` (Swarm) [method] L4579 - NEEDS_PARAMETERS, NEEDS_RETURNS -- ✅ `access` (Swarm) [method] L4738 -- ⚠️ `estimate_dt` (Swarm) [method] L5015 +- ✅ `access` (Swarm) [method] L4696 +- ✅ `advection` (Swarm) [method] L4797 +- ⚠️ `estimate_dt` (Swarm) [method] L5019 - NEEDS_PARAMETERS +- 📝 `advection` (NodalPointSwarm) [method] L5194 + - NEEDS_RETURNS
-Private/Internal (36 items) +Private/Internal (35 items) - `__init__` [method] L137 - none -- `__init__` [method] L2181 - none -- `__init__` [method] L2659 - none -- `__init__` [method] L5091 - none -- `_data_layout` [method] L1009 - none -- `_create_proxy_variable` [method] L1056 - none -- `__getitem__` [method] L2334 - none -- `_particle_coordinates` [property] L3289 - none -- `_data_layout` [method] L4790 - none -- `_get_map` [method] L4819 - none -- `_create_variable_array` [method] L384 - complete -- `_create_canonical_data_array` [method] L441 - complete -- `_create_array_view` [method] L526 - partial -- `_is_simple_variable` [method] L544 - minimal -- `_create_simple_array_view` [method] L548 - minimal -- `_create_tensor_array_view` [method] L761 - minimal -- `_pack_array_to_data_format` [method] L972 - minimal -- `_update` [method] L1086 - minimal -- `_update_proxy_if_stale` [method] L1106 - minimal -- `_rbf_to_meshVar` [method] L1152 - partial -- `_rbf_reduce_to_meshVar` [method] L1208 - partial -- `_warn_deprecated_sync` [method] L1275 - minimal -- `_object_viewer` [method] L1470 - minimal -- `_update` [method] L2248 - minimal -- `_on_data_changed` [method] L2256 - partial -- `_update_proxy_if_stale` [method] L2265 - partial -- `_update_proxy_variables` [method] L2452 - partial -- `__del__` [method] L2804 - partial -- `_invalidate_canonical_data` [method] L2839 - partial -- `_flush_pending_petsc_sync` [method] L2868 - partial -- `_sync_before_assembly` [method] L2901 - partial -- `_get_kdtree` [method] L2962 - minimal -- `_route_by_nearest_centroid` [method] L2975 - partial -- `_force_migration_after_mesh_change` [method] L3777 - partial -- `_snapshot_stable_name` [method] L4446 - minimal -- `_legacy_access` [method] L4597 - partial +- `__init__` [method] L2245 - none +- `__init__` [method] L2723 - none +- `__init__` [method] L5095 - none +- `_data_layout` [method] L1008 - none +- `_create_proxy_variable` [method] L1055 - none +- `__getitem__` [method] L2398 - none +- `_particle_coordinates` [property] L3353 - none +- `_data_layout` [method] L4748 - none +- `_get_map` [method] L4777 - none +- `_create_variable_array` [method] L383 - complete +- `_create_canonical_data_array` [method] L440 - complete +- `_create_array_view` [method] L525 - partial +- `_is_simple_variable` [method] L543 - minimal +- `_create_simple_array_view` [method] L547 - minimal +- `_create_tensor_array_view` [method] L760 - minimal +- `_pack_array_to_data_format` [method] L971 - minimal +- `_update` [method] L1085 - minimal +- `_update_proxy_if_stale` [method] L1105 - minimal +- `_rbf_to_meshVar` [method] L1151 - partial +- `_rbf_reduce_to_meshVar` [method] L1207 - partial +- `_warn_deprecated_sync` [method] L1273 - minimal +- `_object_viewer` [method] L1468 - minimal +- `_update` [method] L2312 - minimal +- `_on_data_changed` [method] L2320 - partial +- `_update_proxy_if_stale` [method] L2329 - partial +- `_update_proxy_variables` [method] L2516 - partial +- `__del__` [method] L2868 - partial +- `_invalidate_canonical_data` [method] L2903 - partial +- `_flush_pending_petsc_sync` [method] L2932 - partial +- `_sync_before_assembly` [method] L2965 - partial +- `_get_kdtree` [method] L3026 - minimal +- `_route_by_nearest_centroid` [method] L3039 - partial +- `_force_migration_after_mesh_change` [method] L3841 - partial +- `_snapshot_stable_name` [method] L4545 - minimal
@@ -3215,40 +3214,40 @@ Generated by `docstring_sweep.py` - ⚠️ `get_dimensionality` (_PintHelper) [method] L74 - NEEDS_PARAMETERS - ✅ `check_units_consistency` [function] L510 -- ✅ `get_dimensionality` [function] L567 -- ✅ `get_units` [function] L591 -- ✅ `non_dimensionalise` [function] L643 -- ✅ `show_nondimensional_form` [function] L887 -- ✅ `dimensionalise` [function] L933 -- ✅ `simplify_units` [function] L1092 -- ✅ `create_quantity` [function] L1121 -- ✅ `convert_units` [function] L1155 -- ✅ `to_base_units` [function] L1289 -- ✅ `to_reduced_units` [function] L1383 -- ✅ `to_compact` [function] L1469 -- 📝 `get_scaling_coefficients` [function] L1559 +- ✅ `get_dimensionality` [function] L575 +- ✅ `get_units` [function] L603 +- ✅ `non_dimensionalise` [function] L661 +- ✅ `show_nondimensional_form` [function] L913 +- ✅ `dimensionalise` [function] L964 +- ✅ `simplify_units` [function] L1123 +- ✅ `create_quantity` [function] L1156 +- ✅ `convert_units` [function] L1196 +- ✅ `to_base_units` [function] L1338 +- ✅ `to_reduced_units` [function] L1438 +- ✅ `to_compact` [function] L1530 +- 📝 `get_scaling_coefficients` [function] L1626 - NEEDS_PARAMETERS -- 📝 `set_scaling_coefficients` [function] L1577 +- 📝 `set_scaling_coefficients` [function] L1647 - NEEDS_RETURNS -- ⚠️ `is_dimensionless` [function] L1595 +- ⚠️ `is_dimensionless` [function] L1668 - NEEDS_PARAMETERS -- ⚠️ `has_units` [function] L1600 +- ⚠️ `has_units` [function] L1673 - NEEDS_PARAMETERS -- ⚠️ `same_units` [function] L1605 +- ⚠️ `same_units` [function] L1678 - NEEDS_PARAMETERS -- ⚠️ `is_velocity` [function] L1613 +- ⚠️ `is_velocity` [function] L1686 - NEEDS_PARAMETERS -- ⚠️ `is_pressure` [function] L1623 +- ⚠️ `is_pressure` [function] L1696 - NEEDS_PARAMETERS -- ✅ `validate_expression_units` [function] L1633 -- 📝 `assert_dimensionality` [function] L1658 +- ✅ `validate_expression_units` [function] L1706 +- 📝 `assert_dimensionality` [function] L1738 - NEEDS_RETURNS -- 📝 `validate_coordinates_dimensionality` [function] L1789 +- 📝 `validate_coordinates_dimensionality` [function] L1880 - NEEDS_RETURNS -- 📝 `enforce_units_consistency` [function] L1844 +- 📝 `enforce_units_consistency` [function] L1940 - NEEDS_RETURNS -- ✅ `require_units_if_active` [function] L1864 -- ✅ `convert_angle_to_degrees` [function] L1964 +- ✅ `require_units_if_active` [function] L1965 +- ✅ `convert_angle_to_degrees` [function] L2076
Private/Internal (8 items) @@ -3864,21 +3863,21 @@ Generated by `docstring_sweep.py` **Public API:** -- ❌ `mesh_adapt_meshVar` [function] L588 +- ❌ `mesh_adapt_meshVar` [function] L586 - NEEDS_OVERVIEW, NEEDS_PARAMETERS - ✅ `create_metric` [function] L88 -- ✅ `metric_from_gradient` [function] L159 -- ✅ `metric_from_field` [function] L322 -- 📝 `mesh2mesh_swarm` [function] L629 +- ✅ `metric_from_gradient` [function] L158 +- ✅ `metric_from_field` [function] L321 +- 📝 `mesh2mesh_swarm` [function] L627 - NEEDS_PARAMETERS, NEEDS_RETURNS -- ⚠️ `mesh2mesh_meshVariable` [function] L870 +- ⚠️ `mesh2mesh_meshVariable` [function] L867 - NEEDS_PARAMETERS
Private/Internal (2 items) -- `_dm_stack_bcs` [function] L451 - none -- `_dm_unstack_bcs` [function] L475 - partial +- `_dm_stack_bcs` [function] L449 - none +- `_dm_unstack_bcs` [function] L473 - partial
@@ -4107,19 +4106,18 @@ Generated by `docstring_sweep.py` **Public API:** -- 📝 `evaluate` [function] L825 - - NEEDS_RETURNS -- 📝 `global_evaluate` [function] L903 +- ✅ `evaluate` [function] L758 +- 📝 `global_evaluate` [function] L892 - NEEDS_RETURNS
Private/Internal (5 items) - `_validate_coords_not_sequence` [function] L32 - partial -- `_evaluate_impl` [function] L56 - complete -- `_global_evaluate_impl` [function] L410 - complete -- `_normalize_monotone` [function] L656 - partial -- `_apply_monotone_limit` [function] L675 - partial +- `_evaluate_impl` [function] L56 - partial +- `_global_evaluate_impl` [function] L343 - complete +- `_normalize_monotone` [function] L589 - partial +- `_apply_monotone_limit` [function] L608 - partial
diff --git a/src/underworld3/discretisation/remesh.py b/src/underworld3/discretisation/remesh.py index 6c21c227..51f27569 100644 --- a/src/underworld3/discretisation/remesh.py +++ b/src/underworld3/discretisation/remesh.py @@ -33,6 +33,7 @@ from __future__ import annotations import enum +import os import weakref from dataclasses import dataclass, field from typing import TYPE_CHECKING, Callable, Optional @@ -53,6 +54,24 @@ ] +# Monotone-limiting mode for the REMAP transfer, read ONCE at import time +# from the ``REMESH_MONOTONE`` environment variable. On a freshly-adapted +# mesh the NEW boundary DOFs sit a sagitta OUTSIDE the OLD boundary cell +# (arc vs chord), so the old P2/P3 field, FE-evaluated there, overshoots +# wildly — in parallel the migrate lands those points in a containing cell +# on another rank and the overshoot is delivered as a "valid" (un-flagged) +# value. That is the parallel free-slip v.n "leak": a corrupt boundary T/V +# remap, NOT a BC bug. The default ``"clamp"`` bounds each resampled value +# to its k-NN source-nodal range; it is bit-identical to plain FE in smooth +# regions and parallel-safe (rank-local) — the same limiter as the +# SemiLagrangian trace-back fix. Set REMESH_MONOTONE to "off" (or "0", +# "none", "false", "") to disable, or to any other mode accepted by +# ``uw.function.global_evaluate(..., monotone=...)`` (e.g. "pick"). +REMESH_MONOTONE = os.environ.get("REMESH_MONOTONE", "clamp") +if REMESH_MONOTONE.lower() in ("", "0", "off", "none", "false"): + REMESH_MONOTONE = False + + class RemeshPolicy(str, enum.Enum): """Per-variable transfer semantics on a mesh adapt. @@ -112,8 +131,16 @@ class RemeshContext: :func:`remap_var_set` with this dict and its own var list. ``scratch`` is a free-form dict where adapt ops or hooks publish - flags / per-step state (e.g. ``ale_opt_out``, a stashed - ``v_mesh``). Keys are by convention. + flags / per-step state. Two keys are in use: + + * ``"ale_opt_out"`` — published by ``OT_adapt`` + (:mod:`underworld3.meshing._ot_adapt`, from inside ``do_move`` via + ``mesh._remesh_pending_scratch``) on a reset adapt; consumed by + the ``DuDt`` ``on_remesh`` hook (:mod:`underworld3.systems.ddt`), + which falls back to REMAP for its managed history vars. + * ``"v_mesh"`` — the Phase 2 ALE convention: an ALE-style operator + hook stashes the mesh velocity here for the next solve to + consume. No producer exists yet. """ mesh: "Mesh" @@ -170,23 +197,52 @@ def _gather_transfer_vars(mesh: "Mesh") -> dict: return buckets -def _snapshot_remap_data(remap_vars): - """Copy the current ``.data`` array of every REMAP var (defensive copy).""" +def _snapshot_var_data(vars_): + """Copy the current ``.data`` array of each given var (defensive copy). + + Used for both the REMAP bucket and the operator-managed bucket in + :func:`remesh_with_field_transfer`. Vars that cannot be snapshotted + are omitted from the returned dict. + """ out = {} - for var in remap_vars: + for var in vars_: try: arr = np.asarray(var.data) if arr.size == 0: continue out[var] = arr.copy() except Exception: - # If a var's data is not addressable yet (lazy alloc, etc.), - # skip it — nothing to snapshot. The transfer pass will just - # not touch it. + # Sanctioned swallow: a var whose storage is unallocated or + # size-0 on this rank (lazy allocation / empty local partition) + # has nothing to snapshot. It is absent from the returned dict, + # so the transfer pass never touches it (the write-back twin, + # _write_var_data, skips the same vars). pass return out +def _write_var_data(var, values): + """Overwrite ``var``'s DOF values in place, tolerating unwritable storage. + + Parameters + ---------- + var : MeshVariable + Target variable; its full ``.data`` buffer is overwritten. + values : array_like or float + Replacement values, broadcastable to ``var.data``'s shape + (a scalar such as ``0.0`` zeros the whole buffer). + """ + try: + np.asarray(var.data)[...] = values + except Exception: + # Sanctioned swallow: a var whose storage is unallocated or size-0 + # on this rank (lazy allocation / empty local partition) has nowhere + # to write. Skipping leaves the variable exactly as the snapshot + # pass found it — the same vars are skipped by _snapshot_var_data, + # so no transfer is silently half-applied. + pass + + def _remap_one_var(var, old_X, new_X, mesh): """Helper kept separate for diagnostics; not currently used. @@ -269,8 +325,13 @@ def remesh_with_field_transfer( # (smooth_mesh_interior called from inside that pipeline) consult # this flag and skip their own wrap. if getattr(mesh, "_in_remesh_transfer", False): - # Surface the outer scratch dict so a nested do_move can still - # publish (e.g. an inner op flags "this is the reset adapt"). + # Nested call: run the mover only. The OUTER wrapper owns + # snapshot / transfer / hook dispatch, and it already set + # mesh._remesh_pending_scratch, so an inner adapt op can still + # publish flags there (e.g. OT_adapt marking a reset adapt). + # The True return here is unconditional and meaningless — nested + # callers cannot use it to tell whether the mesh actually moved; + # only the outer call's return value carries that information. do_move() return True mesh._in_remesh_transfer = True @@ -298,10 +359,10 @@ def _remesh_with_field_transfer_impl( managed_vars = buckets["managed"] old_X = np.asarray(mesh.X.coords).copy() - old_data = _snapshot_remap_data(remap_vars) + old_data = _snapshot_var_data(remap_vars) # Snapshot managed vars too — needed when a hook opts out of ALE # for this adapt and falls back to REMAP (see RemeshContext docs). - managed_snapshot = _snapshot_remap_data(managed_vars) + managed_snapshot = _snapshot_var_data(managed_vars) # Run the mover. It is allowed to call _deform_mesh many times; .data # is untouched by _deform_mesh, so REMAP snapshots stay valid. @@ -315,7 +376,7 @@ def _remesh_with_field_transfer_impl( return False # The one-shot REMAP dance for the generic per-variable pass. - _remap_var_set(mesh, remap_vars, old_X, new_X, old_data, verbose=verbose) + remap_var_set(mesh, remap_vars, old_X, new_X, old_data, verbose=verbose) # Operator hooks (Phase 2 ALE etc.). Currently fired even when # remap_vars is empty so a CARRY-only DDt still gets its v_mesh. @@ -330,6 +391,15 @@ def _remesh_with_field_transfer_impl( try: hook(ctx) except Exception as exc: + # Best-effort hook contract: the generic REMAP pass above has + # already secured every registered variable, so a failing + # on_remesh hook can only lose an operator-private refinement + # (e.g. an ALE history update degrades to the plain CARRY + # values). One broken operator must not abort the transfer of + # the remaining hooks' state mid-adapt, so dispatch continues; + # the failure is reported only under verbose=True. + # TODO(DESIGN): consider warning unconditionally — a silently + # degraded ALE history is hard to diagnose downstream. if verbose: uw.pprint( f" remesh_with_field_transfer: hook raised: {exc}") @@ -347,10 +417,7 @@ def _remesh_with_field_transfer_impl( # API. REINIT is for *framework-stamped* stateless vars. if extra_zero: for var in extra_zero: - try: - np.asarray(var.data)[...] = 0.0 - except Exception: - pass + _write_var_data(var, 0.0) return True @@ -377,20 +444,19 @@ def _iter_active_hooks(mesh): live.append((ref, cb)) # Prune dead refs once per dispatch. if isinstance(refs, list): - refs[:] = [ref for ref, _ in live] if live else [] + refs[:] = [ref for ref, _ in live] for _, cb in live: yield cb -def _remap_var_set(mesh, vars_, old_X, new_X, old_data, *, verbose=False): +def remap_var_set(mesh, vars_, old_X, new_X, old_data, *, verbose=False): """One-shot REMAP dance for a set of variables. Used by the generic per-variable pass in - :func:`remesh_with_field_transfer` AND exposed (as - :func:`remap_var_set`) so an operator's ``on_remesh`` hook can - force-REMAP its CARRY-managed vars on an adapt that is - ALE-incompatible (e.g. an OT_adapt reset, where the linear - ``Δx/dt → v_mesh`` interpretation breaks down). + :func:`remesh_with_field_transfer`, and public so an operator's + ``on_remesh`` hook can force-REMAP its CARRY-managed vars on an + adapt that is ALE-incompatible (e.g. an OT_adapt reset, where the + linear ``Δx/dt → v_mesh`` interpretation breaks down). Contract: on entry the mesh is at ``new_X`` and each var's ``.data`` may hold *either* the original snapshot value (CARRY: @@ -420,10 +486,7 @@ def _remap_var_set(mesh, vars_, old_X, new_X, old_data, *, verbose=False): # then deform forward and write the resampled values back. mesh._deform_mesh(old_X) for var, data in old_data.items(): - try: - np.asarray(var.data)[...] = data - except Exception: - pass + _write_var_data(var, data) resampled = {} for var in vars_: @@ -432,24 +495,11 @@ def _remap_var_set(mesh, vars_, old_X, new_X, old_data, *, verbose=False): continue try: # global_evaluate resolves off-rank targets via swarm migration. - # - # monotone='clamp' bounds each resampled value to its k-NN - # source-nodal range. On a freshly-adapted mesh the NEW boundary - # DOFs sit a sagitta OUTSIDE the OLD boundary cell (arc vs chord), - # so the old P2/P3 field, FE-evaluated there, overshoots wildly — - # in parallel the migrate lands those points in a containing cell - # on another rank and the overshoot is delivered as a "valid" - # (un-flagged) value. That is the parallel free-slip v.n "leak": - # a corrupt boundary T/V remap, NOT a BC bug. The clamp bounds it - # to the physical nodal range, is bit-identical to plain FE in - # smooth regions, and is parallel-safe (rank-local). Same limiter - # as the SemiLagrangian trace-back fix. - import os as _os - _mono = _os.environ.get("REMESH_MONOTONE", "clamp") - if _mono.lower() in ("", "0", "off", "none", "false"): - _mono = False + # REMESH_MONOTONE (module constant, see its comment) bounds the + # boundary-overshoot failure mode of the plain FE evaluation. try: - val = uw.function.global_evaluate(var.sym, target, monotone=_mono) + val = uw.function.global_evaluate( + var.sym, target, monotone=REMESH_MONOTONE) except (ValueError, NotImplementedError): # monotone needs a single-MeshVariable expr; composite / # unsupported vars fall back to plain FE (still transferred). @@ -457,7 +507,7 @@ def _remap_var_set(mesh, vars_, old_X, new_X, old_data, *, verbose=False): except Exception as exc: if verbose: uw.pprint( - f" _remap_var_set: skipping " + f" remap_var_set: skipping " f"{getattr(var, 'name', var)!r} ({exc})") continue resampled[var] = np.asarray(val).reshape( @@ -465,14 +515,8 @@ def _remap_var_set(mesh, vars_, old_X, new_X, old_data, *, verbose=False): mesh._deform_mesh(new_X) for var, val in resampled.items(): - try: - np.asarray(var.data)[...] = val - except Exception: - pass - + _write_var_data(var, val) -# Public alias for operator-hook use. -remap_var_set = _remap_var_set def _mark_reinit_stale(var): diff --git a/src/underworld3/function/functions_unit_system.py b/src/underworld3/function/functions_unit_system.py index 4d7c0a31..fa249914 100644 --- a/src/underworld3/function/functions_unit_system.py +++ b/src/underworld3/function/functions_unit_system.py @@ -77,79 +77,12 @@ def _evaluate_impl( bounded-interpolation post-process. This body is unchanged from the historical ``evaluate`` so that ``monotone=False`` is bit-identical. - This function wraps the Cython evaluate_nd implementation to automatically - handle unit conversions and return unit-aware results. + This function wraps the Cython evaluate_nd implementation to + automatically handle unit conversions and return unit-aware results. - Parameters - ---------- - expr : sympy expression or UWexpression - Expression to evaluate - coords : numpy.ndarray or UnitAwareArray - Coordinates at which to evaluate. Supported forms: - - numpy array of doubles (shape: n_points x n_dims) in model - (non-dimensional) units - - UnitAwareArray with dimensional coordinates (e.g., from mesh.X.coords) - - Both work transparently - dimensional coords are auto-converted - - Python lists/tuples of coordinates — including quantity-valued - lists such as ``[(x_qty, y_qty)]`` — are NOT supported and raise - ``TypeError`` (the coordinate-units family is unsupported; - maintainer ruling D7, 2026-07). Convert dimensional coordinates - explicitly, e.g. ``float(uw.non_dimensionalise(x_qty))``, and - pass a plain array. - coord_sys : mesh.N vector coordinate system, optional - Coordinate system to use (default: None) - other_arguments : dict, optional - Additional arguments for evaluation (default: None) - simplify : bool, optional - Whether to simplify expression (default: True) - verbose : bool, optional - Verbose output (default: False) - evalf : bool, optional - Force numerical evaluation via sympy evalf (default: False) - mode : str, optional - Evaluation mode controlling accuracy vs speed tradeoff. - Options: ``"default"`` (accurate, projection for derivatives), - ``"fast"`` (Clement gradient, RBF everywhere), - ``"projection"`` (always L2 projection). - Default: ``"default"`` - data_layout : callable, optional - Data layout specification (default: None) - check_extrapolated : bool, optional - Check for extrapolated values (default: False) - smoothing : float, optional - Smoothing parameter for L2 projection (dimensionless). - Only used when projection is active. Default: 1e-6 - rbf : bool, optional - Expert override: Force RBF interpolation everywhere. Overrides mode. - force_l2 : bool, optional - Expert override: Force L2 projection path. Overrides mode. - - Returns - ------- - UWQuantity, UnitAwareArray, or ndarray - If non-dimensional scaling is active, returns plain ndarray. - If expression has units, returns UWQuantity (scalar) or UnitAwareArray. - Otherwise returns plain ndarray. - - Notes - ----- - **Evaluation Modes:** - - - ``"fast"``: Clement gradient (no solve), direct calculation, RBF everywhere - - ``"default"``: Projection for derivatives (solve), direct otherwise, DMInterp + RBF - - ``"projection"``: Always use L2 projection (solve), DMInterp + RBF - - The `rbf` and `force_l2` parameters are expert overrides that take - precedence over the mode setting when explicitly provided. - - Examples - -------- - >>> # Works with both dimensional and non-dimensional coords - >>> result = uw.function.evaluate(T.sym, T.coords) # dimensional coords - >>> result = uw.function.evaluate(T.sym, mesh.X.coords[:, :2]) # non-dimensional - >>> if hasattr(result, 'to'): - ... result_K = result.to('K') # Unit conversion + Parameters, return values, and the evaluation-mode notes are + documented on the public wrapper, :func:`evaluate` — every parameter + here has the same meaning (the wrapper adds only ``monotone``). """ _validate_coords_not_sequence(coords) @@ -841,20 +774,60 @@ def evaluate( ): """Evaluate ``expr`` at ``coords`` with automatic unit handling. - Thin wrapper over :func:`_evaluate_impl`. See that function for the - full parameter documentation and evaluation-mode notes. With the - default ``monotone=False`` this is bit-identical to the historical - ``evaluate``. - - Coordinates are a plain ``(N, dim)`` array in model (non-dimensional) - units, or a ``UnitAwareArray``/``UWQuantity`` array which is - non-dimensionalised automatically. Python lists/tuples of individual - quantity objects (``[(x_qty, y_qty)]``) are NOT supported — convert - physical locations with :func:`underworld3.scaling.non_dimensionalise` - and pass a numpy array (units-family ruling, 2026-07). + Wraps the compiled ``evaluate_nd`` machinery so unit conversion + (dimensional coordinates in, unit-aware results out) happens + automatically. With the default ``monotone=False`` the result is + bit-identical to the historical ``evaluate``. Parameters ---------- + expr : sympy expression or UWexpression + Expression to evaluate. All MeshVariable symbols in the + expression must belong to the same mesh (``ValueError`` + otherwise — use ``var.copy_into()`` to transfer data between + meshes first). + coords : numpy.ndarray or UnitAwareArray + Coordinates at which to evaluate, shape ``(n_points, dim)``. + A plain array is taken to be in model (non-dimensional) units; + a ``UnitAwareArray`` / ``UWQuantity`` array (e.g. from + ``mesh.X.coords``) is non-dimensionalised automatically. + Python lists/tuples of individual quantity objects + (``[(x_qty, y_qty)]``) are NOT supported and raise + ``TypeError`` — convert physical locations with + :func:`underworld3.scaling.non_dimensionalise` and pass a + numpy array (units-family ruling, 2026-07). + coord_sys : mesh.N vector coordinate system, optional + Coordinate system to evaluate in (default: the mesh's own). + other_arguments : dict, optional + Additional arguments passed through to the compiled evaluator. + simplify : bool, optional + Sympy-simplify the expression before evaluation + (default: False). + verbose : bool, optional + Verbose output (default: False). + evalf : bool, optional + Force numerical evaluation via sympy ``evalf`` + (default: False). + mode : {"default", "fast", "projection"}, optional + Accuracy / speed tradeoff. ``"default"`` — L2 projection for + derivative terms, direct evaluation otherwise (DMInterp + RBF). + ``"fast"`` — Clement gradient (no solve), RBF everywhere. + ``"projection"`` — always L2 projection (a solve). + data_layout : callable, optional + Data layout specification (default: None). + check_extrapolated : bool, optional + If True, also return a boolean mask flagging points whose + value was extrapolated from outside the domain + (default: False). + smoothing : float, optional + Smoothing parameter for the L2 projection (dimensionless); + only used when a projection path is active. Default: 1e-6. + rbf : bool, optional + Expert override: force RBF interpolation everywhere. + Takes precedence over ``mode``. + force_l2 : bool, optional + Expert override: force the L2 projection path. + Takes precedence over ``mode``. monotone : bool or str, optional Opt-in bounded (monotone) interpolation, applied as a post-process to the computed result. ``False`` (default) → no @@ -864,6 +837,22 @@ def evaluate( out-of-bounds subset via (bounded) RBF interpolation. Only single-MeshVariable expressions are supported; composites raise ``ValueError``. See :func:`_apply_monotone_limit`. + + Returns + ------- + UWQuantity, UnitAwareArray, or numpy.ndarray + If non-dimensional scaling is active, a plain ndarray. If the + expression carries units, a ``UWQuantity`` (scalar) or + ``UnitAwareArray``. Otherwise a plain ndarray. With + ``check_extrapolated=True``, a ``(values, extrapolated_mask)`` + pair. + + Examples + -------- + >>> result = uw.function.evaluate(T.sym, T.coords) # dimensional coords + >>> result = uw.function.evaluate(T.sym, mesh.X.coords[:, :2]) + >>> if hasattr(result, 'to'): + ... result_K = result.to('K') # unit conversion """ # Validate up front so an unknown option fails fast (no wasted eval). monotone_mode = _normalize_monotone(monotone) diff --git a/src/underworld3/swarm.py b/src/underworld3/swarm.py index f60921bb..4c57a1b5 100644 --- a/src/underworld3/swarm.py +++ b/src/underworld3/swarm.py @@ -2028,6 +2028,26 @@ def save( @timing.routine_timer_decorator def write_proxy(self, filename: str): + """Write this variable's proxy mesh variable to an HDF5 file. + + The proxy is the RBF-interpolated mesh-variable image of the + particle data (built when the variable was created with + ``proxy_degree > 0``); this writes that mesh field via + ``MeshVariable.write``, which is often the most convenient + checkpoint/visualisation form of particle data. + + Parameters + ---------- + filename : str + Output file path, passed directly to + ``MeshVariable.write`` (conventionally ``*.h5``). + + Notes + ----- + If the variable has no proxy (``proxy_degree=0`` / + ``_proxy=False``), nothing is written; a message is printed and + the call returns. + """ # if not proxied, nothing to do. return. if not self._meshVar: uw.pprint("No proxy mesh variable that can be saved") @@ -2046,6 +2066,52 @@ def read_timestep( index: int, outputPath="", ): + """Restore this variable's values from a saved timestep. + + Reads the checkpoint files written by ``Swarm.write_timestep`` + and maps the saved (coordinate, value) pairs onto the *current* + particles by nearest-neighbour interpolation — the live swarm + need not have the same particle count or positions as the saved + one. + + Filename convention (matching ``Swarm.write_timestep( + data_filename, swarmID, swarmVars=[...], outputPath=..., + index=...)``): + + * swarm coordinates: + ``{outputPath}/{data_filename}.{swarmID}.{index:05}.h5`` + * this variable's data: + ``{outputPath}/{data_filename}.{swarmID}.{data_name}.{index:05}.h5`` + + Both files must exist (``RuntimeError`` otherwise). + + Parameters + ---------- + data_filename : str + Base name used when the checkpoint was written. (Note: the + corresponding parameter on ``Swarm.read_timestep`` is + spelled ``base_filename`` — the two signatures predate a + common convention.) + swarmID : str + Swarm identifier used when the checkpoint was written + (``swarm_id`` on ``Swarm.read_timestep``). + data_name : str + The saved variable's ``name`` (``Swarm.write_timestep`` + embeds each variable's ``.name`` in its data filename). + index : int + Timestep index (zero-padded to five digits in the + filename). + outputPath : str, optional + Directory holding the checkpoint files (default: current + directory). + + Notes + ----- + MPI-collective. Rank 0 reads the saved data in one shot; the + saved points are then routed to their owning ranks with the + same migration rule the live swarm uses, so the rank-local + nearest-neighbour lookup always sees the correct neighbours. + """ # mesh.write_timestep( "test", meshUpdates=False, meshVars=[X], outputPath="", index=0) # swarm.write_timestep("test", "swarm", swarmVars=[var], outputPath="", index=0) @@ -4140,6 +4206,41 @@ def read_timestep( outputPath: Optional[str] = "", migrate=True, ): + """Restore the swarm's particle coordinates from a saved timestep. + + Adds particles at the coordinates saved by + ``Swarm.write_timestep``; call this on a freshly-built swarm + *before* restoring variable values with + ``SwarmVariable.read_timestep``. File read (matching + ``write_timestep(filename, swarmname, index, outputPath=...)``): + + ``{outputPath}/{base_filename}.{swarm_id}.{index:05}.h5`` + + Parameters + ---------- + base_filename : str + Base name used when the checkpoint was written + (``filename`` on ``write_timestep``; note + ``SwarmVariable.read_timestep`` spells it + ``data_filename`` — the two signatures predate a common + convention). + swarm_id : str + Swarm identifier used when the checkpoint was written + (``swarmname`` on ``write_timestep``). + index : int + Timestep index (zero-padded to five digits in the + filename). + outputPath : str, optional + Directory holding the checkpoint files (default: current + directory). + migrate : bool, optional + ``True`` (default): every rank reads the saved coordinates + and keeps only the points it owns — the parallel restore + path. ``False``: every rank keeps a full copy of the saved + swarm, including points outside the local (or entire) + domain — useful for debugging, visualisation, or when the + mesh has been adapted since the save. + """ output_base_name = os.path.join(outputPath, base_filename) swarm_file = output_base_name + f".{swarm_id}.{index:05}.h5" @@ -4703,6 +4804,52 @@ def advection( evalf=False, step_limit=False, ): + r"""Advect the particle swarm through one timestep of a velocity field. + + Particle positions are updated with an explicit Runge-Kutta step + of :math:`\dot{\mathbf{x}} = \mathbf{V}(\mathbf{x})`. Velocity + is sampled with a *global* evaluation (off-rank sample points + are resolved collectively), so the call is MPI-collective: every + rank must make it, including ranks holding no particles. On + completion the swarm is migrated so each particle lands on the + rank owning its new location; particles that leave the domain + are removed (unless ``restore_points_to_domain_func`` or the + mesh's own ``return_coords_to_bounds`` returns them). + + Parameters + ---------- + V_fn : vector UW function / sympy expression + Velocity field, evaluated at particle locations. Any + expression accepted by :func:`uw.function.evaluate`, + e.g. ``stokes.u.sym``. + delta_t : float or UWQuantity + Timestep. Non-dimensionalised internally + (``uw.scaling.non_dimensionalise``), so a dimensional time + (e.g. ``uw.quantity(1000, "year")``) is valid when scaling + is active; a plain float is taken to be in model units, + consistent with the model-unit velocity. + order : int, optional + Runge-Kutta order: ``2`` (default) is the midpoint scheme; + any other value falls back to first-order forward Euler. + corrector : bool, optional + Historical predictor-corrector option; currently inert (the + corrector block is disabled). Retained for call + compatibility. Default ``False``. + restore_points_to_domain_func : callable, optional + Maps an ``(n, dim)`` coordinate array back into the domain + (periodic wrap, boundary projection, ...). Applied to the + updated positions each substep, in addition to the mesh's + own ``return_coords_to_bounds``. + evalf : bool, optional + Historical flag selecting RBF (``evalf``) velocity + sampling; currently inert — velocity is always sampled with + ``uw.function.global_evaluate``. Default ``False``. + step_limit : bool, optional + If ``True``, split ``delta_t`` into substeps no larger than + :meth:`estimate_dt` (roughly one element crossing per + substep). Default ``False`` here; note + :meth:`NodalPointSwarm.advection` defaults it to ``True``. + """ # Convert delta_t to model units if it has units # This ensures consistent arithmetic: velocity is in model units, so time must be too import underworld3 as uw @@ -5054,7 +5201,20 @@ def advection( evalf=False, step_limit=True, ): - + """Advect the nodal-point swarm one timestep (semi-Lagrangian sweep). + + Records each particle's launch point (its home mesh node) and + origin rank, then delegates to :meth:`Swarm.advection`. The + recorded launch data is what lets semi-Lagrangian schemes return + sampled values to the node the particle departed from after the + (possibly off-rank) trajectory. + + Parameters are those of :meth:`Swarm.advection`, with one + difference: ``step_limit`` defaults to ``True`` — trajectories + are substepped to at most ~one element crossing per substep + (see :meth:`Swarm.estimate_dt`), which keeps the node-return + bookkeeping robust for large ``delta_t``. + """ self._X0.data[...] = self._nX0.data[...] self._nR0.data[...] = uw.mpi.rank