From 523e528f535f117914981a35fe72e648e55a6c85 Mon Sep 17 00:00:00 2001 From: nwng04 Date: Mon, 24 Aug 2026 17:39:35 +0100 Subject: [PATCH 01/28] Add __all__ to init.py --- firedrake/__init__.py | 104 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 104 insertions(+) diff --git a/firedrake/__init__.py b/firedrake/__init__.py index 29e9ea9664..c8992ad833 100644 --- a/firedrake/__init__.py +++ b/firedrake/__init__.py @@ -46,42 +46,74 @@ def init_petsc(): del petsc from ufl import * # noqa: F401 +__all__ = ufl.__all__ + from finat.ufl import * # noqa: F401 +__all__ += finat.ufl.__all__ from pyop2 import op2 # noqa: F401 +__all__ += ["op2"] + from pyop2.mpi import COMM_WORLD, COMM_SELF # noqa: F401 +__all__ += ["COMM_WORLD", "COMM_SELF"] # Register possible citations import firedrake.citations # noqa: F401 +__all__ += ["firedrake.citations"] + petsctools.cite("FiredrakeUserManual") del petsctools from firedrake.petsc import PETSc # noqa: F401 +__all__ += ["PETSc"] + from firedrake.assemble import assemble # noqa: F401 +__all__ += ["assemble"] + from firedrake.bcs import DirichletBC, homogenize, EquationBC # noqa: F401 +__all__ += ["DirichletBC", "homogenize", "EquationBC"] + from firedrake.checkpointing import ( # noqa: F401 DumbCheckpoint, HDF5File, FILE_READ, FILE_CREATE, FILE_UPDATE, CheckpointFile ) +__all__ += ["DumbCheckpoint", "HDF5File", "FILE_READ", "FILE_CREATE", "FILE_UPDATE", "CheckpointFile"] + from firedrake.cofunction import Cofunction, RieszMap # noqa: F401 +__all__ += ["Cofunction", "RieszMap"] + from firedrake.constant import Constant # noqa: F401 +__all__ += ["Constant"] + from firedrake.deflation import DeflatedSNES, Deflation # noqa: F401 +__all__ += ["DeflatedSNES", "Deflation"] + from firedrake.exceptions import ( # noqa: F401 FiredrakeException, ConvergenceError, MismatchingDomainError, VertexOnlyMeshMissingPointsError, DofNotDefinedError, DofTypeError, SerialExecutionOnlyError, PointNotInDomainError, ) +__all__ += ["FiredrakeException", "ConvergenceError", "MismatchingDomainError", "VertexOnlyMeshMissingPointsError", "DofNotDefinedError", "DofTypeError", "SerialExecutionOnlyError", "PointNotInDomainError"] + from firedrake.function import ( # noqa: F401 Function, CoordinatelessFunction, PointEvaluator ) +__all__ += ["Function", "CoordinatelessFunction", "PointEvaluator"] + from firedrake.functionspace import ( # noqa: F401 MixedFunctionSpace, FunctionSpace, VectorFunctionSpace, TensorFunctionSpace, RestrictedFunctionSpace ) +__all__ += ["MixedFunctionSpace", "FunctionSpace", "VectorFunctionSpace", "TensorFunctionSpace", "RestrictedFunctionSpace"] + from firedrake.interpolation import ( # noqa: F401 interpolate, Interpolate, get_interpolator ) +__all__ += ["interpolate", "Interpolate", "get_interpolator"] + from firedrake.linear_solver import LinearSolver # noqa: F401 +__all__ += ["LinearSolver"] + from firedrake.preconditioners import ( # noqa: F401 PCBase, SNESBase, PCSNESBase, ASMPatchPC, ASMStarPC, ASMVankaPC, ASMLinesmoothPC, ASMExtrudedStarPC, AssembledPC, AuxiliaryOperatorPC, @@ -90,6 +122,8 @@ def init_petsc(): PoissonFDMPC, TwoLevelPC, HiptmairPC, FacetSplitPC, BDDCPC, CovariancePC, OffloadPC, AuxiliaryOperatorSNES ) +__all__ += ["PCBase", "SNESBase", "PCSNESBase", "ASMPatchPC", "ASMStarPC", "ASMVankaPC", "ASMLinesmoothPC", "ASMExtrudedStarPC", "AssembledPC", "AuxiliaryOperatorPC", "MassInvPC", "PCDPC", "PatchPC", "PlaneSmoother", "PatchSNES", "P1PC", "P1SNES", "LORPC", "GTMGPC", "PMGPC", "PMGSNES", "HypreAMS", "HypreADS", "FDMPC", "PoissonFDMPC", "TwoLevelPC", "HiptmairPC", "FacetSplitPC", "BDDCPC", "CovariancePC", "OffloadPC", "AuxiliaryOperatorSNES"] + from firedrake.mesh import ( # noqa: F401 Mesh, ExtrudedMesh, VertexOnlyMesh, RelabeledMesh, SubDomainData, UNMARKED, DistributedMeshOverlapType, @@ -97,6 +131,12 @@ def init_petsc(): AbstractMeshTopology, ExtrudedMeshTopology, Submesh, VertexOnlyMeshTopology, MeshSequenceGeometry, MeshSequenceTopology ) +__all__ += ["Mesh", "ExtrudedMesh", "VertexOnlyMesh", "RelabeledMesh", + "SubDomainData", "UNMARKED", "DistributedMeshOverlapType", + "DEFAULT_MESH_NAME", "MeshGeometry", "MeshTopology", + "AbstractMeshTopology", "ExtrudedMeshTopology", "Submesh", + "VertexOnlyMeshTopology", "MeshSequenceGeometry", "MeshSequenceTopology"] + from firedrake.mg import ( # noqa: F401 HierarchyBase, MeshHierarchy, ExtrudedMeshHierarchy, NonNestedHierarchy, SemiCoarsenedExtrudedHierarchy, SubmeshHierarchy, @@ -104,33 +144,64 @@ def init_petsc(): OpenCascadeMeshHierarchy, AdaptiveMeshHierarchy, AdaptiveTransferManager ) +__all__ += ["HierarchyBase", "MeshHierarchy", "ExtrudedMeshHierarchy", + "NonNestedHierarchy", "SemiCoarsenedExtrudedHierarchy", "SubmeshHierarchy", + "prolong", "restrict", "inject", "TransferManager", + "OpenCascadeMeshHierarchy", "AdaptiveMeshHierarchy", + "AdaptiveTransferManager"] + from firedrake.norms import errornorm, norm # noqa: F401 +__all__ += ["errornorm", "norm"] + from firedrake.nullspace import VectorSpaceBasis, MixedVectorSpaceBasis # noqa: F401 +__all__ += ["VectorSpaceBasis", "MixedVectorSpaceBasis"] + from firedrake.output import VTKFile # noqa: F401 +__all__ += ["VTKFile"] + from firedrake.parameters import ( # noqa: F401 Parameters, parameters, disable_performance_optimisations ) +__all__ += ["Parameters", "parameters", "disable_performance_optimisations"] + from firedrake.parloops import ( # noqa: F401 par_loop, direct, READ, WRITE, RW, INC, MIN, MAX ) +__all__ += ["par_loop", "direct", "READ", "WRITE", "RW", "INC", "MIN", "MAX"] + from firedrake.projection import ( # noqa: F401 project, Projector ) +__all__ += ["project", "Projector"] + from firedrake.slate import ( # noqa: F401 AssembledVector, Block, Factorization, Tensor, Inverse, Transpose, Negative, Add, Mul, Solve, BlockAssembledVector, DiagonalTensor, Reciprocal, HybridizationPC, SchurComplementBuilder, SCPC, TensorOp ) +__all__ += ["AssembledVector", "Block", "Factorization", "Tensor", "Inverse", + "Transpose", "Negative", "Add", "Mul", "Solve", "BlockAssembledVector", + "DiagonalTensor", "Reciprocal", "HybridizationPC", "SchurComplementBuilder", + "SCPC", "TensorOp"] + from firedrake.slope_limiter import ( # noqa: F401 Limiter, VertexBasedLimiter ) +__all__ += ["Limiter", "VertexBasedLimiter"] + from firedrake.solving import solve # noqa: F401 +__all__ += ["solve"] + from firedrake.ufl_expr import ( # noqa: F401 Argument, Coargument, TestFunction, TrialFunction, TestFunctions, TrialFunctions, derivative, adjoint, action, CellSize, FacetNormal ) +__all__ += ["Argument", "Coargument", "TestFunction", "TrialFunction", + "TestFunctions", "TrialFunctions", "derivative", "adjoint", + "action", "CellSize", "FacetNormal"] + from firedrake.utility_meshes import ( # noqa: F401 IntervalMesh, UnitIntervalMesh, PeriodicIntervalMesh, PeriodicUnitIntervalMesh, UnitTriangleMesh, RectangleMesh, @@ -142,33 +213,63 @@ def init_petsc(): UnitOctahedralSphereMesh, CubedSphereMesh, UnitCubedSphereMesh, TorusMesh, AnnulusMesh, SolidTorusMesh, CylinderMesh ) +__all__ += ["IntervalMesh", "UnitIntervalMesh", "PeriodicIntervalMesh", + "PeriodicUnitIntervalMesh", "UnitTriangleMesh", "RectangleMesh", + "TensorRectangleMesh", "SquareMesh", "UnitSquareMesh", "PeriodicRectangleMesh", + "PeriodicSquareMesh", "PeriodicUnitSquareMesh", "CircleManifoldMesh", + "UnitDiskMesh", "UnitBallMesh", "UnitTetrahedronMesh", "TensorBoxMesh", + "BoxMesh", "CubeMesh", "UnitCubeMesh", "PeriodicBoxMesh", "PeriodicUnitCubeMesh", + "IcosahedralSphereMesh", "UnitIcosahedralSphereMesh", "OctahedralSphereMesh", + "UnitOctahedralSphereMesh", "CubedSphereMesh", "UnitCubedSphereMesh", + "TorusMesh", "AnnulusMesh", "SolidTorusMesh", "CylinderMesh"] + from firedrake.variational_solver import ( # noqa: F401 LinearVariationalProblem, LinearVariationalSolver, NonlinearVariationalProblem, NonlinearVariationalSolver ) +__all__ += ["LinearVariationalProblem", "LinearVariationalSolver", + "NonlinearVariationalProblem", "NonlinearVariationalSolver"] + from firedrake.eigensolver import ( # noqa: F401 LinearEigenproblem, LinearEigensolver ) +__all__ += ["LinearEigenproblem", "LinearEigensolver"] + from firedrake.ensemble import ( # noqa: F401 Ensemble, EnsembleFunction, EnsembleCofunction, EnsembleFunctionSpace, EnsembleDualSpace, EnsembleBJacobiPC, EnsembleBlockDiagonalMat ) +__all__ += ["Ensemble", "EnsembleFunction", "EnsembleCofunction", + "EnsembleFunctionSpace", "EnsembleDualSpace", "EnsembleBJacobiPC", + "EnsembleBlockDiagonalMat"] + from firedrake.randomfunctiongen import * # noqa: F401 +__all__ += firedrake.randomfunctiongen.__all__ + from firedrake.external_operators import ( # noqa: F401 AbstractExternalOperator, assemble_method, PointexprOperator, point_expr, MLOperator ) +__all__ += ["AbstractExternalOperator", "assemble_method", + "PointexprOperator", "point_expr", "MLOperator"] + from firedrake.progress_bar import ProgressBar # noqa: F401 +__all__ += ["ProgressBar"] from firedrake.logging import ( # noqa: F401 set_level, set_log_handlers, set_log_level, DEBUG, INFO, WARNING, ERROR, CRITICAL, log, debug, info, warning, error, critical, info_red, info_green, info_blue, RED, GREEN, BLUE ) +__all__ += ["set_level", "set_log_handlers", "set_log_level", "DEBUG", "INFO", + "WARNING", "ERROR", "CRITICAL", "log", "debug", "info", "warning", "error", + "critical", "info_red", "info_green", "info_blue", "RED", "GREEN", "BLUE"] + from firedrake.matrix import ( # noqa: F401 MatrixBase, Matrix, ImplicitMatrix, AssembledMatrix ) +__all__ += ["MatrixBase", "Matrix", "ImplicitMatrix", "AssembledMatrix"] # Set default log level set_log_level(WARNING) @@ -176,9 +277,12 @@ def init_petsc(): # Moved functionality from firedrake._deprecation import plot # noqa: F401 +__all__ += ["plot"] + import sys sys.modules["firedrake.plot"] = plot from firedrake.plot import * # noqa: F401 +__all__ += firedrake.plot.__all__ del sys From 65999223dff997b09ab22d81a1a19438f5dbf10f Mon Sep 17 00:00:00 2001 From: nwng04 Date: Mon, 24 Aug 2026 19:14:05 +0100 Subject: [PATCH 02/28] Fix __all__ so compiles --- firedrake/__init__.py | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/firedrake/__init__.py b/firedrake/__init__.py index c8992ad833..15abfcedcc 100644 --- a/firedrake/__init__.py +++ b/firedrake/__init__.py @@ -45,11 +45,12 @@ def init_petsc(): del atexit del petsc +import ufl # NOTE TO SELF: Required for ufl.__all__ to be registered from ufl import * # noqa: F401 __all__ = ufl.__all__ from finat.ufl import * # noqa: F401 -__all__ += finat.ufl.__all__ +__all__ += ["BrokenElement", "EnrichedElement", "NodalEnrichedElement", "FiniteElement", "FiniteElementBase", "HCurlElement", "HDivElement", "WithMapping", "HDiv", "HCurl", "MixedElement", "TensorElement", "VectorElement", "RestrictedElement", "TensorProductElement"] from pyop2 import op2 # noqa: F401 __all__ += ["op2"] @@ -59,7 +60,7 @@ def init_petsc(): # Register possible citations import firedrake.citations # noqa: F401 -__all__ += ["firedrake.citations"] +__all__ += ["citations"] petsctools.cite("FiredrakeUserManual") del petsctools @@ -276,15 +277,13 @@ def init_petsc(): set_log_handlers(comm=COMM_WORLD) # Moved functionality -from firedrake._deprecation import plot # noqa: F401 -__all__ += ["plot"] - +from firedrake._deprecation import plot as _plot_module # NOTE TO SELF: Changed name to _plot_module as adding plot.__all__ to __all__ was confusing the compiler with another plot method elsewhere in the code import sys -sys.modules["firedrake.plot"] = plot +sys.modules["firedrake.plot"] = _plot_module from firedrake.plot import * # noqa: F401 -__all__ += firedrake.plot.__all__ - +__all__ += _plot_module.__all__ del sys +del _plot_module def set_blas_num_threads(): From 2be45cc2dd44fa263cedd428469906b116a6c3af Mon Sep 17 00:00:00 2001 From: nwng04 Date: Mon, 24 Aug 2026 19:46:05 +0100 Subject: [PATCH 03/28] Add utils to import list --- firedrake/__init__.py | 1 + 1 file changed, 1 insertion(+) diff --git a/firedrake/__init__.py b/firedrake/__init__.py index 15abfcedcc..ea9f5ac7fc 100644 --- a/firedrake/__init__.py +++ b/firedrake/__init__.py @@ -285,6 +285,7 @@ def init_petsc(): del sys del _plot_module +__all__ += ["utils"] #NOTE TO SELF: Added to make tests compile - check if this is required or if we should import utils in failing tests instead def set_blas_num_threads(): """Try to detect threading and either disable or warn user. From 43c3bb5eb9104d84fab4c6722bcf26685f618a4b Mon Sep 17 00:00:00 2001 From: nwng04 Date: Fri, 28 Aug 2026 08:18:09 +0100 Subject: [PATCH 04/28] Attempt to fix failing unit tests --- firedrake/__init__.py | 88 ++++++++++++++++++++++++------------------- 1 file changed, 49 insertions(+), 39 deletions(-) diff --git a/firedrake/__init__.py b/firedrake/__init__.py index ea9f5ac7fc..f0c7dbf7f5 100644 --- a/firedrake/__init__.py +++ b/firedrake/__init__.py @@ -45,9 +45,10 @@ def init_petsc(): del atexit del petsc -import ufl # NOTE TO SELF: Required for ufl.__all__ to be registered +import ufl as _ufl # NOTE TO SELF: Required for ufl.__all__ to be registered from ufl import * # noqa: F401 -__all__ = ufl.__all__ +__all__ = list(_ufl.__all__) +del _ufl from finat.ufl import * # noqa: F401 __all__ += ["BrokenElement", "EnrichedElement", "NodalEnrichedElement", "FiniteElement", "FiniteElementBase", "HCurlElement", "HDivElement", "WithMapping", "HDiv", "HCurl", "MixedElement", "TensorElement", "VectorElement", "RestrictedElement", "TensorProductElement"] @@ -100,6 +101,7 @@ def init_petsc(): Function, CoordinatelessFunction, PointEvaluator ) __all__ += ["Function", "CoordinatelessFunction", "PointEvaluator"] +#NOTE: firedrake.function has matching __all__ to this list from firedrake.functionspace import ( # noqa: F401 MixedFunctionSpace, FunctionSpace, VectorFunctionSpace, @@ -125,18 +127,20 @@ def init_petsc(): ) __all__ += ["PCBase", "SNESBase", "PCSNESBase", "ASMPatchPC", "ASMStarPC", "ASMVankaPC", "ASMLinesmoothPC", "ASMExtrudedStarPC", "AssembledPC", "AuxiliaryOperatorPC", "MassInvPC", "PCDPC", "PatchPC", "PlaneSmoother", "PatchSNES", "P1PC", "P1SNES", "LORPC", "GTMGPC", "PMGPC", "PMGSNES", "HypreAMS", "HypreADS", "FDMPC", "PoissonFDMPC", "TwoLevelPC", "HiptmairPC", "FacetSplitPC", "BDDCPC", "CovariancePC", "OffloadPC", "AuxiliaryOperatorSNES"] -from firedrake.mesh import ( # noqa: F401 - Mesh, ExtrudedMesh, VertexOnlyMesh, RelabeledMesh, - SubDomainData, UNMARKED, DistributedMeshOverlapType, - DEFAULT_MESH_NAME, MeshGeometry, MeshTopology, - AbstractMeshTopology, ExtrudedMeshTopology, Submesh, - VertexOnlyMeshTopology, MeshSequenceGeometry, MeshSequenceTopology -) -__all__ += ["Mesh", "ExtrudedMesh", "VertexOnlyMesh", "RelabeledMesh", - "SubDomainData", "UNMARKED", "DistributedMeshOverlapType", - "DEFAULT_MESH_NAME", "MeshGeometry", "MeshTopology", - "AbstractMeshTopology", "ExtrudedMeshTopology", "Submesh", - "VertexOnlyMeshTopology", "MeshSequenceGeometry", "MeshSequenceTopology"] +import firedrake.mesh as _mesh +from firedrake.mesh import * # noqa: F401 +# Mesh, ExtrudedMesh, VertexOnlyMesh, RelabeledMesh, +# SubDomainData, UNMARKED, DistributedMeshOverlapType, +# DEFAULT_MESH_NAME, MeshGeometry, MeshTopology, +# AbstractMeshTopology, ExtrudedMeshTopology, Submesh, +# VertexOnlyMeshTopology, MeshSequenceGeometry, MeshSequenceTopology +# ) +__all__ += list(_mesh.__all__)#["Mesh", "ExtrudedMesh", "VertexOnlyMesh", "RelabeledMesh", + # "SubDomainData", "UNMARKED", "DistributedMeshOverlapType", + # "DEFAULT_MESH_NAME", "MeshGeometry", "MeshTopology", + # "AbstractMeshTopology", "ExtrudedMeshTopology", "Submesh", + # "VertexOnlyMeshTopology", "MeshSequenceGeometry", "MeshSequenceTopology"] +del _mesh from firedrake.mg import ( # noqa: F401 HierarchyBase, MeshHierarchy, ExtrudedMeshHierarchy, @@ -203,26 +207,28 @@ def init_petsc(): "TestFunctions", "TrialFunctions", "derivative", "adjoint", "action", "CellSize", "FacetNormal"] -from firedrake.utility_meshes import ( # noqa: F401 - IntervalMesh, UnitIntervalMesh, PeriodicIntervalMesh, - PeriodicUnitIntervalMesh, UnitTriangleMesh, RectangleMesh, - TensorRectangleMesh, SquareMesh, UnitSquareMesh, PeriodicRectangleMesh, - PeriodicSquareMesh, PeriodicUnitSquareMesh, CircleManifoldMesh, - UnitDiskMesh, UnitBallMesh, UnitTetrahedronMesh, TensorBoxMesh, - BoxMesh, CubeMesh, UnitCubeMesh, PeriodicBoxMesh, PeriodicUnitCubeMesh, - IcosahedralSphereMesh, UnitIcosahedralSphereMesh, OctahedralSphereMesh, - UnitOctahedralSphereMesh, CubedSphereMesh, UnitCubedSphereMesh, - TorusMesh, AnnulusMesh, SolidTorusMesh, CylinderMesh -) -__all__ += ["IntervalMesh", "UnitIntervalMesh", "PeriodicIntervalMesh", - "PeriodicUnitIntervalMesh", "UnitTriangleMesh", "RectangleMesh", - "TensorRectangleMesh", "SquareMesh", "UnitSquareMesh", "PeriodicRectangleMesh", - "PeriodicSquareMesh", "PeriodicUnitSquareMesh", "CircleManifoldMesh", - "UnitDiskMesh", "UnitBallMesh", "UnitTetrahedronMesh", "TensorBoxMesh", - "BoxMesh", "CubeMesh", "UnitCubeMesh", "PeriodicBoxMesh", "PeriodicUnitCubeMesh", - "IcosahedralSphereMesh", "UnitIcosahedralSphereMesh", "OctahedralSphereMesh", - "UnitOctahedralSphereMesh", "CubedSphereMesh", "UnitCubedSphereMesh", - "TorusMesh", "AnnulusMesh", "SolidTorusMesh", "CylinderMesh"] +import firedrake.utility_meshes as _utility_meshes +from firedrake.utility_meshes import * # noqa: F401 + # IntervalMesh, UnitIntervalMesh, PeriodicIntervalMesh, + # PeriodicUnitIntervalMesh, UnitTriangleMesh, RectangleMesh, + # TensorRectangleMesh, SquareMesh, UnitSquareMesh, PeriodicRectangleMesh, + # PeriodicSquareMesh, PeriodicUnitSquareMesh, CircleManifoldMesh, + # UnitDiskMesh, UnitBallMesh, UnitTetrahedronMesh, TensorBoxMesh, + # BoxMesh, CubeMesh, UnitCubeMesh, PeriodicBoxMesh, PeriodicUnitCubeMesh, + # IcosahedralSphereMesh, UnitIcosahedralSphereMesh, OctahedralSphereMesh, + # UnitOctahedralSphereMesh, CubedSphereMesh, UnitCubedSphereMesh, + # TorusMesh, AnnulusMesh, SolidTorusMesh, CylinderMesh +#) +__all__ += list(_utility_meshes.__all__)#["IntervalMesh", "UnitIntervalMesh", "PeriodicIntervalMesh", +# "PeriodicUnitIntervalMesh", "UnitTriangleMesh", "RectangleMesh", +# "TensorRectangleMesh", "SquareMesh", "UnitSquareMesh", "PeriodicRectangleMesh", +# "PeriodicSquareMesh", "PeriodicUnitSquareMesh", "CircleManifoldMesh", +# "UnitDiskMesh", "UnitBallMesh", "UnitTetrahedronMesh", "TensorBoxMesh", +# "BoxMesh", "CubeMesh", "UnitCubeMesh", "PeriodicBoxMesh", "PeriodicUnitCubeMesh", +# "IcosahedralSphereMesh", "UnitIcosahedralSphereMesh", "OctahedralSphereMesh", +# "UnitOctahedralSphereMesh", "CubedSphereMesh", "UnitCubedSphereMesh", +# "TorusMesh", "AnnulusMesh", "SolidTorusMesh", "CylinderMesh"] +del _utility_meshes from firedrake.variational_solver import ( # noqa: F401 LinearVariationalProblem, LinearVariationalSolver, @@ -245,8 +251,10 @@ def init_petsc(): "EnsembleFunctionSpace", "EnsembleDualSpace", "EnsembleBJacobiPC", "EnsembleBlockDiagonalMat"] +import firedrake.randomfunctiongen as _randomfunctiongen from firedrake.randomfunctiongen import * # noqa: F401 -__all__ += firedrake.randomfunctiongen.__all__ +__all__ += list(_randomfunctiongen.__all__) +del _randomfunctiongen from firedrake.external_operators import ( # noqa: F401 AbstractExternalOperator, assemble_method, @@ -277,15 +285,17 @@ def init_petsc(): set_log_handlers(comm=COMM_WORLD) # Moved functionality -from firedrake._deprecation import plot as _plot_module # NOTE TO SELF: Changed name to _plot_module as adding plot.__all__ to __all__ was confusing the compiler with another plot method elsewhere in the code +from firedrake._deprecation import plot as _plot # NOTE TO SELF: Changed name to _plot as adding plot.__all__ to __all__ was confusing the compiler with another plot method elsewhere in the code import sys -sys.modules["firedrake.plot"] = _plot_module +sys.modules["firedrake.plot"] = _plot from firedrake.plot import * # noqa: F401 -__all__ += _plot_module.__all__ +__all__ += list(_plot.__all__) del sys -del _plot_module +del _plot __all__ += ["utils"] #NOTE TO SELF: Added to make tests compile - check if this is required or if we should import utils in failing tests instead +#from tsfc import default_parameters +#__all__ += ["default_parameters"] def set_blas_num_threads(): """Try to detect threading and either disable or warn user. From 213c7cfff6119ef9cd3321caa69e515f20d00bbf Mon Sep 17 00:00:00 2001 From: nwng04 Date: Tue, 1 Sep 2026 11:02:12 +0100 Subject: [PATCH 05/28] Clean up changes in init file --- firedrake/__init__.py | 75 ++++++++++++++++++++----------------------- 1 file changed, 35 insertions(+), 40 deletions(-) diff --git a/firedrake/__init__.py b/firedrake/__init__.py index f0c7dbf7f5..797b24fdbb 100644 --- a/firedrake/__init__.py +++ b/firedrake/__init__.py @@ -45,7 +45,7 @@ def init_petsc(): del atexit del petsc -import ufl as _ufl # NOTE TO SELF: Required for ufl.__all__ to be registered +import ufl as _ufl # Required for ufl.__all__ to be picked up by the compiler from ufl import * # noqa: F401 __all__ = list(_ufl.__all__) del _ufl @@ -101,7 +101,6 @@ def init_petsc(): Function, CoordinatelessFunction, PointEvaluator ) __all__ += ["Function", "CoordinatelessFunction", "PointEvaluator"] -#NOTE: firedrake.function has matching __all__ to this list from firedrake.functionspace import ( # noqa: F401 MixedFunctionSpace, FunctionSpace, VectorFunctionSpace, @@ -128,19 +127,18 @@ def init_petsc(): __all__ += ["PCBase", "SNESBase", "PCSNESBase", "ASMPatchPC", "ASMStarPC", "ASMVankaPC", "ASMLinesmoothPC", "ASMExtrudedStarPC", "AssembledPC", "AuxiliaryOperatorPC", "MassInvPC", "PCDPC", "PatchPC", "PlaneSmoother", "PatchSNES", "P1PC", "P1SNES", "LORPC", "GTMGPC", "PMGPC", "PMGSNES", "HypreAMS", "HypreADS", "FDMPC", "PoissonFDMPC", "TwoLevelPC", "HiptmairPC", "FacetSplitPC", "BDDCPC", "CovariancePC", "OffloadPC", "AuxiliaryOperatorSNES"] import firedrake.mesh as _mesh -from firedrake.mesh import * # noqa: F401 -# Mesh, ExtrudedMesh, VertexOnlyMesh, RelabeledMesh, -# SubDomainData, UNMARKED, DistributedMeshOverlapType, -# DEFAULT_MESH_NAME, MeshGeometry, MeshTopology, -# AbstractMeshTopology, ExtrudedMeshTopology, Submesh, -# VertexOnlyMeshTopology, MeshSequenceGeometry, MeshSequenceTopology -# ) -__all__ += list(_mesh.__all__)#["Mesh", "ExtrudedMesh", "VertexOnlyMesh", "RelabeledMesh", - # "SubDomainData", "UNMARKED", "DistributedMeshOverlapType", - # "DEFAULT_MESH_NAME", "MeshGeometry", "MeshTopology", - # "AbstractMeshTopology", "ExtrudedMeshTopology", "Submesh", - # "VertexOnlyMeshTopology", "MeshSequenceGeometry", "MeshSequenceTopology"] -del _mesh +from firedrake.mesh import ( # noqa: F401 + Mesh, ExtrudedMesh, VertexOnlyMesh, RelabeledMesh, + SubDomainData, UNMARKED, DistributedMeshOverlapType, + DEFAULT_MESH_NAME, MeshGeometry, MeshTopology, + AbstractMeshTopology, ExtrudedMeshTopology, Submesh, + VertexOnlyMeshTopology, MeshSequenceGeometry, MeshSequenceTopology +) +__all__ += ["Mesh", "ExtrudedMesh", "VertexOnlyMesh", "RelabeledMesh", + "SubDomainData", "UNMARKED", "DistributedMeshOverlapType", + "DEFAULT_MESH_NAME", "MeshGeometry", "MeshTopology", + "AbstractMeshTopology", "ExtrudedMeshTopology", "Submesh", + "VertexOnlyMeshTopology", "MeshSequenceGeometry", "MeshSequenceTopology"] from firedrake.mg import ( # noqa: F401 HierarchyBase, MeshHierarchy, ExtrudedMeshHierarchy, @@ -208,27 +206,26 @@ def init_petsc(): "action", "CellSize", "FacetNormal"] import firedrake.utility_meshes as _utility_meshes -from firedrake.utility_meshes import * # noqa: F401 - # IntervalMesh, UnitIntervalMesh, PeriodicIntervalMesh, - # PeriodicUnitIntervalMesh, UnitTriangleMesh, RectangleMesh, - # TensorRectangleMesh, SquareMesh, UnitSquareMesh, PeriodicRectangleMesh, - # PeriodicSquareMesh, PeriodicUnitSquareMesh, CircleManifoldMesh, - # UnitDiskMesh, UnitBallMesh, UnitTetrahedronMesh, TensorBoxMesh, - # BoxMesh, CubeMesh, UnitCubeMesh, PeriodicBoxMesh, PeriodicUnitCubeMesh, - # IcosahedralSphereMesh, UnitIcosahedralSphereMesh, OctahedralSphereMesh, - # UnitOctahedralSphereMesh, CubedSphereMesh, UnitCubedSphereMesh, - # TorusMesh, AnnulusMesh, SolidTorusMesh, CylinderMesh -#) -__all__ += list(_utility_meshes.__all__)#["IntervalMesh", "UnitIntervalMesh", "PeriodicIntervalMesh", -# "PeriodicUnitIntervalMesh", "UnitTriangleMesh", "RectangleMesh", -# "TensorRectangleMesh", "SquareMesh", "UnitSquareMesh", "PeriodicRectangleMesh", -# "PeriodicSquareMesh", "PeriodicUnitSquareMesh", "CircleManifoldMesh", -# "UnitDiskMesh", "UnitBallMesh", "UnitTetrahedronMesh", "TensorBoxMesh", -# "BoxMesh", "CubeMesh", "UnitCubeMesh", "PeriodicBoxMesh", "PeriodicUnitCubeMesh", -# "IcosahedralSphereMesh", "UnitIcosahedralSphereMesh", "OctahedralSphereMesh", -# "UnitOctahedralSphereMesh", "CubedSphereMesh", "UnitCubedSphereMesh", -# "TorusMesh", "AnnulusMesh", "SolidTorusMesh", "CylinderMesh"] -del _utility_meshes +from firedrake.utility_meshes import ( # noqa: F401 + IntervalMesh, UnitIntervalMesh, PeriodicIntervalMesh, + PeriodicUnitIntervalMesh, UnitTriangleMesh, RectangleMesh, + TensorRectangleMesh, SquareMesh, UnitSquareMesh, PeriodicRectangleMesh, + PeriodicSquareMesh, PeriodicUnitSquareMesh, CircleManifoldMesh, + UnitDiskMesh, UnitBallMesh, UnitTetrahedronMesh, TensorBoxMesh, + BoxMesh, CubeMesh, UnitCubeMesh, PeriodicBoxMesh, PeriodicUnitCubeMesh, + IcosahedralSphereMesh, UnitIcosahedralSphereMesh, OctahedralSphereMesh, + UnitOctahedralSphereMesh, CubedSphereMesh, UnitCubedSphereMesh, + TorusMesh, AnnulusMesh, SolidTorusMesh, CylinderMesh +) +__all__ += ["IntervalMesh", "UnitIntervalMesh", "PeriodicIntervalMesh", + "PeriodicUnitIntervalMesh", "UnitTriangleMesh", "RectangleMesh", + "TensorRectangleMesh", "SquareMesh", "UnitSquareMesh", "PeriodicRectangleMesh", + "PeriodicSquareMesh", "PeriodicUnitSquareMesh", "CircleManifoldMesh", + "UnitDiskMesh", "UnitBallMesh", "UnitTetrahedronMesh", "TensorBoxMesh", + "BoxMesh", "CubeMesh", "UnitCubeMesh", "PeriodicBoxMesh", "PeriodicUnitCubeMesh", + "IcosahedralSphereMesh", "UnitIcosahedralSphereMesh", "OctahedralSphereMesh", + "UnitOctahedralSphereMesh", "CubedSphereMesh", "UnitCubedSphereMesh", + "TorusMesh", "AnnulusMesh", "SolidTorusMesh", "CylinderMesh"] from firedrake.variational_solver import ( # noqa: F401 LinearVariationalProblem, LinearVariationalSolver, @@ -285,7 +282,7 @@ def init_petsc(): set_log_handlers(comm=COMM_WORLD) # Moved functionality -from firedrake._deprecation import plot as _plot # NOTE TO SELF: Changed name to _plot as adding plot.__all__ to __all__ was confusing the compiler with another plot method elsewhere in the code +from firedrake._deprecation import plot as _plot import sys sys.modules["firedrake.plot"] = _plot from firedrake.plot import * # noqa: F401 @@ -293,9 +290,7 @@ def init_petsc(): del sys del _plot -__all__ += ["utils"] #NOTE TO SELF: Added to make tests compile - check if this is required or if we should import utils in failing tests instead -#from tsfc import default_parameters -#__all__ += ["default_parameters"] +#__all__ += ["utils"] #NOTE TO SELF: Added to make tests compile - check if this is required or if we should import utils in failing tests instead def set_blas_num_threads(): """Try to detect threading and either disable or warn user. From 5234fc94446d794e29b27991041c371cb76a83f8 Mon Sep 17 00:00:00 2001 From: nwng04 Date: Tue, 1 Sep 2026 11:29:08 +0100 Subject: [PATCH 06/28] Remove unnecessary lines --- firedrake/__init__.py | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/firedrake/__init__.py b/firedrake/__init__.py index 797b24fdbb..a479397f67 100644 --- a/firedrake/__init__.py +++ b/firedrake/__init__.py @@ -126,7 +126,6 @@ def init_petsc(): ) __all__ += ["PCBase", "SNESBase", "PCSNESBase", "ASMPatchPC", "ASMStarPC", "ASMVankaPC", "ASMLinesmoothPC", "ASMExtrudedStarPC", "AssembledPC", "AuxiliaryOperatorPC", "MassInvPC", "PCDPC", "PatchPC", "PlaneSmoother", "PatchSNES", "P1PC", "P1SNES", "LORPC", "GTMGPC", "PMGPC", "PMGSNES", "HypreAMS", "HypreADS", "FDMPC", "PoissonFDMPC", "TwoLevelPC", "HiptmairPC", "FacetSplitPC", "BDDCPC", "CovariancePC", "OffloadPC", "AuxiliaryOperatorSNES"] -import firedrake.mesh as _mesh from firedrake.mesh import ( # noqa: F401 Mesh, ExtrudedMesh, VertexOnlyMesh, RelabeledMesh, SubDomainData, UNMARKED, DistributedMeshOverlapType, @@ -205,7 +204,6 @@ def init_petsc(): "TestFunctions", "TrialFunctions", "derivative", "adjoint", "action", "CellSize", "FacetNormal"] -import firedrake.utility_meshes as _utility_meshes from firedrake.utility_meshes import ( # noqa: F401 IntervalMesh, UnitIntervalMesh, PeriodicIntervalMesh, PeriodicUnitIntervalMesh, UnitTriangleMesh, RectangleMesh, @@ -282,7 +280,7 @@ def init_petsc(): set_log_handlers(comm=COMM_WORLD) # Moved functionality -from firedrake._deprecation import plot as _plot +from firedrake._deprecation import plot as _plot # noqa: F401 import sys sys.modules["firedrake.plot"] = _plot from firedrake.plot import * # noqa: F401 @@ -290,7 +288,8 @@ def init_petsc(): del sys del _plot -#__all__ += ["utils"] #NOTE TO SELF: Added to make tests compile - check if this is required or if we should import utils in failing tests instead + +__all__ += ["utils"] def set_blas_num_threads(): """Try to detect threading and either disable or warn user. From 7ab998e24077bb3dc7e55917a9fb7f8ea83603b9 Mon Sep 17 00:00:00 2001 From: nwng04 Date: Tue, 1 Sep 2026 11:55:10 +0100 Subject: [PATCH 07/28] Adjust indentation --- firedrake/__init__.py | 75 +++++++++++++++++++++++++------------------ 1 file changed, 43 insertions(+), 32 deletions(-) diff --git a/firedrake/__init__.py b/firedrake/__init__.py index a479397f67..fc470b06a4 100644 --- a/firedrake/__init__.py +++ b/firedrake/__init__.py @@ -51,7 +51,10 @@ def init_petsc(): del _ufl from finat.ufl import * # noqa: F401 -__all__ += ["BrokenElement", "EnrichedElement", "NodalEnrichedElement", "FiniteElement", "FiniteElementBase", "HCurlElement", "HDivElement", "WithMapping", "HDiv", "HCurl", "MixedElement", "TensorElement", "VectorElement", "RestrictedElement", "TensorProductElement"] +__all__ += ["BrokenElement", "EnrichedElement", "NodalEnrichedElement", + "FiniteElement","FiniteElementBase", "HCurlElement", + "HDivElement", "WithMapping", "HDiv", "HCurl", "MixedElement", + "TensorElement", "VectorElement", "RestrictedElement", "TensorProductElement"] from pyop2 import op2 # noqa: F401 __all__ += ["op2"] @@ -79,7 +82,8 @@ def init_petsc(): DumbCheckpoint, HDF5File, FILE_READ, FILE_CREATE, FILE_UPDATE, CheckpointFile ) -__all__ += ["DumbCheckpoint", "HDF5File", "FILE_READ", "FILE_CREATE", "FILE_UPDATE", "CheckpointFile"] +__all__ += ["DumbCheckpoint", "HDF5File", "FILE_READ", "FILE_CREATE", + "FILE_UPDATE", "CheckpointFile"] from firedrake.cofunction import Cofunction, RieszMap # noqa: F401 __all__ += ["Cofunction", "RieszMap"] @@ -95,7 +99,9 @@ def init_petsc(): VertexOnlyMeshMissingPointsError, DofNotDefinedError, DofTypeError, SerialExecutionOnlyError, PointNotInDomainError, ) -__all__ += ["FiredrakeException", "ConvergenceError", "MismatchingDomainError", "VertexOnlyMeshMissingPointsError", "DofNotDefinedError", "DofTypeError", "SerialExecutionOnlyError", "PointNotInDomainError"] +__all__ += ["FiredrakeException", "ConvergenceError", "MismatchingDomainError", + "VertexOnlyMeshMissingPointsError", "DofNotDefinedError", "DofTypeError", + "SerialExecutionOnlyError", "PointNotInDomainError"] from firedrake.function import ( # noqa: F401 Function, CoordinatelessFunction, PointEvaluator @@ -106,7 +112,8 @@ def init_petsc(): MixedFunctionSpace, FunctionSpace, VectorFunctionSpace, TensorFunctionSpace, RestrictedFunctionSpace ) -__all__ += ["MixedFunctionSpace", "FunctionSpace", "VectorFunctionSpace", "TensorFunctionSpace", "RestrictedFunctionSpace"] +__all__ += ["MixedFunctionSpace", "FunctionSpace", "VectorFunctionSpace", + "TensorFunctionSpace", "RestrictedFunctionSpace"] from firedrake.interpolation import ( # noqa: F401 interpolate, Interpolate, get_interpolator @@ -124,7 +131,11 @@ def init_petsc(): PoissonFDMPC, TwoLevelPC, HiptmairPC, FacetSplitPC, BDDCPC, CovariancePC, OffloadPC, AuxiliaryOperatorSNES ) -__all__ += ["PCBase", "SNESBase", "PCSNESBase", "ASMPatchPC", "ASMStarPC", "ASMVankaPC", "ASMLinesmoothPC", "ASMExtrudedStarPC", "AssembledPC", "AuxiliaryOperatorPC", "MassInvPC", "PCDPC", "PatchPC", "PlaneSmoother", "PatchSNES", "P1PC", "P1SNES", "LORPC", "GTMGPC", "PMGPC", "PMGSNES", "HypreAMS", "HypreADS", "FDMPC", "PoissonFDMPC", "TwoLevelPC", "HiptmairPC", "FacetSplitPC", "BDDCPC", "CovariancePC", "OffloadPC", "AuxiliaryOperatorSNES"] +__all__ += ["PCBase", "SNESBase", "PCSNESBase", "ASMPatchPC", "ASMStarPC", "ASMVankaPC", + "ASMLinesmoothPC", "ASMExtrudedStarPC", "AssembledPC", "AuxiliaryOperatorPC", + "MassInvPC", "PCDPC", "PatchPC", "PlaneSmoother", "PatchSNES", "P1PC", "P1SNES", + "LORPC", "GTMGPC", "PMGPC", "PMGSNES", "HypreAMS", "HypreADS", "FDMPC", + "PoissonFDMPC", "TwoLevelPC", "HiptmairPC", "FacetSplitPC", "BDDCPC", "CovariancePC", "OffloadPC", "AuxiliaryOperatorSNES"] from firedrake.mesh import ( # noqa: F401 Mesh, ExtrudedMesh, VertexOnlyMesh, RelabeledMesh, @@ -134,10 +145,10 @@ def init_petsc(): VertexOnlyMeshTopology, MeshSequenceGeometry, MeshSequenceTopology ) __all__ += ["Mesh", "ExtrudedMesh", "VertexOnlyMesh", "RelabeledMesh", - "SubDomainData", "UNMARKED", "DistributedMeshOverlapType", - "DEFAULT_MESH_NAME", "MeshGeometry", "MeshTopology", - "AbstractMeshTopology", "ExtrudedMeshTopology", "Submesh", - "VertexOnlyMeshTopology", "MeshSequenceGeometry", "MeshSequenceTopology"] + "SubDomainData", "UNMARKED", "DistributedMeshOverlapType", + "DEFAULT_MESH_NAME", "MeshGeometry", "MeshTopology", + "AbstractMeshTopology", "ExtrudedMeshTopology", "Submesh", + "VertexOnlyMeshTopology", "MeshSequenceGeometry", "MeshSequenceTopology"] from firedrake.mg import ( # noqa: F401 HierarchyBase, MeshHierarchy, ExtrudedMeshHierarchy, @@ -147,10 +158,10 @@ def init_petsc(): AdaptiveTransferManager ) __all__ += ["HierarchyBase", "MeshHierarchy", "ExtrudedMeshHierarchy", - "NonNestedHierarchy", "SemiCoarsenedExtrudedHierarchy", "SubmeshHierarchy", - "prolong", "restrict", "inject", "TransferManager", - "OpenCascadeMeshHierarchy", "AdaptiveMeshHierarchy", - "AdaptiveTransferManager"] + "NonNestedHierarchy", "SemiCoarsenedExtrudedHierarchy", + "SubmeshHierarchy", "prolong", "restrict", "inject", + "TransferManager", "OpenCascadeMeshHierarchy", + "AdaptiveMeshHierarchy", "AdaptiveTransferManager"] from firedrake.norms import errornorm, norm # noqa: F401 __all__ += ["errornorm", "norm"] @@ -183,9 +194,9 @@ def init_petsc(): SCPC, TensorOp ) __all__ += ["AssembledVector", "Block", "Factorization", "Tensor", "Inverse", - "Transpose", "Negative", "Add", "Mul", "Solve", "BlockAssembledVector", - "DiagonalTensor", "Reciprocal", "HybridizationPC", "SchurComplementBuilder", - "SCPC", "TensorOp"] + "Transpose", "Negative", "Add", "Mul", "Solve", "BlockAssembledVector", + "DiagonalTensor", "Reciprocal", "HybridizationPC", "SchurComplementBuilder", + "SCPC", "TensorOp"] from firedrake.slope_limiter import ( # noqa: F401 Limiter, VertexBasedLimiter @@ -201,8 +212,8 @@ def init_petsc(): action, CellSize, FacetNormal ) __all__ += ["Argument", "Coargument", "TestFunction", "TrialFunction", - "TestFunctions", "TrialFunctions", "derivative", "adjoint", - "action", "CellSize", "FacetNormal"] + "TestFunctions", "TrialFunctions", "derivative", "adjoint", + "action", "CellSize", "FacetNormal"] from firedrake.utility_meshes import ( # noqa: F401 IntervalMesh, UnitIntervalMesh, PeriodicIntervalMesh, @@ -216,21 +227,21 @@ def init_petsc(): TorusMesh, AnnulusMesh, SolidTorusMesh, CylinderMesh ) __all__ += ["IntervalMesh", "UnitIntervalMesh", "PeriodicIntervalMesh", - "PeriodicUnitIntervalMesh", "UnitTriangleMesh", "RectangleMesh", - "TensorRectangleMesh", "SquareMesh", "UnitSquareMesh", "PeriodicRectangleMesh", - "PeriodicSquareMesh", "PeriodicUnitSquareMesh", "CircleManifoldMesh", - "UnitDiskMesh", "UnitBallMesh", "UnitTetrahedronMesh", "TensorBoxMesh", - "BoxMesh", "CubeMesh", "UnitCubeMesh", "PeriodicBoxMesh", "PeriodicUnitCubeMesh", - "IcosahedralSphereMesh", "UnitIcosahedralSphereMesh", "OctahedralSphereMesh", - "UnitOctahedralSphereMesh", "CubedSphereMesh", "UnitCubedSphereMesh", - "TorusMesh", "AnnulusMesh", "SolidTorusMesh", "CylinderMesh"] + "PeriodicUnitIntervalMesh", "UnitTriangleMesh", "RectangleMesh", + "TensorRectangleMesh", "SquareMesh", "UnitSquareMesh", "PeriodicRectangleMesh", + "PeriodicSquareMesh", "PeriodicUnitSquareMesh", "CircleManifoldMesh", + "UnitDiskMesh", "UnitBallMesh", "UnitTetrahedronMesh", "TensorBoxMesh", + "BoxMesh", "CubeMesh", "UnitCubeMesh", "PeriodicBoxMesh", "PeriodicUnitCubeMesh", + "IcosahedralSphereMesh", "UnitIcosahedralSphereMesh", "OctahedralSphereMesh", + "UnitOctahedralSphereMesh", "CubedSphereMesh", "UnitCubedSphereMesh", + "TorusMesh", "AnnulusMesh", "SolidTorusMesh", "CylinderMesh"] from firedrake.variational_solver import ( # noqa: F401 LinearVariationalProblem, LinearVariationalSolver, NonlinearVariationalProblem, NonlinearVariationalSolver ) __all__ += ["LinearVariationalProblem", "LinearVariationalSolver", - "NonlinearVariationalProblem", "NonlinearVariationalSolver"] + "NonlinearVariationalProblem", "NonlinearVariationalSolver"] from firedrake.eigensolver import ( # noqa: F401 LinearEigenproblem, LinearEigensolver @@ -243,8 +254,8 @@ def init_petsc(): EnsembleBlockDiagonalMat ) __all__ += ["Ensemble", "EnsembleFunction", "EnsembleCofunction", - "EnsembleFunctionSpace", "EnsembleDualSpace", "EnsembleBJacobiPC", - "EnsembleBlockDiagonalMat"] + "EnsembleFunctionSpace", "EnsembleDualSpace", + "EnsembleBJacobiPC", "EnsembleBlockDiagonalMat"] import firedrake.randomfunctiongen as _randomfunctiongen from firedrake.randomfunctiongen import * # noqa: F401 @@ -256,7 +267,7 @@ def init_petsc(): PointexprOperator, point_expr, MLOperator ) __all__ += ["AbstractExternalOperator", "assemble_method", - "PointexprOperator", "point_expr", "MLOperator"] + "PointexprOperator", "point_expr", "MLOperator"] from firedrake.progress_bar import ProgressBar # noqa: F401 __all__ += ["ProgressBar"] @@ -267,8 +278,8 @@ def init_petsc(): critical, info_red, info_green, info_blue, RED, GREEN, BLUE ) __all__ += ["set_level", "set_log_handlers", "set_log_level", "DEBUG", "INFO", - "WARNING", "ERROR", "CRITICAL", "log", "debug", "info", "warning", "error", - "critical", "info_red", "info_green", "info_blue", "RED", "GREEN", "BLUE"] + "WARNING", "ERROR", "CRITICAL", "log", "debug", "info", "warning", "error", + "critical", "info_red", "info_green", "info_blue", "RED", "GREEN", "BLUE"] from firedrake.matrix import ( # noqa: F401 MatrixBase, Matrix, ImplicitMatrix, AssembledMatrix From 2b1fb07ff4770d4ceabd4b1b8211636fa2986ab6 Mon Sep 17 00:00:00 2001 From: nwng04 Date: Tue, 1 Sep 2026 13:15:19 +0100 Subject: [PATCH 08/28] Alter spacing to pass linting tests --- firedrake/__init__.py | 79 ++++++++++++++++++++++++++----------------- 1 file changed, 48 insertions(+), 31 deletions(-) diff --git a/firedrake/__init__.py b/firedrake/__init__.py index fc470b06a4..bbcc4f01c2 100644 --- a/firedrake/__init__.py +++ b/firedrake/__init__.py @@ -51,12 +51,14 @@ def init_petsc(): del _ufl from finat.ufl import * # noqa: F401 -__all__ += ["BrokenElement", "EnrichedElement", "NodalEnrichedElement", - "FiniteElement","FiniteElementBase", "HCurlElement", - "HDivElement", "WithMapping", "HDiv", "HCurl", "MixedElement", - "TensorElement", "VectorElement", "RestrictedElement", "TensorProductElement"] - -from pyop2 import op2 # noqa: F401 +__all__ += [ + "BrokenElement", "EnrichedElement", "NodalEnrichedElement", + "FiniteElement", "FiniteElementBase", "HCurlElement", + "HDivElement", "WithMapping", "HDiv", "HCurl", "MixedElement", + "TensorElement", "VectorElement", "RestrictedElement", "TensorProductElement", +] + +from pyop2 import op2 # noqa: F401 __all__ += ["op2"] from pyop2.mpi import COMM_WORLD, COMM_SELF # noqa: F401 @@ -82,8 +84,10 @@ def init_petsc(): DumbCheckpoint, HDF5File, FILE_READ, FILE_CREATE, FILE_UPDATE, CheckpointFile ) -__all__ += ["DumbCheckpoint", "HDF5File", "FILE_READ", "FILE_CREATE", - "FILE_UPDATE", "CheckpointFile"] +__all__ += [ + "DumbCheckpoint", "HDF5File", "FILE_READ", "FILE_CREATE", + "FILE_UPDATE", "CheckpointFile", +] from firedrake.cofunction import Cofunction, RieszMap # noqa: F401 __all__ += ["Cofunction", "RieszMap"] @@ -99,9 +103,11 @@ def init_petsc(): VertexOnlyMeshMissingPointsError, DofNotDefinedError, DofTypeError, SerialExecutionOnlyError, PointNotInDomainError, ) -__all__ += ["FiredrakeException", "ConvergenceError", "MismatchingDomainError", - "VertexOnlyMeshMissingPointsError", "DofNotDefinedError", "DofTypeError", - "SerialExecutionOnlyError", "PointNotInDomainError"] +__all__ += [ + "FiredrakeException", "ConvergenceError", "MismatchingDomainError", + "VertexOnlyMeshMissingPointsError", "DofNotDefinedError", "DofTypeError", + "SerialExecutionOnlyError", "PointNotInDomainError", +] from firedrake.function import ( # noqa: F401 Function, CoordinatelessFunction, PointEvaluator @@ -112,8 +118,10 @@ def init_petsc(): MixedFunctionSpace, FunctionSpace, VectorFunctionSpace, TensorFunctionSpace, RestrictedFunctionSpace ) -__all__ += ["MixedFunctionSpace", "FunctionSpace", "VectorFunctionSpace", - "TensorFunctionSpace", "RestrictedFunctionSpace"] +__all__ += [ + "MixedFunctionSpace", "FunctionSpace", "VectorFunctionSpace", + "TensorFunctionSpace", "RestrictedFunctionSpace", +] from firedrake.interpolation import ( # noqa: F401 interpolate, Interpolate, get_interpolator @@ -131,11 +139,14 @@ def init_petsc(): PoissonFDMPC, TwoLevelPC, HiptmairPC, FacetSplitPC, BDDCPC, CovariancePC, OffloadPC, AuxiliaryOperatorSNES ) -__all__ += ["PCBase", "SNESBase", "PCSNESBase", "ASMPatchPC", "ASMStarPC", "ASMVankaPC", - "ASMLinesmoothPC", "ASMExtrudedStarPC", "AssembledPC", "AuxiliaryOperatorPC", - "MassInvPC", "PCDPC", "PatchPC", "PlaneSmoother", "PatchSNES", "P1PC", "P1SNES", - "LORPC", "GTMGPC", "PMGPC", "PMGSNES", "HypreAMS", "HypreADS", "FDMPC", - "PoissonFDMPC", "TwoLevelPC", "HiptmairPC", "FacetSplitPC", "BDDCPC", "CovariancePC", "OffloadPC", "AuxiliaryOperatorSNES"] +__all__ += [ + "PCBase", "SNESBase", "PCSNESBase", "ASMPatchPC", "ASMStarPC", "ASMVankaPC", + "ASMLinesmoothPC", "ASMExtrudedStarPC", "AssembledPC", "AuxiliaryOperatorPC", + "MassInvPC", "PCDPC", "PatchPC", "PlaneSmoother", "PatchSNES", "P1PC", "P1SNES", + "LORPC", "GTMGPC", "PMGPC", "PMGSNES", "HypreAMS", "HypreADS", "FDMPC", + "PoissonFDMPC", "TwoLevelPC", "HiptmairPC", "FacetSplitPC", "BDDCPC", + "CovariancePC", "OffloadPC", "AuxiliaryOperatorSNES", +] from firedrake.mesh import ( # noqa: F401 Mesh, ExtrudedMesh, VertexOnlyMesh, RelabeledMesh, @@ -144,11 +155,13 @@ def init_petsc(): AbstractMeshTopology, ExtrudedMeshTopology, Submesh, VertexOnlyMeshTopology, MeshSequenceGeometry, MeshSequenceTopology ) -__all__ += ["Mesh", "ExtrudedMesh", "VertexOnlyMesh", "RelabeledMesh", - "SubDomainData", "UNMARKED", "DistributedMeshOverlapType", - "DEFAULT_MESH_NAME", "MeshGeometry", "MeshTopology", - "AbstractMeshTopology", "ExtrudedMeshTopology", "Submesh", - "VertexOnlyMeshTopology", "MeshSequenceGeometry", "MeshSequenceTopology"] +__all__ += [ + "Mesh", "ExtrudedMesh", "VertexOnlyMesh", "RelabeledMesh", + "SubDomainData", "UNMARKED", "DistributedMeshOverlapType", + "DEFAULT_MESH_NAME", "MeshGeometry", "MeshTopology", + "AbstractMeshTopology", "ExtrudedMeshTopology", "Submesh", + "VertexOnlyMeshTopology", "MeshSequenceGeometry", "MeshSequenceTopology", +] from firedrake.mg import ( # noqa: F401 HierarchyBase, MeshHierarchy, ExtrudedMeshHierarchy, @@ -157,11 +170,13 @@ def init_petsc(): OpenCascadeMeshHierarchy, AdaptiveMeshHierarchy, AdaptiveTransferManager ) -__all__ += ["HierarchyBase", "MeshHierarchy", "ExtrudedMeshHierarchy", - "NonNestedHierarchy", "SemiCoarsenedExtrudedHierarchy", - "SubmeshHierarchy", "prolong", "restrict", "inject", - "TransferManager", "OpenCascadeMeshHierarchy", - "AdaptiveMeshHierarchy", "AdaptiveTransferManager"] +__all__ += [ + "HierarchyBase", "MeshHierarchy", "ExtrudedMeshHierarchy", + "NonNestedHierarchy", "SemiCoarsenedExtrudedHierarchy", + "SubmeshHierarchy", "prolong", "restrict", "inject", + "TransferManager", "OpenCascadeMeshHierarchy", + "AdaptiveMeshHierarchy", "AdaptiveTransferManager", +] from firedrake.norms import errornorm, norm # noqa: F401 __all__ += ["errornorm", "norm"] @@ -253,9 +268,11 @@ def init_petsc(): EnsembleFunctionSpace, EnsembleDualSpace, EnsembleBJacobiPC, EnsembleBlockDiagonalMat ) -__all__ += ["Ensemble", "EnsembleFunction", "EnsembleCofunction", - "EnsembleFunctionSpace", "EnsembleDualSpace", - "EnsembleBJacobiPC", "EnsembleBlockDiagonalMat"] +__all__ += [ + "Ensemble", "EnsembleFunction", "EnsembleCofunction", + "EnsembleFunctionSpace", "EnsembleDualSpace", + "EnsembleBJacobiPC", "EnsembleBlockDiagonalMat", +] import firedrake.randomfunctiongen as _randomfunctiongen from firedrake.randomfunctiongen import * # noqa: F401 From c3c576066f205b720eb5a85cc0a5077c0f261ecf Mon Sep 17 00:00:00 2001 From: nwng04 Date: Tue, 1 Sep 2026 13:24:24 +0100 Subject: [PATCH 09/28] Move utils import --- firedrake/__init__.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/firedrake/__init__.py b/firedrake/__init__.py index bbcc4f01c2..b3735ea0bb 100644 --- a/firedrake/__init__.py +++ b/firedrake/__init__.py @@ -303,12 +303,14 @@ def init_petsc(): ) __all__ += ["MatrixBase", "Matrix", "ImplicitMatrix", "AssembledMatrix"] +__all__ += ["utils"] + # Set default log level set_log_level(WARNING) set_log_handlers(comm=COMM_WORLD) # Moved functionality -from firedrake._deprecation import plot as _plot # noqa: F401 +from firedrake._deprecation import plot as _plot # noqa: F401 import sys sys.modules["firedrake.plot"] = _plot from firedrake.plot import * # noqa: F401 @@ -317,8 +319,6 @@ def init_petsc(): del _plot -__all__ += ["utils"] - def set_blas_num_threads(): """Try to detect threading and either disable or warn user. From cf4e29ac3de8f45f40f3f1e704e819b290ce670f Mon Sep 17 00:00:00 2001 From: nwng04 Date: Tue, 1 Sep 2026 15:17:28 +0100 Subject: [PATCH 10/28] Remove duplicate objects imports - for sphix tests --- firedrake/assemble.py | 3 --- firedrake/bcs.py | 2 +- firedrake/checkpointing.py | 2 +- firedrake/constant.py | 3 --- firedrake/deflation.py | 2 -- firedrake/function.py | 2 +- firedrake/matrix.py | 2 +- firedrake/mesh.py | 2 +- firedrake/solving.py | 2 -- 9 files changed, 5 insertions(+), 15 deletions(-) diff --git a/firedrake/assemble.py b/firedrake/assemble.py index 6dd7c4f03f..4b55ac3398 100644 --- a/firedrake/assemble.py +++ b/firedrake/assemble.py @@ -36,9 +36,6 @@ from pyop2.types.mat import _GlobalMatPayload, _DatMatPayload -__all__ = "assemble", - - _FORM_CACHE_KEY = "firedrake.assemble.FormAssembler" """Entry used in form cache to try and reuse assemblers where possible.""" diff --git a/firedrake/bcs.py b/firedrake/bcs.py index 16bed26f60..75816771c5 100644 --- a/firedrake/bcs.py +++ b/firedrake/bcs.py @@ -25,7 +25,7 @@ from firedrake.function import Function from firedrake.cofunction import Cofunction -__all__ = ['DirichletBC', 'homogenize', 'EquationBC'] +__all__ = ['homogenize', 'EquationBC'] class BCBase(object): diff --git a/firedrake/checkpointing.py b/firedrake/checkpointing.py index a2286bccbe..baa1b9a80e 100644 --- a/firedrake/checkpointing.py +++ b/firedrake/checkpointing.py @@ -23,7 +23,7 @@ import h5py -__all__ = ["DumbCheckpoint", "HDF5File", "FILE_READ", "FILE_CREATE", "FILE_UPDATE", "CheckpointFile"] +__all__ = ["HDF5File", "FILE_READ", "FILE_CREATE", "FILE_UPDATE"] FILE_READ = PETSc.Viewer.Mode.READ diff --git a/firedrake/constant.py b/firedrake/constant.py index 948e359492..a454c6f637 100644 --- a/firedrake/constant.py +++ b/firedrake/constant.py @@ -23,9 +23,6 @@ from firedrake.adjoint_utils.constant import ConstantMixin -__all__ = ['Constant'] - - def _create_dat(op2type, value, comm): if op2type is op2.Global and comm is None: raise ValueError("Attempted to create pyop2 Global with no communicator") diff --git a/firedrake/deflation.py b/firedrake/deflation.py index 030ec9b92e..f569d37f8c 100644 --- a/firedrake/deflation.py +++ b/firedrake/deflation.py @@ -8,8 +8,6 @@ import weakref -__all__ = ['DeflatedSNES', 'Deflation'] - class DeflatedSNES(SNESBase): """ diff --git a/firedrake/function.py b/firedrake/function.py index 7635c34e8b..1c7eafcfff 100644 --- a/firedrake/function.py +++ b/firedrake/function.py @@ -30,7 +30,7 @@ from firedrake.exceptions import PointNotInDomainError -__all__ = ['Function', 'CoordinatelessFunction', 'PointEvaluator'] +__all__ = ['CoordinatelessFunction', 'PointEvaluator'] class _CFunction(ctypes.Structure): diff --git a/firedrake/matrix.py b/firedrake/matrix.py index 276edf1756..c588a5900e 100644 --- a/firedrake/matrix.py +++ b/firedrake/matrix.py @@ -11,7 +11,7 @@ from firedrake.matrix_free import ImplicitMatrixContext from firedrake.slate import slate -__all__ = ("MatrixBase", "Matrix", "ImplicitMatrix", "AssembledMatrix") +__all__ = ("MatrixBase", "ImplicitMatrix", "AssembledMatrix") class DummyOP2Mat: diff --git a/firedrake/mesh.py b/firedrake/mesh.py index be425bf581..2a63a41c50 100644 --- a/firedrake/mesh.py +++ b/firedrake/mesh.py @@ -61,7 +61,7 @@ __all__ = [ - 'Mesh', 'ExtrudedMesh', 'VertexOnlyMesh', 'RelabeledMesh', + 'ExtrudedMesh', 'RelabeledMesh', 'SubDomainData', 'UNMARKED', 'DistributedMeshOverlapType', 'DEFAULT_MESH_NAME', 'MeshGeometry', 'MeshTopology', 'AbstractMeshTopology', 'ExtrudedMeshTopology', 'VertexOnlyMeshTopology', diff --git a/firedrake/solving.py b/firedrake/solving.py index 23a202137f..6139465b4e 100644 --- a/firedrake/solving.py +++ b/firedrake/solving.py @@ -17,8 +17,6 @@ # You should have received a copy of the GNU Lesser General Public License # along with DOLFIN. If not, see . -__all__ = ["solve"] - import ufl import firedrake.linear_solver as ls From 23bc6f3e4967f2869a773b641363bbcf04d31d19 Mon Sep 17 00:00:00 2001 From: nwng04 Date: Tue, 1 Sep 2026 15:22:35 +0100 Subject: [PATCH 11/28] Add function to all --- firedrake/__init__.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/firedrake/__init__.py b/firedrake/__init__.py index b3735ea0bb..719bc913fb 100644 --- a/firedrake/__init__.py +++ b/firedrake/__init__.py @@ -303,7 +303,7 @@ def init_petsc(): ) __all__ += ["MatrixBase", "Matrix", "ImplicitMatrix", "AssembledMatrix"] -__all__ += ["utils"] +__all__ += ["utils", "function"] # Set default log level set_log_level(WARNING) From b57999139c85900f000e0c755d64268ec4b85c28 Mon Sep 17 00:00:00 2001 From: nwng04 Date: Wed, 2 Sep 2026 09:56:57 +0100 Subject: [PATCH 12/28] Add spiked module --- firedrake/__init__.py | 104 ++++++++++++++++++++++-------------------- 1 file changed, 55 insertions(+), 49 deletions(-) diff --git a/firedrake/__init__.py b/firedrake/__init__.py index 719bc913fb..794c42c15f 100644 --- a/firedrake/__init__.py +++ b/firedrake/__init__.py @@ -46,41 +46,38 @@ def init_petsc(): del petsc import ufl as _ufl # Required for ufl.__all__ to be picked up by the compiler -from ufl import * # noqa: F401 +from ufl import * __all__ = list(_ufl.__all__) del _ufl -from finat.ufl import * # noqa: F401 -__all__ += [ - "BrokenElement", "EnrichedElement", "NodalEnrichedElement", - "FiniteElement", "FiniteElementBase", "HCurlElement", - "HDivElement", "WithMapping", "HDiv", "HCurl", "MixedElement", - "TensorElement", "VectorElement", "RestrictedElement", "TensorProductElement", -] +import finat.ufl as _finat_ufl +from finat.ufl import * +__all__ += list(_finat_ufl.__all__) +del _finat_ufl -from pyop2 import op2 # noqa: F401 +from pyop2 import op2 __all__ += ["op2"] -from pyop2.mpi import COMM_WORLD, COMM_SELF # noqa: F401 +from pyop2.mpi import COMM_WORLD, COMM_SELF __all__ += ["COMM_WORLD", "COMM_SELF"] # Register possible citations -import firedrake.citations # noqa: F401 +import firedrake.citations __all__ += ["citations"] petsctools.cite("FiredrakeUserManual") del petsctools -from firedrake.petsc import PETSc # noqa: F401 +from firedrake.petsc import PETSc __all__ += ["PETSc"] -from firedrake.assemble import assemble # noqa: F401 +from firedrake.assemble import assemble __all__ += ["assemble"] -from firedrake.bcs import DirichletBC, homogenize, EquationBC # noqa: F401 +from firedrake.bcs import DirichletBC, homogenize, EquationBC __all__ += ["DirichletBC", "homogenize", "EquationBC"] -from firedrake.checkpointing import ( # noqa: F401 +from firedrake.checkpointing import ( DumbCheckpoint, HDF5File, FILE_READ, FILE_CREATE, FILE_UPDATE, CheckpointFile ) @@ -89,16 +86,16 @@ def init_petsc(): "FILE_UPDATE", "CheckpointFile", ] -from firedrake.cofunction import Cofunction, RieszMap # noqa: F401 +from firedrake.cofunction import Cofunction, RieszMap __all__ += ["Cofunction", "RieszMap"] -from firedrake.constant import Constant # noqa: F401 +from firedrake.constant import Constant __all__ += ["Constant"] -from firedrake.deflation import DeflatedSNES, Deflation # noqa: F401 +from firedrake.deflation import DeflatedSNES, Deflation __all__ += ["DeflatedSNES", "Deflation"] -from firedrake.exceptions import ( # noqa: F401 +from firedrake.exceptions import ( FiredrakeException, ConvergenceError, MismatchingDomainError, VertexOnlyMeshMissingPointsError, DofNotDefinedError, DofTypeError, SerialExecutionOnlyError, PointNotInDomainError, @@ -109,12 +106,12 @@ def init_petsc(): "SerialExecutionOnlyError", "PointNotInDomainError", ] -from firedrake.function import ( # noqa: F401 +from firedrake.function import ( Function, CoordinatelessFunction, PointEvaluator ) __all__ += ["Function", "CoordinatelessFunction", "PointEvaluator"] -from firedrake.functionspace import ( # noqa: F401 +from firedrake.functionspace import ( MixedFunctionSpace, FunctionSpace, VectorFunctionSpace, TensorFunctionSpace, RestrictedFunctionSpace ) @@ -123,15 +120,15 @@ def init_petsc(): "TensorFunctionSpace", "RestrictedFunctionSpace", ] -from firedrake.interpolation import ( # noqa: F401 +from firedrake.interpolation import ( interpolate, Interpolate, get_interpolator ) __all__ += ["interpolate", "Interpolate", "get_interpolator"] -from firedrake.linear_solver import LinearSolver # noqa: F401 +from firedrake.linear_solver import LinearSolver __all__ += ["LinearSolver"] -from firedrake.preconditioners import ( # noqa: F401 +from firedrake.preconditioners import ( PCBase, SNESBase, PCSNESBase, ASMPatchPC, ASMStarPC, ASMVankaPC, ASMLinesmoothPC, ASMExtrudedStarPC, AssembledPC, AuxiliaryOperatorPC, MassInvPC, PCDPC, PatchPC, PlaneSmoother, PatchSNES, P1PC, P1SNES, @@ -148,7 +145,7 @@ def init_petsc(): "CovariancePC", "OffloadPC", "AuxiliaryOperatorSNES", ] -from firedrake.mesh import ( # noqa: F401 +from firedrake.mesh import ( Mesh, ExtrudedMesh, VertexOnlyMesh, RelabeledMesh, SubDomainData, UNMARKED, DistributedMeshOverlapType, DEFAULT_MESH_NAME, MeshGeometry, MeshTopology, @@ -163,7 +160,7 @@ def init_petsc(): "VertexOnlyMeshTopology", "MeshSequenceGeometry", "MeshSequenceTopology", ] -from firedrake.mg import ( # noqa: F401 +from firedrake.mg import ( HierarchyBase, MeshHierarchy, ExtrudedMeshHierarchy, NonNestedHierarchy, SemiCoarsenedExtrudedHierarchy, SubmeshHierarchy, prolong, restrict, inject, TransferManager, @@ -178,31 +175,31 @@ def init_petsc(): "AdaptiveMeshHierarchy", "AdaptiveTransferManager", ] -from firedrake.norms import errornorm, norm # noqa: F401 +from firedrake.norms import errornorm, norm __all__ += ["errornorm", "norm"] -from firedrake.nullspace import VectorSpaceBasis, MixedVectorSpaceBasis # noqa: F401 +from firedrake.nullspace import VectorSpaceBasis, MixedVectorSpaceBasis __all__ += ["VectorSpaceBasis", "MixedVectorSpaceBasis"] -from firedrake.output import VTKFile # noqa: F401 +from firedrake.output import VTKFile __all__ += ["VTKFile"] -from firedrake.parameters import ( # noqa: F401 +from firedrake.parameters import ( Parameters, parameters, disable_performance_optimisations ) __all__ += ["Parameters", "parameters", "disable_performance_optimisations"] -from firedrake.parloops import ( # noqa: F401 +from firedrake.parloops import ( par_loop, direct, READ, WRITE, RW, INC, MIN, MAX ) __all__ += ["par_loop", "direct", "READ", "WRITE", "RW", "INC", "MIN", "MAX"] -from firedrake.projection import ( # noqa: F401 +from firedrake.projection import ( project, Projector ) __all__ += ["project", "Projector"] -from firedrake.slate import ( # noqa: F401 +from firedrake.slate import ( AssembledVector, Block, Factorization, Tensor, Inverse, Transpose, Negative, Add, Mul, Solve, BlockAssembledVector, DiagonalTensor, Reciprocal, HybridizationPC, SchurComplementBuilder, @@ -213,15 +210,15 @@ def init_petsc(): "DiagonalTensor", "Reciprocal", "HybridizationPC", "SchurComplementBuilder", "SCPC", "TensorOp"] -from firedrake.slope_limiter import ( # noqa: F401 +from firedrake.slope_limiter import ( Limiter, VertexBasedLimiter ) __all__ += ["Limiter", "VertexBasedLimiter"] -from firedrake.solving import solve # noqa: F401 +from firedrake.solving import solve __all__ += ["solve"] -from firedrake.ufl_expr import ( # noqa: F401 +from firedrake.ufl_expr import ( Argument, Coargument, TestFunction, TrialFunction, TestFunctions, TrialFunctions, derivative, adjoint, action, CellSize, FacetNormal @@ -230,7 +227,7 @@ def init_petsc(): "TestFunctions", "TrialFunctions", "derivative", "adjoint", "action", "CellSize", "FacetNormal"] -from firedrake.utility_meshes import ( # noqa: F401 +from firedrake.utility_meshes import ( IntervalMesh, UnitIntervalMesh, PeriodicIntervalMesh, PeriodicUnitIntervalMesh, UnitTriangleMesh, RectangleMesh, TensorRectangleMesh, SquareMesh, UnitSquareMesh, PeriodicRectangleMesh, @@ -251,19 +248,19 @@ def init_petsc(): "UnitOctahedralSphereMesh", "CubedSphereMesh", "UnitCubedSphereMesh", "TorusMesh", "AnnulusMesh", "SolidTorusMesh", "CylinderMesh"] -from firedrake.variational_solver import ( # noqa: F401 +from firedrake.variational_solver import ( LinearVariationalProblem, LinearVariationalSolver, NonlinearVariationalProblem, NonlinearVariationalSolver ) __all__ += ["LinearVariationalProblem", "LinearVariationalSolver", "NonlinearVariationalProblem", "NonlinearVariationalSolver"] -from firedrake.eigensolver import ( # noqa: F401 +from firedrake.eigensolver import ( LinearEigenproblem, LinearEigensolver ) __all__ += ["LinearEigenproblem", "LinearEigensolver"] -from firedrake.ensemble import ( # noqa: F401 +from firedrake.ensemble import ( Ensemble, EnsembleFunction, EnsembleCofunction, EnsembleFunctionSpace, EnsembleDualSpace, EnsembleBJacobiPC, EnsembleBlockDiagonalMat @@ -275,21 +272,21 @@ def init_petsc(): ] import firedrake.randomfunctiongen as _randomfunctiongen -from firedrake.randomfunctiongen import * # noqa: F401 +from firedrake.randomfunctiongen import * __all__ += list(_randomfunctiongen.__all__) del _randomfunctiongen -from firedrake.external_operators import ( # noqa: F401 +from firedrake.external_operators import ( AbstractExternalOperator, assemble_method, PointexprOperator, point_expr, MLOperator ) __all__ += ["AbstractExternalOperator", "assemble_method", "PointexprOperator", "point_expr", "MLOperator"] -from firedrake.progress_bar import ProgressBar # noqa: F401 +from firedrake.progress_bar import ProgressBar __all__ += ["ProgressBar"] -from firedrake.logging import ( # noqa: F401 +from firedrake.logging import ( set_level, set_log_handlers, set_log_level, DEBUG, INFO, WARNING, ERROR, CRITICAL, log, debug, info, warning, error, critical, info_red, info_green, info_blue, RED, GREEN, BLUE @@ -298,27 +295,36 @@ def init_petsc(): "WARNING", "ERROR", "CRITICAL", "log", "debug", "info", "warning", "error", "critical", "info_red", "info_green", "info_blue", "RED", "GREEN", "BLUE"] -from firedrake.matrix import ( # noqa: F401 +from firedrake.matrix import ( MatrixBase, Matrix, ImplicitMatrix, AssembledMatrix ) __all__ += ["MatrixBase", "Matrix", "ImplicitMatrix", "AssembledMatrix"] -__all__ += ["utils", "function"] - # Set default log level set_log_level(WARNING) set_log_handlers(comm=COMM_WORLD) # Moved functionality -from firedrake._deprecation import plot as _plot # noqa: F401 +from firedrake._deprecation import plot as _plot import sys sys.modules["firedrake.plot"] = _plot -from firedrake.plot import * # noqa: F401 +from firedrake.plot import * __all__ += list(_plot.__all__) del sys del _plot +class SpikedModule: + def __init__(self, module): + self.module = module + + def __getattr__(self, key): + raise AttributeError(f"'{self.module}.{key}' is not available via `from firedrake import *`." + f" Please import it directly (e.g. 'import firedrake.{self.module}).") + +utils = SpikedModule("utils") +__all__ += ["utils"] + def set_blas_num_threads(): """Try to detect threading and either disable or warn user. From d0ebdbbf5955af935a39a852d5ba23cad5abfbb5 Mon Sep 17 00:00:00 2001 From: Na Wang <78233396+nwng04@users.noreply.github.com> Date: Wed, 2 Sep 2026 16:47:09 +0100 Subject: [PATCH 13/28] Apply suggestion from @connorjward Co-authored-by: Connor Ward --- firedrake/__init__.py | 2 ++ 1 file changed, 2 insertions(+) diff --git a/firedrake/__init__.py b/firedrake/__init__.py index 794c42c15f..d9b563f393 100644 --- a/firedrake/__init__.py +++ b/firedrake/__init__.py @@ -271,6 +271,8 @@ def init_petsc(): "EnsembleBJacobiPC", "EnsembleBlockDiagonalMat", ] +# randomfunctiongen generates __all__ dynamically, so we cannot enumerate +# things here import firedrake.randomfunctiongen as _randomfunctiongen from firedrake.randomfunctiongen import * __all__ += list(_randomfunctiongen.__all__) From e427efb28d427af4d9cca1445e57d1afb4ca4ffe Mon Sep 17 00:00:00 2001 From: nwng04 Date: Wed, 2 Sep 2026 18:05:22 +0100 Subject: [PATCH 14/28] Add utils as an import to tests and remove whitespacing --- firedrake/__init__.py | 90 +++++++++---------- firedrake/_deprecation.py | 11 +++ .../firedrake/regression/test_auxiliary_dm.py | 3 +- .../regression/test_bessel_functions.py | 3 +- .../test_coefficient_derivatives.py | 3 +- .../firedrake/regression/test_conditional.py | 3 +- .../regression/test_coordinatederivative.py | 11 +-- .../firedrake/regression/test_expressions.py | 3 +- ...est_fieldsplit_fieldsplit_aux_multigrid.py | 3 +- .../regression/test_solving_interface.py | 3 +- tests/firedrake/regression/test_split.py | 5 +- 11 files changed, 75 insertions(+), 63 deletions(-) diff --git a/firedrake/__init__.py b/firedrake/__init__.py index d9b563f393..a026e76657 100644 --- a/firedrake/__init__.py +++ b/firedrake/__init__.py @@ -46,38 +46,38 @@ def init_petsc(): del petsc import ufl as _ufl # Required for ufl.__all__ to be picked up by the compiler -from ufl import * +from ufl import * __all__ = list(_ufl.__all__) del _ufl import finat.ufl as _finat_ufl -from finat.ufl import * +from finat.ufl import * __all__ += list(_finat_ufl.__all__) del _finat_ufl -from pyop2 import op2 +from pyop2 import op2 __all__ += ["op2"] -from pyop2.mpi import COMM_WORLD, COMM_SELF +from pyop2.mpi import COMM_WORLD, COMM_SELF __all__ += ["COMM_WORLD", "COMM_SELF"] # Register possible citations -import firedrake.citations +import firedrake.citations # noqa: F401 __all__ += ["citations"] petsctools.cite("FiredrakeUserManual") del petsctools -from firedrake.petsc import PETSc +from firedrake.petsc import PETSc __all__ += ["PETSc"] -from firedrake.assemble import assemble +from firedrake.assemble import assemble __all__ += ["assemble"] -from firedrake.bcs import DirichletBC, homogenize, EquationBC +from firedrake.bcs import DirichletBC, homogenize, EquationBC __all__ += ["DirichletBC", "homogenize", "EquationBC"] -from firedrake.checkpointing import ( +from firedrake.checkpointing import ( DumbCheckpoint, HDF5File, FILE_READ, FILE_CREATE, FILE_UPDATE, CheckpointFile ) @@ -86,16 +86,16 @@ def init_petsc(): "FILE_UPDATE", "CheckpointFile", ] -from firedrake.cofunction import Cofunction, RieszMap +from firedrake.cofunction import Cofunction, RieszMap __all__ += ["Cofunction", "RieszMap"] -from firedrake.constant import Constant +from firedrake.constant import Constant __all__ += ["Constant"] -from firedrake.deflation import DeflatedSNES, Deflation +from firedrake.deflation import DeflatedSNES, Deflation __all__ += ["DeflatedSNES", "Deflation"] -from firedrake.exceptions import ( +from firedrake.exceptions import ( FiredrakeException, ConvergenceError, MismatchingDomainError, VertexOnlyMeshMissingPointsError, DofNotDefinedError, DofTypeError, SerialExecutionOnlyError, PointNotInDomainError, @@ -106,12 +106,12 @@ def init_petsc(): "SerialExecutionOnlyError", "PointNotInDomainError", ] -from firedrake.function import ( +from firedrake.function import ( Function, CoordinatelessFunction, PointEvaluator ) __all__ += ["Function", "CoordinatelessFunction", "PointEvaluator"] -from firedrake.functionspace import ( +from firedrake.functionspace import ( MixedFunctionSpace, FunctionSpace, VectorFunctionSpace, TensorFunctionSpace, RestrictedFunctionSpace ) @@ -120,15 +120,15 @@ def init_petsc(): "TensorFunctionSpace", "RestrictedFunctionSpace", ] -from firedrake.interpolation import ( +from firedrake.interpolation import ( interpolate, Interpolate, get_interpolator ) __all__ += ["interpolate", "Interpolate", "get_interpolator"] -from firedrake.linear_solver import LinearSolver +from firedrake.linear_solver import LinearSolver __all__ += ["LinearSolver"] -from firedrake.preconditioners import ( +from firedrake.preconditioners import ( PCBase, SNESBase, PCSNESBase, ASMPatchPC, ASMStarPC, ASMVankaPC, ASMLinesmoothPC, ASMExtrudedStarPC, AssembledPC, AuxiliaryOperatorPC, MassInvPC, PCDPC, PatchPC, PlaneSmoother, PatchSNES, P1PC, P1SNES, @@ -145,7 +145,7 @@ def init_petsc(): "CovariancePC", "OffloadPC", "AuxiliaryOperatorSNES", ] -from firedrake.mesh import ( +from firedrake.mesh import ( Mesh, ExtrudedMesh, VertexOnlyMesh, RelabeledMesh, SubDomainData, UNMARKED, DistributedMeshOverlapType, DEFAULT_MESH_NAME, MeshGeometry, MeshTopology, @@ -160,7 +160,7 @@ def init_petsc(): "VertexOnlyMeshTopology", "MeshSequenceGeometry", "MeshSequenceTopology", ] -from firedrake.mg import ( +from firedrake.mg import ( HierarchyBase, MeshHierarchy, ExtrudedMeshHierarchy, NonNestedHierarchy, SemiCoarsenedExtrudedHierarchy, SubmeshHierarchy, prolong, restrict, inject, TransferManager, @@ -175,10 +175,10 @@ def init_petsc(): "AdaptiveMeshHierarchy", "AdaptiveTransferManager", ] -from firedrake.norms import errornorm, norm +from firedrake.norms import errornorm, norm __all__ += ["errornorm", "norm"] -from firedrake.nullspace import VectorSpaceBasis, MixedVectorSpaceBasis +from firedrake.nullspace import VectorSpaceBasis, MixedVectorSpaceBasis __all__ += ["VectorSpaceBasis", "MixedVectorSpaceBasis"] from firedrake.output import VTKFile @@ -189,17 +189,17 @@ def init_petsc(): ) __all__ += ["Parameters", "parameters", "disable_performance_optimisations"] -from firedrake.parloops import ( +from firedrake.parloops import ( par_loop, direct, READ, WRITE, RW, INC, MIN, MAX ) __all__ += ["par_loop", "direct", "READ", "WRITE", "RW", "INC", "MIN", "MAX"] -from firedrake.projection import ( +from firedrake.projection import ( project, Projector ) __all__ += ["project", "Projector"] -from firedrake.slate import ( +from firedrake.slate import ( AssembledVector, Block, Factorization, Tensor, Inverse, Transpose, Negative, Add, Mul, Solve, BlockAssembledVector, DiagonalTensor, Reciprocal, HybridizationPC, SchurComplementBuilder, @@ -210,15 +210,15 @@ def init_petsc(): "DiagonalTensor", "Reciprocal", "HybridizationPC", "SchurComplementBuilder", "SCPC", "TensorOp"] -from firedrake.slope_limiter import ( +from firedrake.slope_limiter import ( Limiter, VertexBasedLimiter ) __all__ += ["Limiter", "VertexBasedLimiter"] -from firedrake.solving import solve +from firedrake.solving import solve __all__ += ["solve"] -from firedrake.ufl_expr import ( +from firedrake.ufl_expr import ( Argument, Coargument, TestFunction, TrialFunction, TestFunctions, TrialFunctions, derivative, adjoint, action, CellSize, FacetNormal @@ -227,7 +227,7 @@ def init_petsc(): "TestFunctions", "TrialFunctions", "derivative", "adjoint", "action", "CellSize", "FacetNormal"] -from firedrake.utility_meshes import ( +from firedrake.utility_meshes import ( IntervalMesh, UnitIntervalMesh, PeriodicIntervalMesh, PeriodicUnitIntervalMesh, UnitTriangleMesh, RectangleMesh, TensorRectangleMesh, SquareMesh, UnitSquareMesh, PeriodicRectangleMesh, @@ -248,19 +248,19 @@ def init_petsc(): "UnitOctahedralSphereMesh", "CubedSphereMesh", "UnitCubedSphereMesh", "TorusMesh", "AnnulusMesh", "SolidTorusMesh", "CylinderMesh"] -from firedrake.variational_solver import ( +from firedrake.variational_solver import ( LinearVariationalProblem, LinearVariationalSolver, NonlinearVariationalProblem, NonlinearVariationalSolver ) __all__ += ["LinearVariationalProblem", "LinearVariationalSolver", "NonlinearVariationalProblem", "NonlinearVariationalSolver"] -from firedrake.eigensolver import ( +from firedrake.eigensolver import ( LinearEigenproblem, LinearEigensolver ) __all__ += ["LinearEigenproblem", "LinearEigensolver"] -from firedrake.ensemble import ( +from firedrake.ensemble import ( Ensemble, EnsembleFunction, EnsembleCofunction, EnsembleFunctionSpace, EnsembleDualSpace, EnsembleBJacobiPC, EnsembleBlockDiagonalMat @@ -274,21 +274,21 @@ def init_petsc(): # randomfunctiongen generates __all__ dynamically, so we cannot enumerate # things here import firedrake.randomfunctiongen as _randomfunctiongen -from firedrake.randomfunctiongen import * +from firedrake.randomfunctiongen import * __all__ += list(_randomfunctiongen.__all__) del _randomfunctiongen -from firedrake.external_operators import ( +from firedrake.external_operators import ( AbstractExternalOperator, assemble_method, PointexprOperator, point_expr, MLOperator ) __all__ += ["AbstractExternalOperator", "assemble_method", "PointexprOperator", "point_expr", "MLOperator"] -from firedrake.progress_bar import ProgressBar +from firedrake.progress_bar import ProgressBar __all__ += ["ProgressBar"] -from firedrake.logging import ( +from firedrake.logging import ( set_level, set_log_handlers, set_log_level, DEBUG, INFO, WARNING, ERROR, CRITICAL, log, debug, info, warning, error, critical, info_red, info_green, info_blue, RED, GREEN, BLUE @@ -297,7 +297,7 @@ def init_petsc(): "WARNING", "ERROR", "CRITICAL", "log", "debug", "info", "warning", "error", "critical", "info_red", "info_green", "info_blue", "RED", "GREEN", "BLUE"] -from firedrake.matrix import ( +from firedrake.matrix import ( MatrixBase, Matrix, ImplicitMatrix, AssembledMatrix ) __all__ += ["MatrixBase", "Matrix", "ImplicitMatrix", "AssembledMatrix"] @@ -307,26 +307,18 @@ def init_petsc(): set_log_handlers(comm=COMM_WORLD) # Moved functionality -from firedrake._deprecation import plot as _plot +from firedrake._deprecation import plot as _plot import sys sys.modules["firedrake.plot"] = _plot -from firedrake.plot import * +from firedrake.plot import * __all__ += list(_plot.__all__) del sys del _plot - -class SpikedModule: - def __init__(self, module): - self.module = module - - def __getattr__(self, key): - raise AttributeError(f"'{self.module}.{key}' is not available via `from firedrake import *`." - f" Please import it directly (e.g. 'import firedrake.{self.module}).") - -utils = SpikedModule("utils") +from firedrake._deprecation import utils __all__ += ["utils"] + def set_blas_num_threads(): """Try to detect threading and either disable or warn user. diff --git a/firedrake/_deprecation.py b/firedrake/_deprecation.py index f5cad3d0fd..4348bc6e6a 100644 --- a/firedrake/_deprecation.py +++ b/firedrake/_deprecation.py @@ -45,6 +45,15 @@ def __call__(*args, **kwargs): return __call__ +class SpikedModule: + def __init__(self, module): + self.module = module + + def __getattr__(self, key): + raise AttributeError(f"'{self.module}.{key}' is not available via `from firedrake import *`." + f" Please import it directly (e.g. 'import firedrake.{self.module}).") + + # Deprecate plotting in the global namespace plot = _fake_module( "firedrake.pyplot", @@ -53,3 +62,5 @@ def __call__(*args, **kwargs): "tripcolor", "quiver", "streamplot", "FunctionPlotter", "pgfplot" ] ) + +utils = SpikedModule("utils") diff --git a/tests/firedrake/regression/test_auxiliary_dm.py b/tests/firedrake/regression/test_auxiliary_dm.py index a4fbb094cb..2ea5c6f0f7 100644 --- a/tests/firedrake/regression/test_auxiliary_dm.py +++ b/tests/firedrake/regression/test_auxiliary_dm.py @@ -1,5 +1,6 @@ from firedrake import * from firedrake.petsc import DEFAULT_DIRECT_SOLVER_PARAMETERS +from firedrake.utils import complex_mode import pytest distribution_parameters = {"partition": True, "overlap_type": (DistributedMeshOverlapType.VERTEX, 2)} @@ -45,7 +46,7 @@ def src(self, mesh): return f -@pytest.mark.skipif(utils.complex_mode, reason="Differentiation of energy not defined in Complex.") +@pytest.mark.skipif(complex_mode, reason="Differentiation of energy not defined in Complex.") def test_auxiliary_dm(): problem = BiharmonicProblem(5, 1) mesh = problem.mesh() diff --git a/tests/firedrake/regression/test_bessel_functions.py b/tests/firedrake/regression/test_bessel_functions.py index 52b0eb7cde..da4c3b1e6c 100644 --- a/tests/firedrake/regression/test_bessel_functions.py +++ b/tests/firedrake/regression/test_bessel_functions.py @@ -1,10 +1,11 @@ from firedrake import * from scipy.special import jn +from firedrake.utils import complex_mode import numpy as np import pytest -@pytest.mark.skipif(utils.complex_mode, reason="Complex bessel functions are not implemented.") +@pytest.mark.skipif(complex_mode, reason="Complex bessel functions are not implemented.") def test_bessel_functions(): mesh = UnitDiskMesh(3) diff --git a/tests/firedrake/regression/test_coefficient_derivatives.py b/tests/firedrake/regression/test_coefficient_derivatives.py index 449a99e02f..cc49e776f2 100644 --- a/tests/firedrake/regression/test_coefficient_derivatives.py +++ b/tests/firedrake/regression/test_coefficient_derivatives.py @@ -1,9 +1,10 @@ from firedrake import * +from firedrake.utils import complex_mode import numpy as np import pytest -@pytest.mark.skipif(utils.complex_mode, reason="Not complex differentiable") +@pytest.mark.skipif(complex_mode, reason="Not complex differentiable") def test_coefficient_derivatives(): m = UnitSquareMesh(3, 3) x = SpatialCoordinate(m) diff --git a/tests/firedrake/regression/test_conditional.py b/tests/firedrake/regression/test_conditional.py index 7af345a913..bbfee74fa2 100644 --- a/tests/firedrake/regression/test_conditional.py +++ b/tests/firedrake/regression/test_conditional.py @@ -2,6 +2,7 @@ import numpy as np import ufl from firedrake import * +from firedrake.utils import complex_mode from ufl.algorithms.comparison_checker import ComplexComparisonError @@ -32,7 +33,7 @@ def test_conditional(ncell): A = assemble(derivative(Fc, u, du)).M.values -@pytest.mark.skipif(utils.complex_mode, reason="Differentiation of conditional unlikely to work in complex.") +@pytest.mark.skipif(complex_mode, reason="Differentiation of conditional unlikely to work in complex.") def test_conditional_nan(): # Test case courtesy of Marco Morandini: # https://github.com/firedrakeproject/tsfc/issues/183 diff --git a/tests/firedrake/regression/test_coordinatederivative.py b/tests/firedrake/regression/test_coordinatederivative.py index 8444f421ee..3de8917bb5 100644 --- a/tests/firedrake/regression/test_coordinatederivative.py +++ b/tests/firedrake/regression/test_coordinatederivative.py @@ -1,9 +1,10 @@ import pytest import numpy as np from firedrake import * +from firedrake.utils import complex_mode -@pytest.mark.skipif(utils.complex_mode, reason="Don't expect coordinate derivatives to work in complex") +@pytest.mark.skipif(complex_mode, reason="Don't expect coordinate derivatives to work in complex") def test_first_shape_derivative(): mesh = UnitSquareMesh(6, 6) n = FacetNormal(mesh) @@ -47,7 +48,7 @@ def test_first(J, dJ): test_first(J, dJ) -@pytest.mark.skipif(utils.complex_mode, reason="Don't expect coordinate derivatives to work in complex") +@pytest.mark.skipif(complex_mode, reason="Don't expect coordinate derivatives to work in complex") def test_mixed_derivatives(): mesh = UnitSquareMesh(6, 6) X = SpatialCoordinate(mesh) @@ -80,7 +81,7 @@ def test_mixed(J, dJ_manual): test_mixed(J, dJ) -@pytest.mark.skipif(utils.complex_mode, reason="Don't expect coordinate derivatives to work in complex") +@pytest.mark.skipif(complex_mode, reason="Don't expect coordinate derivatives to work in complex") def test_integral_scaling_edge_case(): mesh = UnitSquareMesh(6, 6) X = SpatialCoordinate(mesh) @@ -96,7 +97,7 @@ def test_integral_scaling_edge_case(): assemble(Constant(2.0) * derivative(derivative(J, X), X)) -@pytest.mark.skipif(utils.complex_mode, reason="Don't expect coordinate derivatives to work in complex") +@pytest.mark.skipif(complex_mode, reason="Don't expect coordinate derivatives to work in complex") def test_second_shape_derivative(): mesh = UnitSquareMesh(6, 6) V = FunctionSpace(mesh, "CG", 1) @@ -129,7 +130,7 @@ def test_second(J, ddJ): test_second(Ja+Jb, ddJa + ddJb) -@pytest.mark.skipif(utils.complex_mode, reason="Don't expect coordinate derivatives to work in complex") +@pytest.mark.skipif(complex_mode, reason="Don't expect coordinate derivatives to work in complex") def test_coordinate_handling(): mesh = UnitSquareMesh(60, 60) V = VectorFunctionSpace(mesh, "CG", 1) diff --git a/tests/firedrake/regression/test_expressions.py b/tests/firedrake/regression/test_expressions.py index ad5af1a086..5117599628 100644 --- a/tests/firedrake/regression/test_expressions.py +++ b/tests/firedrake/regression/test_expressions.py @@ -8,6 +8,7 @@ import ufl # noqa: F401 from firedrake import * +from firedrake.utils import complex_mode @pytest.fixture(scope='module') @@ -404,7 +405,7 @@ def test_assign_from_mfs_sub(cg1, vcg1): v.assign(w1) -@pytest.mark.skipif(not utils.complex_mode, reason="Test specific to complex mode") +@pytest.mark.skipif(not complex_mode, reason="Test specific to complex mode") def test_assign_complex_value(cg1): f = Function(cg1) g = Function(cg1) diff --git a/tests/firedrake/regression/test_fieldsplit_fieldsplit_aux_multigrid.py b/tests/firedrake/regression/test_fieldsplit_fieldsplit_aux_multigrid.py index ca28a78dbe..22e9a04bf0 100644 --- a/tests/firedrake/regression/test_fieldsplit_fieldsplit_aux_multigrid.py +++ b/tests/firedrake/regression/test_fieldsplit_fieldsplit_aux_multigrid.py @@ -11,6 +11,7 @@ import pytest from firedrake import * from firedrake.petsc import DEFAULT_DIRECT_SOLVER +from firedrake.utils import complex_mode def BoundaryConditions(mesh): @@ -39,7 +40,7 @@ def alpha(d): return (K, bcs) -@pytest.mark.skipif(utils.complex_mode, reason="inner(grad(u), grad(u)) not complex Gateaux differentiable.") +@pytest.mark.skipif(complex_mode, reason="inner(grad(u), grad(u)) not complex Gateaux differentiable.") def test_fieldsplit_fieldsplit_aux_multigrid(): # Setup mesh = UnitSquareMesh(10, 10) diff --git a/tests/firedrake/regression/test_solving_interface.py b/tests/firedrake/regression/test_solving_interface.py index d05105d9a4..85ebdceb00 100644 --- a/tests/firedrake/regression/test_solving_interface.py +++ b/tests/firedrake/regression/test_solving_interface.py @@ -2,6 +2,7 @@ import numpy as np from firedrake import * from firedrake.petsc import PETSc +from firedrake.utils import complex_mode from numpy.linalg import norm as np_norm import gc @@ -317,7 +318,7 @@ def test_solve_sub_mat_type(mesh, sub_mat_type): P.getNestSubMatrix(i, j).getType() == sub_mat_type -@pytest.mark.skipif(utils.complex_mode, reason="Differentiation of energy not defined in Complex.") +@pytest.mark.skipif(complex_mode, reason="Differentiation of energy not defined in Complex.") @pytest.mark.parametrize("mixed", (False, True), ids=("primal", "mixed")) def test_solve_pre_apply_bcs(mesh, mixed): """Solve a 1D hyperelasticity problem with linear exact solution. diff --git a/tests/firedrake/regression/test_split.py b/tests/firedrake/regression/test_split.py index fcf8f221f8..4f38fc4e63 100644 --- a/tests/firedrake/regression/test_split.py +++ b/tests/firedrake/regression/test_split.py @@ -1,5 +1,6 @@ import pytest from firedrake import * +from firedrake.utils import complex_mode from firedrake.formmanipulation import ExtractSubBlock import numpy as np @@ -36,7 +37,7 @@ def test_function_split_raises(): derivative(phi, f) -@pytest.mark.skipif(utils.complex_mode, reason="u**2 not complex Gateaux differentiable.") +@pytest.mark.skipif(complex_mode, reason="u**2 not complex Gateaux differentiable.") def test_split_function_derivative(): mesh = UnitSquareMesh(1, 1) V = FunctionSpace(mesh, "DG", 0) @@ -62,7 +63,7 @@ def test_split_function_derivative(): assert np.allclose(actual.M.values, expect.M.values) -@pytest.mark.skipif(utils.complex_mode, reason="inner(grad(u), grad(u)) not complex Gateaux differentiable.") +@pytest.mark.skipif(complex_mode, reason="inner(grad(u), grad(u)) not complex Gateaux differentiable.") def test_assemble_split_mixed_derivative(): """Assemble the derivative of a form wrt part of mixed function.""" mesh = UnitSquareMesh(1, 1) From cbae9188656f3a041ea9e2a702a2ced07e2253dc Mon Sep 17 00:00:00 2001 From: nwng04 Date: Wed, 2 Sep 2026 18:29:50 +0100 Subject: [PATCH 15/28] Remove some duplicate modules from export lists --- firedrake/cofunction.py | 2 +- firedrake/function.py | 2 +- firedrake/functionspace.py | 4 ---- firedrake/mesh.py | 6 ++---- firedrake/mg/embedded.py | 2 -- firedrake/nullspace.py | 3 --- firedrake/preconditioners/patch.py | 3 --- firedrake/preconditioners/pmg.py | 3 ++- 8 files changed, 6 insertions(+), 19 deletions(-) diff --git a/firedrake/cofunction.py b/firedrake/cofunction.py index 8075cc8f5a..55e4fe99cf 100644 --- a/firedrake/cofunction.py +++ b/firedrake/cofunction.py @@ -16,7 +16,7 @@ from firedrake.petsc import PETSc -__all__ = ["Cofunction", "RieszMap"] +__all__ = ["RieszMap"] class Cofunction(ufl.Cofunction, CofunctionMixin): diff --git a/firedrake/function.py b/firedrake/function.py index 1c7eafcfff..6d2d48d496 100644 --- a/firedrake/function.py +++ b/firedrake/function.py @@ -30,7 +30,7 @@ from firedrake.exceptions import PointNotInDomainError -__all__ = ['CoordinatelessFunction', 'PointEvaluator'] +__all__ = ['PointEvaluator'] class _CFunction(ctypes.Structure): diff --git a/firedrake/functionspace.py b/firedrake/functionspace.py index 66de2f289f..a9cac4e44e 100644 --- a/firedrake/functionspace.py +++ b/firedrake/functionspace.py @@ -16,10 +16,6 @@ import numbers -__all__ = ("MixedFunctionSpace", "FunctionSpace", - "VectorFunctionSpace", "TensorFunctionSpace", "RestrictedFunctionSpace") - - @PETSc.Log.EventDecorator() def make_scalar_element(mesh, family, degree, vfamily, vdegree, variant, quad_scheme): """Build a scalar :class:`finat.ufl.finiteelement.FiniteElement`. diff --git a/firedrake/mesh.py b/firedrake/mesh.py index 2a63a41c50..3c6646c6e3 100644 --- a/firedrake/mesh.py +++ b/firedrake/mesh.py @@ -61,10 +61,8 @@ __all__ = [ - 'ExtrudedMesh', 'RelabeledMesh', - 'SubDomainData', 'UNMARKED', 'DistributedMeshOverlapType', - 'DEFAULT_MESH_NAME', 'MeshGeometry', 'MeshTopology', - 'AbstractMeshTopology', 'ExtrudedMeshTopology', 'VertexOnlyMeshTopology', + 'RelabeledMesh', 'SubDomainData', 'UNMARKED', + 'DistributedMeshOverlapType', 'DEFAULT_MESH_NAME', 'VertexOnlyMeshTopology', 'MeshSequenceGeometry', 'MeshSequenceTopology', 'Submesh' ] diff --git a/firedrake/mg/embedded.py b/firedrake/mg/embedded.py index 9a00c277b1..9cd3a4a606 100644 --- a/firedrake/mg/embedded.py +++ b/firedrake/mg/embedded.py @@ -9,8 +9,6 @@ from finat.element_factory import create_element from .utils import get_level -__all__ = ("TransferManager",) - class Op(IntEnum): PROLONG = 0 diff --git a/firedrake/nullspace.py b/firedrake/nullspace.py index 0dccac69c3..d31b5de454 100644 --- a/firedrake/nullspace.py +++ b/firedrake/nullspace.py @@ -11,9 +11,6 @@ from firedrake.petsc import PETSc -__all__ = ['VectorSpaceBasis', 'MixedVectorSpaceBasis'] - - class VectorSpaceBasis(object): r"""Build a basis for a vector space. diff --git a/firedrake/preconditioners/patch.py b/firedrake/preconditioners/patch.py index 4e08fe9a53..5f5c93118d 100644 --- a/firedrake/preconditioners/patch.py +++ b/firedrake/preconditioners/patch.py @@ -37,9 +37,6 @@ from firedrake import Function -__all__ = ("PatchPC", "PlaneSmoother", "PatchSNES") - - class PatchCallable: """Class representing the evaluation of a patch operator or residual. diff --git a/firedrake/preconditioners/pmg.py b/firedrake/preconditioners/pmg.py index 5fee3d9429..3320bffc01 100644 --- a/firedrake/preconditioners/pmg.py +++ b/firedrake/preconditioners/pmg.py @@ -24,7 +24,8 @@ import tempfile import weakref -__all__ = ("PMGPC", "PMGSNES") + +__all__ = ("PMGSNES") class PMGBase(PCSNESBase): From 593a1a826923253a9ff4d75672a86346818db7c3 Mon Sep 17 00:00:00 2001 From: nwng04 Date: Wed, 2 Sep 2026 19:46:26 +0100 Subject: [PATCH 16/28] First attempt at fixing sphinx failurs, specifying module locations --- demos/deflation/deflation.py.rst | 2 +- docs/source/boundary_conditions.rst | 10 ++++---- docs/source/interpolation.rst | 4 +-- docs/source/matrix-free.rst | 2 +- docs/source/quadrature.rst | 4 +-- docs/source/solving-interface.rst | 12 ++++----- docs/source/variational-problems.rst | 2 +- firedrake/_deprecation.py | 25 +++++++++++++------ firedrake/mesh.py | 2 +- firedrake/preconditioners/asm.py | 2 +- firedrake/preconditioners/assembled.py | 2 -- firedrake/preconditioners/auxiliary_snes.py | 2 -- firedrake/preconditioners/base.py | 2 +- firedrake/preconditioners/fdm.py | 2 +- firedrake/preconditioners/gtmg.py | 3 --- firedrake/preconditioners/hypre_ams.py | 2 -- firedrake/preconditioners/low_order.py | 2 +- firedrake/preconditioners/massinv.py | 2 -- firedrake/preconditioners/pcd.py | 2 -- firedrake/preconditioners/pmg.py | 3 --- .../static_condensation/hybridization.py | 2 +- firedrake/slate/static_condensation/scpc.py | 3 --- firedrake/utility_meshes.py | 3 --- firedrake/variational_solver.py | 5 +--- 24 files changed, 43 insertions(+), 57 deletions(-) diff --git a/demos/deflation/deflation.py.rst b/demos/deflation/deflation.py.rst index 2529094dab..61debb9247 100644 --- a/demos/deflation/deflation.py.rst +++ b/demos/deflation/deflation.py.rst @@ -44,7 +44,7 @@ We implement the usual weak formulation of the equation in Firedrake as standard bcs = DirichletBC(V, 0, "on_boundary") problem = NonlinearVariationalProblem(F, u, bcs) -Applying deflation requires two ingredients: the :class:`~.DeflatedSNES` nonlinear solver, and a :class:`~.Deflation` object. The :class:`~.Deflation` object records the solutions to be deflated, and specifies the sense of distance to use in deflation. In this example we use the metric induced by the :math:`L^2(\Omega)` inner product: :: +Applying deflation requires two ingredients: the :class:`~.deflation.DeflatedSNES` nonlinear solver, and a :class:`~.deflation.Deflation` object. The :class:`~.deflation.Deflation` object records the solutions to be deflated, and specifies the sense of distance to use in deflation. In this example we use the metric induced by the :math:`L^2(\Omega)` inner product: :: sp = {"snes_type": "python", "snes_python_type": "firedrake.DeflatedSNES", diff --git a/docs/source/boundary_conditions.rst b/docs/source/boundary_conditions.rst index da8d9eefdc..ca6e643b66 100644 --- a/docs/source/boundary_conditions.rst +++ b/docs/source/boundary_conditions.rst @@ -288,13 +288,13 @@ solved with boundary conditions as follows: :class:`~.Matrix` object that records the fact that it is intended to be assembled from ``a``. -2. At the :func:`~.solve` call, Firedrake determines +2. At the :func:`~firedrake.solving.solve` call, Firedrake determines which boundary conditions to apply in the following priority order: first, boundary conditions supplied to the - :func:`~.solve` call. If no boundary conditions - are supplied to the :func:`~.solve` call, then any + :func:`~firedrake.solving.solve` call. If no boundary conditions + are supplied to the :func:`~firedrake.solving.solve` call, then any boundary conditions applied when - :func:`~.assemble` was called on A are used, as + :func:`~firedrake.assemble.assemble` was called on A are used, as are any boundary conditions subsequently added with :meth:`~.DirichletBC.apply`. @@ -308,5 +308,5 @@ solved with boundary conditions as follows: 4. The matrix assembled is then stored in the :class:`~.Matrix` so that reassembly is avoided if the - matrix is used in another :func:`~.solve` call with + matrix is used in another :func:`~firedrake.solving.solve` call with the same boundary conditions. diff --git a/docs/source/interpolation.rst b/docs/source/interpolation.rst index 50441902ff..66eeb59d83 100644 --- a/docs/source/interpolation.rst +++ b/docs/source/interpolation.rst @@ -47,7 +47,7 @@ The basic syntax for interpolation is: :end-before: [test_interpolate_operator 2] Here, the :py:func:`~.interpolate` function returned a **symbolic** UFL_ :py:class:`~ufl.Interpolate` -expression. To calculate a concrete numerical result, we need to call :py:func:`~.assemble` on this expression. +expression. To calculate a concrete numerical result, we need to call :py:func:`~firedrake.assemble.assemble` on this expression. It is also possible to interpolate an expression directly into an existing :py:class:`~.Function`: @@ -289,7 +289,7 @@ of the source mesh. Volume, surface and line integrals can therefore be calculated by interpolating onto the mesh or :ref:`immersed manifold ` which defines the volume, surface or line of interest in the domain. The integral itself is calculated -by calling :py:func:`~.assemble` on an appropriate form over the target mesh +by calling :py:func:`~firedrake.assemble.assemble` on an appropriate form over the target mesh function space: .. literalinclude:: ../../tests/firedrake/regression/test_interpolation_manual.py diff --git a/docs/source/matrix-free.rst b/docs/source/matrix-free.rst index f97062872b..3e19bdb325 100644 --- a/docs/source/matrix-free.rst +++ b/docs/source/matrix-free.rst @@ -74,7 +74,7 @@ in :class:`.ImplicitMatrixContext`. For example, it is not possible to extract physical parameters such as the Reynolds number from a UFL bilinear form. In this case, the solver accepts a dictionary ``"appctx"`` as an optional keyword argument, the same argument may -also be passed to :func:`~.assemble` in the case of preassembled +also be passed to :func:`~firedrake.assemble.assemble` in the case of preassembled solves. Firedrake passes that down into the :class:`.ImplicitMatrixContext` so that it is accessible to preconditioners. diff --git a/docs/source/quadrature.rst b/docs/source/quadrature.rst index c65dcddf2a..fcf1e7ddf4 100644 --- a/docs/source/quadrature.rst +++ b/docs/source/quadrature.rst @@ -50,8 +50,8 @@ provided as a convenient shorthand. For integrals that do not specify a fixed or maximum quadrature degree, a default value may be keyed as the ``"quadrature_degree"`` or ``"max_quadrature_degree"`` entry -respectively in the ``form_compiler_parameters`` dictionary passed on to :py:func:`~.solve`, -:py:func:`~.project`, :py:class:`~.NonlinearVariationalProblem`, or :py:func:`~.assemble`. +respectively in the ``form_compiler_parameters`` dictionary passed on to :py:func:`~firedrake.solving.solve`, +:py:func:`~.project`, :py:class:`~.NonlinearVariationalProblem`, or :py:func:`~firedrake.assemble.assemble`. .. code-block:: python3 diff --git a/docs/source/solving-interface.rst b/docs/source/solving-interface.rst index 1d2580ff7f..77b1160f70 100644 --- a/docs/source/solving-interface.rst +++ b/docs/source/solving-interface.rst @@ -155,7 +155,7 @@ which to place our solution: x = Function(V) -We then :py:func:`~.assemble` the left hand side +We then :py:func:`~firedrake.assemble.assemble` the left hand side matrix ``A`` and known right hand side ``b`` from the bilinear and linear forms respectively: @@ -172,7 +172,7 @@ Finally, we can solve the problem placing the solution in ``x``: to apply boundary conditions to the problem, we can assemble the linear operator ``A`` with boundary conditions using the ``bcs`` -keyword argument to :py:func:`~.assemble` (and then +keyword argument to :py:func:`~firedrake.assemble.assemble` (and then not supply them in solve call): .. code-block:: python3 @@ -185,7 +185,7 @@ not supply them in solve call): It is no longer possible to apply or change boundary conditions after assembling the matrix ``A``; pass any - necessary boundary conditions to :py:func:`~.assemble`. + necessary boundary conditions to :py:func:`~firedrake.assemble.assemble`. Specifying solution methods --------------------------- @@ -506,7 +506,7 @@ is assembled as a nested matrix, there is a choice as to the type of the blocks (they may be "aij" or "baij"). The default choice can be controlled with ``parameters["default_sub_matrix_type"]``. For finer-grained control over the matrix type, one can provide it when -calling :func:`~.assemble` through the ``mat_type`` and +calling :func:`~firedrake.assemble.assemble` through the ``mat_type`` and ``sub_mat_type`` keyword arguments. When using variational solvers, the matrix type is controlled through use of the ``solver_parameters`` dictionary by specifying the ``"mat_type"`` entry. @@ -850,7 +850,7 @@ conditions. Sometimes this is not possible. In this case, you can ask Firedrake to remove the component of the right hand side that is in the transpose nullspace by providing a :class:`~firedrake.nullspace.VectorSpaceBasis` with the -``transpose_nullspace`` keyword argument to :func:`~.solve`. +``transpose_nullspace`` keyword argument to :func:`~firedrake.solving.solve`. Singular operators in mixed spaces ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -987,7 +987,7 @@ Checking the provided Jacobian It is possible to verify that the provided Jacobian is consistent with the residual we are trying to minimise by comparing it with a finite differenced Jacobian computed by PETSc. This is possible using only a -few extra options to the call to :func:`~.solve`. We just need to +few extra options to the call to :func:`~firedrake.solving.solve`. We just need to specify that the nonlinear solver we want PETSc to employ should be of type ``test``. PETSc will then go away, compute an approximate Jacobian by finite differencing the residual and compare it to our diff --git a/docs/source/variational-problems.rst b/docs/source/variational-problems.rst index e164f6c620..93f96bcc6e 100644 --- a/docs/source/variational-problems.rst +++ b/docs/source/variational-problems.rst @@ -508,7 +508,7 @@ how to do it here. First we define a function to hold the solution s = Function(V) -and call :py:func:`~.solve` to solve the variational +and call :py:func:`~firedrake.solving.solve` to solve the variational problem: .. code-block:: python3 diff --git a/firedrake/_deprecation.py b/firedrake/_deprecation.py index 4348bc6e6a..282b48624d 100644 --- a/firedrake/_deprecation.py +++ b/firedrake/_deprecation.py @@ -45,13 +45,23 @@ def __call__(*args, **kwargs): return __call__ -class SpikedModule: - def __init__(self, module): - self.module = module +class _spiked_module: + """ Replacement for modules removed from Firedrake's wildcard export. + + Parameters + ---------- + module: + Name of the module no longer exported by 'from firedrake import *' + """ + + def __init__(self, module): + self.module = module - def __getattr__(self, key): - raise AttributeError(f"'{self.module}.{key}' is not available via `from firedrake import *`." - f" Please import it directly (e.g. 'import firedrake.{self.module}).") + def __getattr__(self, key): + raise ImportError( + f"'{self.module}.{key}' is no longer exported by `from firedrake import *`." + f" Please import it directly (e.g. 'import firedrake.{self.module})." + ) # Deprecate plotting in the global namespace @@ -63,4 +73,5 @@ def __getattr__(self, key): ] ) -utils = SpikedModule("utils") +# Deprecate utils in the global namespace +utils = _spiked_module("utils") diff --git a/firedrake/mesh.py b/firedrake/mesh.py index 3c6646c6e3..c31b8c682d 100644 --- a/firedrake/mesh.py +++ b/firedrake/mesh.py @@ -61,7 +61,7 @@ __all__ = [ - 'RelabeledMesh', 'SubDomainData', 'UNMARKED', + 'RelabeledMesh', 'SubDomainData', 'UNMARKED', 'DistributedMeshOverlapType', 'DEFAULT_MESH_NAME', 'VertexOnlyMeshTopology', 'MeshSequenceGeometry', 'MeshSequenceTopology', 'Submesh' diff --git a/firedrake/preconditioners/asm.py b/firedrake/preconditioners/asm.py index 46f1082b5c..afc5bc9c23 100644 --- a/firedrake/preconditioners/asm.py +++ b/firedrake/preconditioners/asm.py @@ -12,7 +12,7 @@ import numpy -__all__ = ("ASMPatchPC", "ASMStarPC", "ASMVankaPC", "ASMLinesmoothPC", "ASMExtrudedStarPC") +__all__ = ("ASMPatchPC", "ASMVankaPC", "ASMLinesmoothPC") class ASMPatchPC(PCBase): diff --git a/firedrake/preconditioners/assembled.py b/firedrake/preconditioners/assembled.py index 4b94c36149..4f4645c6aa 100644 --- a/firedrake/preconditioners/assembled.py +++ b/firedrake/preconditioners/assembled.py @@ -4,8 +4,6 @@ import firedrake.dmhooks as dmhooks from firedrake.dmhooks import get_function_space -__all__ = ("AssembledPC", "AuxiliaryOperatorPC") - class AssembledPC(PCBase): """A matrix-free PC that assembles the operator. diff --git a/firedrake/preconditioners/auxiliary_snes.py b/firedrake/preconditioners/auxiliary_snes.py index 91e0a2c7fe..3d59de15b6 100644 --- a/firedrake/preconditioners/auxiliary_snes.py +++ b/firedrake/preconditioners/auxiliary_snes.py @@ -6,8 +6,6 @@ from ufl import replace from firedrake.dmhooks import get_function_space, get_appctx as get_dm_appctx -__all__ = ("AuxiliaryOperatorSNES",) - class AuxiliaryOperatorSNES(SNESBase): """ diff --git a/firedrake/preconditioners/base.py b/firedrake/preconditioners/base.py index 57522747a1..149c7c88d6 100644 --- a/firedrake/preconditioners/base.py +++ b/firedrake/preconditioners/base.py @@ -6,7 +6,7 @@ from firedrake.bcs import BCBase import ufl -__all__ = ("PCBase", "SNESBase", "PCSNESBase") +__all__ = ("PCBase", "SNESBase") class PCSNESBase(object, metaclass=abc.ABCMeta): diff --git a/firedrake/preconditioners/fdm.py b/firedrake/preconditioners/fdm.py index 89040eda7a..33ea7a67ff 100644 --- a/firedrake/preconditioners/fdm.py +++ b/firedrake/preconditioners/fdm.py @@ -36,7 +36,7 @@ import ctypes -__all__ = ("FDMPC", "PoissonFDMPC") +__all__ = ("PoissonFDMPC") class FDMPC(PCBase): diff --git a/firedrake/preconditioners/gtmg.py b/firedrake/preconditioners/gtmg.py index d26c6b73fe..052ae3789c 100644 --- a/firedrake/preconditioners/gtmg.py +++ b/firedrake/preconditioners/gtmg.py @@ -10,9 +10,6 @@ import firedrake.dmhooks as dmhooks -__all__ = ['GTMGPC'] - - class GTMGPC(PCBase): """Non-nested multigrid preconditioner diff --git a/firedrake/preconditioners/hypre_ams.py b/firedrake/preconditioners/hypre_ams.py index 998d9e9a5c..1bd645cf72 100644 --- a/firedrake/preconditioners/hypre_ams.py +++ b/firedrake/preconditioners/hypre_ams.py @@ -11,8 +11,6 @@ from finat.ufl import FiniteElement, TensorElement, VectorElement from pyop2.utils import as_tuple -__all__ = ("HypreAMS",) - def chop(A, tol=1E-10): # remove (near) zeros from sparsity pattern diff --git a/firedrake/preconditioners/low_order.py b/firedrake/preconditioners/low_order.py index 5f41e65d3f..f09d5412ef 100644 --- a/firedrake/preconditioners/low_order.py +++ b/firedrake/preconditioners/low_order.py @@ -1,6 +1,6 @@ from firedrake.preconditioners.pmg import PMGPC, PMGSNES -__all__ = ("P1PC", "P1SNES", "LORPC") +__all__ = ("LORPC") class P1PC(PMGPC): diff --git a/firedrake/preconditioners/massinv.py b/firedrake/preconditioners/massinv.py index 06aa192cd4..58f596f01a 100644 --- a/firedrake/preconditioners/massinv.py +++ b/firedrake/preconditioners/massinv.py @@ -1,8 +1,6 @@ from firedrake.preconditioners.assembled import AssembledPC from firedrake import inner, dx -__all__ = ("MassInvPC", ) - class MassInvPC(AssembledPC): """A matrix free operator that assembles the mass matrix in the provided space. diff --git a/firedrake/preconditioners/pcd.py b/firedrake/preconditioners/pcd.py index dbc4671720..564fd47a05 100644 --- a/firedrake/preconditioners/pcd.py +++ b/firedrake/preconditioners/pcd.py @@ -1,8 +1,6 @@ from firedrake.preconditioners.base import PCBase from firedrake.petsc import PETSc -__all__ = ("PCDPC", ) - class PCDPC(PCBase): diff --git a/firedrake/preconditioners/pmg.py b/firedrake/preconditioners/pmg.py index 3320bffc01..5218b3203a 100644 --- a/firedrake/preconditioners/pmg.py +++ b/firedrake/preconditioners/pmg.py @@ -25,9 +25,6 @@ import weakref -__all__ = ("PMGSNES") - - class PMGBase(PCSNESBase): """A class for implementing p-multigrid. diff --git a/firedrake/slate/static_condensation/hybridization.py b/firedrake/slate/static_condensation/hybridization.py index f3dc7a9ece..2bfc075b19 100644 --- a/firedrake/slate/static_condensation/hybridization.py +++ b/firedrake/slate/static_condensation/hybridization.py @@ -12,7 +12,7 @@ from firedrake.slate.static_condensation.la_utils import SchurComplementBuilder from firedrake.ufl_expr import adjoint -__all__ = ['HybridizationPC', 'SchurComplementBuilder'] +__all__ = ['SchurComplementBuilder'] class HybridizationPC(SCBase): diff --git a/firedrake/slate/static_condensation/scpc.py b/firedrake/slate/static_condensation/scpc.py index d176e56a05..a5fa99a894 100644 --- a/firedrake/slate/static_condensation/scpc.py +++ b/firedrake/slate/static_condensation/scpc.py @@ -7,9 +7,6 @@ from firedrake.slate.slate import Tensor -__all__ = ['SCPC'] - - class SCPC(SCBase): needs_python_pmat = True diff --git a/firedrake/utility_meshes.py b/firedrake/utility_meshes.py index 91e71b2ee1..3d96a9aa09 100644 --- a/firedrake/utility_meshes.py +++ b/firedrake/utility_meshes.py @@ -35,12 +35,10 @@ __all__ = [ - "IntervalMesh", "UnitIntervalMesh", "PeriodicIntervalMesh", "PeriodicUnitIntervalMesh", "UnitTriangleMesh", - "RectangleMesh", "TensorRectangleMesh", "SquareMesh", "UnitSquareMesh", @@ -52,7 +50,6 @@ "UnitBallMesh", "UnitTetrahedronMesh", "TensorBoxMesh", - "BoxMesh", "CubeMesh", "UnitCubeMesh", "PeriodicBoxMesh", diff --git a/firedrake/variational_solver.py b/firedrake/variational_solver.py index da7ea69988..597b5eb9a6 100644 --- a/firedrake/variational_solver.py +++ b/firedrake/variational_solver.py @@ -18,10 +18,7 @@ from functools import cached_property from collections.abc import Callable -__all__ = ["LinearVariationalProblem", - "LinearVariationalSolver", - "NonlinearVariationalProblem", - "NonlinearVariationalSolver"] +__all__ = ["LinearVariationalProblem", "NonlinearVariationalProblem"] def check_pde_args(F, J, Jp, E=None): From 9136b7098e33eb48b764fd7f6f8106158a9061e8 Mon Sep 17 00:00:00 2001 From: Connor Ward Date: Thu, 3 Sep 2026 09:03:33 +0100 Subject: [PATCH 17/28] Fix some duplicate refs --- demos/adaptive_multigrid/adaptive_multigrid.py.rst | 12 ++++++------ docs/source/citing.rst | 2 +- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/demos/adaptive_multigrid/adaptive_multigrid.py.rst b/demos/adaptive_multigrid/adaptive_multigrid.py.rst index 81276fcf44..5418b04b89 100644 --- a/demos/adaptive_multigrid/adaptive_multigrid.py.rst +++ b/demos/adaptive_multigrid/adaptive_multigrid.py.rst @@ -5,7 +5,7 @@ Adaptive Multigrid Methods Contributed by Anurag Rao. The purpose of this demo is to show how to use Firedrake's multigrid solver on a hierarchy of adaptively refined Netgen meshes. -A :func:`~.MeshHierarchy` is not restricted to uniform refinement: the same object records the parent child relations between adaptively refined meshes, and grows a level at a time as the solution is resolved. +A :func:`MeshHierarchy ` is not restricted to uniform refinement: the same object records the parent child relations between adaptively refined meshes, and grows a level at a time as the solution is resolved. We will first have a look at how to construct such a hierarchy from Netgen meshes, then we will consider a solution to the Poisson problem on an L-shaped domain, and finally we will use the hierarchy to construct a scalable solver. We begin by importing the necessary libraries :: @@ -27,13 +27,13 @@ We begin with the L-shaped domain, which we build as the union of two rectangles ngmsh = geo.GenerateMesh(maxh=0.5) mesh = Mesh(ngmsh) -It is important to convert the initial Netgen mesh into a Firedrake mesh before constructing the :func:`~.MeshHierarchy`. To call the constructor to the hierarchy, we must pass the initial mesh. Our initial mesh looks like this: +It is important to convert the initial Netgen mesh into a Firedrake mesh before constructing the :func:`MeshHierarchy `. To call the constructor to the hierarchy, we must pass the initial mesh. Our initial mesh looks like this: .. figure:: initial_mesh.png :align: center :alt: Initial mesh. -We initialize the :func:`~.MeshHierarchy` here. The default of zero uniform refinement levels gives a hierarchy holding just the initial mesh, which we will grow adaptively below; passing a positive number instead would start us off with that many uniformly refined levels, and the adaptive levels would stack on top of them just the same: :: +We initialize the :func:`MeshHierarchy ` here. The default of zero uniform refinement levels gives a hierarchy holding just the initial mesh, which we will grow adaptively below; passing a positive number instead would start us off with that many uniformly refined levels, and the adaptive levels would stack on top of them just the same: :: mh = MeshHierarchy(mesh) @@ -173,14 +173,14 @@ With these helper functions complete, we can solve the system iteratively. In th if level != refinements - 1: mh.adapt(eta, theta) -To perform Dörfler marking, refine the current mesh, and add the mesh to the hierarchy, we use the :meth:`~.HierarchyBase.adapt` method. In this method the input is the recently computed error estimator ``eta`` and the Dörfler marking parameter ``theta``. The method always performs this on the current fine mesh in the hierarchy. -To mark cells by some other criterion, refine the finest mesh yourself and add the result, which is all that :meth:`~.HierarchyBase.adapt` does once it has marked: +To perform Dörfler marking, refine the current mesh, and add the mesh to the hierarchy, we use the :meth:`HierarchyBase.adapt ` method. In this method the input is the recently computed error estimator ``eta`` and the Dörfler marking parameter ``theta``. The method always performs this on the current fine mesh in the hierarchy. +To mark cells by some other criterion, refine the finest mesh yourself and add the result, which is all that :meth:`HierarchyBase.adapt ` does once it has marked: .. code-block:: python mh.add_mesh(mh[-1].refine_marked_elements(markers)) -Here ``markers`` is a DG0 function whose value on each cell is the number of times to refine it. If the mesh was instead produced by some procedure Firedrake cannot trace the parent child relations through, pass those cell maps to :meth:`~.HierarchyBase.add_mesh` explicitly. +Here ``markers`` is a DG0 function whose value on each cell is the number of times to refine it. If the mesh was instead produced by some procedure Firedrake cannot trace the parent child relations through, pass those cell maps to :meth:`HierarchyBase.add_mesh ` explicitly. The meshes now refine according to the error estimator. The error estimators at levels 3,5, and 15 are shown below. Zooming into the vertex of the L-shape at level 15 shows the error indicator remains strongest there. Further refinements will focus on that area. +-------------------------------+-------------------------------+-------------------------------+ diff --git a/docs/source/citing.rst b/docs/source/citing.rst index de5ae526a6..58f5eb659e 100644 --- a/docs/source/citing.rst +++ b/docs/source/citing.rst @@ -44,7 +44,7 @@ please cite :cite:`Homolya2016` and :cite:`McRae2016`. If you use :py:func:`~.VertexOnlyMesh`, please cite :cite:`nixonhill2023consistent`. If you use the interfaces to couple Firedrake and machine learning frameworks such as PyTorch or JAX, -please cite :cite:`Bouziani2024`. If you use the :py:class:`~.AbstractExternalOperator` +please cite :cite:`Bouziani2024`. If you use the :py:class:`AbstractExternalOperator ` interface, please cite :cite:`Bouziani2024` and :cite:`Bouziani2021`. The form compiler, TSFC, is documented in :cite:`Homolya2018` and From 068e134816dad13180ceaf90f0ef30dcf1ae5588 Mon Sep 17 00:00:00 2001 From: Connor Ward Date: Thu, 3 Sep 2026 09:28:40 +0100 Subject: [PATCH 18/28] apidoc improvements * Put Firedrake modules on separate pages * Use full arg names in sphinx-apidoc so its less magic * Add :orphan: tag to modules.rst via sed --- docs/Makefile | 4 +++- docs/source/documentation.rst | 2 +- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/Makefile b/docs/Makefile index c26010b389..a9f7a92288 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -125,7 +125,9 @@ source/petsc_configure_options.txt: mv source/petsc_configure_options.tmp source/petsc_configure_options.txt apidoc: $(GENERATED_FILES) copy_demos - sphinx-apidoc -f -T -o source/ ../firedrake ../firedrake/cython/*.so + sphinx-apidoc --module-first --separate --force -o source/ ../firedrake ../firedrake/cython/*.so + @# Add :orphan: directive to modules.rst to avoid a warning + sed -i '1i\:orphan:\n' source/modules.rst clean: -rm -rf $(BUILDDIR)/* diff --git a/docs/source/documentation.rst b/docs/source/documentation.rst index eef625aaa7..624ceb711b 100644 --- a/docs/source/documentation.rst +++ b/docs/source/documentation.rst @@ -58,7 +58,7 @@ ================= The complete list of all the classes and methods in Firedrake is - available at the :doc:`firedrake` page. The same information is + available at the :doc:`modules` page. The same information is :ref:`indexed ` in alphabetical order. Another very effective mechanism is the site :ref:`search engine `. From 7ed599eb5bee5a664c2f6e947ae7658aae0f16a1 Mon Sep 17 00:00:00 2001 From: nwng04 Date: Thu, 3 Sep 2026 14:31:48 +0100 Subject: [PATCH 19/28] Remove whitespaces in deprecation.py --- firedrake/_deprecation.py | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/firedrake/_deprecation.py b/firedrake/_deprecation.py index 282b48624d..0dc89de5ff 100644 --- a/firedrake/_deprecation.py +++ b/firedrake/_deprecation.py @@ -47,21 +47,21 @@ def __call__(*args, **kwargs): class _spiked_module: """ Replacement for modules removed from Firedrake's wildcard export. - + Parameters ---------- module: Name of the module no longer exported by 'from firedrake import *' """ - + def __init__(self, module): self.module = module def __getattr__(self, key): raise ImportError( - f"'{self.module}.{key}' is no longer exported by `from firedrake import *`." - f" Please import it directly (e.g. 'import firedrake.{self.module})." - ) + f"'{self.module}.{key}' is no longer exported by `from firedrake import *`." + f" Please import it directly (e.g. 'import firedrake.{self.module})." + ) # Deprecate plotting in the global namespace From 340b496b26784965ef1d79e2eef1425789d9dbe1 Mon Sep 17 00:00:00 2001 From: nwng04 Date: Thu, 3 Sep 2026 16:54:27 +0100 Subject: [PATCH 20/28] Specify module locations in demos --- .../adaptive_multigrid.py.rst | 2 +- demos/boussinesq/boussinesq.py.rst | 4 +- demos/burgers/burgers.py.rst | 8 +- demos/camassa-holm/camassaholm.py.rst | 18 ++--- demos/deflation/deflation.py.rst | 2 +- .../fast_diagonalisation_poisson.py.rst | 28 +++---- .../full_waveform_inversion.py.rst | 4 +- .../linear_wave_equation.py.rst | 2 +- demos/ma-demo/ma-demo.py.rst | 2 +- demos/matrix_free/navier_stokes.py.rst | 2 +- demos/matrix_free/rayleigh-benard.py.rst | 2 +- demos/matrix_free/stokes.py.rst | 2 +- demos/multicomponent/multicomponent.py.rst | 8 +- demos/multigrid/geometric_multigrid.py.rst | 2 +- demos/patch/hcurl_riesz_star.py.rst | 8 +- demos/patch/hdiv_riesz_star.py.rst | 6 +- demos/patch/poisson_mg_patches.py.rst | 14 ++-- demos/patch/stokes_vanka_patches.py.rst | 16 ++-- .../qg_1layer_wave.py.rst | 6 +- .../reynolds_robust_navier_stokes_hdiv.py.rst | 2 +- .../saddle_point_systems.py.rst | 8 +- .../submesh_reaction_diffusion.py.rst | 8 +- demos/vlasov_poisson_1d/vp1d.py.rst | 14 ++-- docs/source/adjoint.rst | 4 +- docs/source/boundary_conditions.rst | 10 +-- docs/source/checkpointing.rst | 64 +++++++-------- docs/source/citing.rst | 2 +- docs/source/duals.rst | 12 +-- docs/source/ensemble_parallelism.rst | 78 +++++++++---------- docs/source/external_operators.rst | 22 +++--- docs/source/extruded-meshes.rst | 6 +- docs/source/interpolation.rst | 36 ++++----- docs/source/mesh-coordinates.rst | 12 +-- docs/source/optimising.rst | 4 +- docs/source/parallelism.rst | 6 +- docs/source/point-evaluation.rst | 40 +++++----- docs/source/preconditioning.rst | 4 +- docs/source/quadrature.rst | 8 +- docs/source/solving-interface.rst | 18 ++--- docs/source/variational-problems.rst | 54 ++++++------- docs/source/visualisation.rst | 28 +++---- .../adjoint/ensemble_reduced_functional.py | 6 +- firedrake/checkpointing.py | 48 ++++++------ firedrake/cython/dmcommon.pyx | 2 +- firedrake/dmhooks.py | 6 +- firedrake/embedding.py | 2 +- firedrake/ensemble/ensemble_function.py | 24 +++--- firedrake/ensemble/ensemble_functionspace.py | 16 ++-- firedrake/ensemble/ensemble_mat.py | 12 +-- firedrake/ensemble/ensemble_pc.py | 12 +-- firedrake/exceptions.py | 2 +- firedrake/extrusion_utils.py | 4 +- firedrake/function.py | 8 +- firedrake/functionspacedata.py | 4 +- firedrake/functionspaceimpl.py | 20 ++--- firedrake/mesh.py | 12 +-- firedrake/mg/mesh.py | 8 +- firedrake/nullspace.py | 4 +- firedrake/preconditioners/asm.py | 2 +- firedrake/pyplot/mpl.py | 30 +++---- firedrake/slate/slate.py | 4 +- firedrake/solving.py | 4 +- firedrake/tsfc_interface.py | 2 +- firedrake/ufl_expr.py | 2 +- firedrake/utility_meshes.py | 67 ++++++++-------- firedrake/variational_solver.py | 8 +- 66 files changed, 442 insertions(+), 443 deletions(-) diff --git a/demos/adaptive_multigrid/adaptive_multigrid.py.rst b/demos/adaptive_multigrid/adaptive_multigrid.py.rst index 5418b04b89..5c67d3265e 100644 --- a/demos/adaptive_multigrid/adaptive_multigrid.py.rst +++ b/demos/adaptive_multigrid/adaptive_multigrid.py.rst @@ -45,7 +45,7 @@ Now we can define a simple Poisson problem - \nabla^2 u = f \text{ in } \Omega, \quad u = 0 \text{ on } \partial \Omega. -Our approach strongly follows the similar problem in this `lecture course `_. We define the function ``solve_poisson``. The first lines correspond to finding a solution in the CG1 space. The right-hand side is set to be the constant function equal to 1. Since we want Dirichlet boundary conditions, we construct the :class:`~.DirichletBC` object and apply it to the entire boundary: :: +Our approach strongly follows the similar problem in this `lecture course `_. We define the function ``solve_poisson``. The first lines correspond to finding a solution in the CG1 space. The right-hand side is set to be the constant function equal to 1. Since we want Dirichlet boundary conditions, we construct the :class:`DirichletBC ` object and apply it to the entire boundary: :: def solve_poisson(mesh, params): V = FunctionSpace(mesh, "CG", 1) diff --git a/demos/boussinesq/boussinesq.py.rst b/demos/boussinesq/boussinesq.py.rst index 5cc6708cf0..46787a4557 100644 --- a/demos/boussinesq/boussinesq.py.rst +++ b/demos/boussinesq/boussinesq.py.rst @@ -142,14 +142,14 @@ and the (strongly enforced) Dirichlet boundary conditions on :math:`u` are enfor bc_u = DirichletBC(Z.sub(0), 0, "on_boundary") -At this point we could form and solve a :class:`~.NonlinearVariationalProblem` +At this point we could form and solve a :class:`NonlinearVariationalProblem ` using :code:`F` and :code:`bc_u`. However, the resultant problem has a nullspace of dimension 2, corresponding to (i) shifting :math:`p` by a constant :math:`C_1` and (ii) shifting :math:`l` by a constant :math:`C_2` while simultaneuosly shifting :math:`T_{\textrm{aux}}` by :math:`-C_2`. One way of dealing with nullspaces in Firedrake is to pass a :code:`nullspace` and -:code:`transpose_nullspace` to :class:`~.NonlinearVariationalSolver`. However, sometimes +:code:`transpose_nullspace` to :class:`NonlinearVariationalSolver `. However, sometimes this approach may not be practical. First, for nonlinear problems with Jacobians that are not symmetric, it may not obvious what the :code:`transpose_nullspace` is. A second reason is that, when using customised PETSc linear solvers, it may be desirable diff --git a/demos/burgers/burgers.py.rst b/demos/burgers/burgers.py.rst index 52fea37f42..6ee2d7bacf 100644 --- a/demos/burgers/burgers.py.rst +++ b/demos/burgers/burgers.py.rst @@ -93,12 +93,12 @@ We now create an object for output visualisation:: Output only supports visualisation of linear fields (either P1, or P1DG). In this example we project to a linear space by hand. Another -option is to let the :class:`~.vtk_output.VTKFile` object manage the +option is to let the :class:`VTKFile ` object manage the decimation. It supports both interpolation to linears (the default) or projection (by passing ``project_output=True`` when creating the -:class:`~.vtk_output.VTKFile`). Outputting data is carried out using -the :meth:`~.vtk_output.VTKFile.write` method of -:class:`~.vtk_output.VTKFile` objects:: +:class:`VTKFile `). Outputting data is carried out using +the :meth:`write ` method of +:class:`VTKFile ` objects:: outfile.write(project(u, V_out, name="Velocity")) diff --git a/demos/camassa-holm/camassaholm.py.rst b/demos/camassa-holm/camassaholm.py.rst index b894a0523f..1342ac3657 100644 --- a/demos/camassa-holm/camassaholm.py.rst +++ b/demos/camassa-holm/camassaholm.py.rst @@ -78,23 +78,23 @@ We then set the parameters for the scheme. :: dt = 0.1 Dt = Constant(dt) -These are set with type :class:`~.Constant` so that the values can be +These are set with type :class:`constant ` so that the values can be changed without needing to regenerate code. -We use a :func:`periodic mesh <.PeriodicIntervalMesh>` of width 40 +We use a :func:`periodic mesh ` of width 40 with 100 cells, :: n = 100 mesh = PeriodicIntervalMesh(n, 40.0) -and build a :class:`mixed function space <.MixedFunctionSpace>` for the +and build a :class:`mixed function space ` for the two variables. :: V = FunctionSpace(mesh, "CG", 1) W = MixedFunctionSpace((V, V)) -We construct a :class:`~.Function` to store the two variables at time -level ``n``, and :attr:`~.Function.subfunctions` it so that we can +We construct a :class:`function ` to store the two variables at time +level ``n``, and :attr:`subfunctions ` it so that we can interpolate the initial condition into the two components. :: w0 = Function(W) @@ -130,7 +130,7 @@ solver since the problem is one dimensional). :: Next we build the weak form of the timestepping algorithm. This is expressed as a mixed nonlinear problem, which must be written as a bilinear form -that is a function of the output :class:`~.Function` ``w1``. :: +that is a function of the output :class:`function ` ``w1``. :: p, q = TestFunctions(W) @@ -140,7 +140,7 @@ that is a function of the output :class:`~.Function` ``w1``. :: m0, u0 = split(w0) Note the use of :func:`split(w1) ` here, which splits up a -:class:`~.Function` so that it may be inserted into a UFL +:class:`function ` so that it may be inserted into a UFL expression. :: mh = 0.5*(m1 + m0) @@ -161,14 +161,14 @@ rather than blocked system. :: 'ksp_type': 'preonly', 'pc_type': 'lu'}) -Next we use the other form of :attr:`~.Function.subfunctions`, ``w0.subfunctions``, +Next we use the other form of :attr:`subfunctions `, ``w0.subfunctions``, which is the way to split up a Function in order to access its data e.g. for output. :: m0, u0 = w0.subfunctions m1, u1 = w1.subfunctions -We choose a final time, and initialise a :class:`~.vtk_output.VTKFile` +We choose a final time, and initialise a :class:`VTKFile ` object for storing ``u``. as well as an array for storing the function to be visualised:: diff --git a/demos/deflation/deflation.py.rst b/demos/deflation/deflation.py.rst index 61debb9247..d28125ccac 100644 --- a/demos/deflation/deflation.py.rst +++ b/demos/deflation/deflation.py.rst @@ -44,7 +44,7 @@ We implement the usual weak formulation of the equation in Firedrake as standard bcs = DirichletBC(V, 0, "on_boundary") problem = NonlinearVariationalProblem(F, u, bcs) -Applying deflation requires two ingredients: the :class:`~.deflation.DeflatedSNES` nonlinear solver, and a :class:`~.deflation.Deflation` object. The :class:`~.deflation.Deflation` object records the solutions to be deflated, and specifies the sense of distance to use in deflation. In this example we use the metric induced by the :math:`L^2(\Omega)` inner product: :: +Applying deflation requires two ingredients: the :class:`DeflatedSNES ` nonlinear solver, and a :class:`Deflation ` object. The :class:`Deflation ` object records the solutions to be deflated, and specifies the sense of distance to use in deflation. In this example we use the metric induced by the :math:`L^2(\Omega)` inner product: :: sp = {"snes_type": "python", "snes_python_type": "firedrake.DeflatedSNES", diff --git a/demos/fast_diagonalisation/fast_diagonalisation_poisson.py.rst b/demos/fast_diagonalisation/fast_diagonalisation_poisson.py.rst index 3179e99302..4dc54a3c70 100644 --- a/demos/fast_diagonalisation/fast_diagonalisation_poisson.py.rst +++ b/demos/fast_diagonalisation/fast_diagonalisation_poisson.py.rst @@ -20,7 +20,7 @@ The fast diagonalisation method produces a basis of discrete eigenfunctions. These are polynomials, and can be efficiently computed on tensor product-elements by solving an eigenproblem on the interval. Therefore, we will require quadrilateral or hexahedral meshes. Currently, the solver only supports -extruded hexahedral meshes, so we must create an :func:`~.ExtrudedMesh`. :: +extruded hexahedral meshes, so we must create an :func:`ExtrudedMesh `. :: from firedrake import * @@ -33,14 +33,14 @@ Defining the problem: the Poisson equation Having defined the mesh we now need to set up our problem. The crucial step for fast diagonalisation is a special choice of basis functions. We obtain them -by passing ``variant="fdm"`` to the :func:`~.FunctionSpace` constructor. The +by passing ``variant="fdm"`` to the :func:`function space ` constructor. The solvers in this demo work also with other element variants, but each iteration would involve an additional a basis transformation. To stress-test the solver, -we prescribe a random :class:`~.Cofunction` as right-hand side. +we prescribe a random :class:`Cofunction ` as right-hand side. We'll demonstrate a few different sets of solver parameters, so let's define a function that takes in set of parameters and uses them on a -:class:`~.LinearVariationalSolver`. :: +:class:`linear variational solver `. :: def run_solve(degree, parameters): @@ -65,8 +65,8 @@ Specifying the solver The solver avoids the assembly of a matrix with dense element submatrices, and instead applies a matrix-free conjugate gradient method with a preconditioner obtained by assembling a sparse matrix. This is done through the python type -preconditioner :class:`~.FDMPC`. We define a function that enables us to -compose :class:`~.FDMPC` with an inner relaxation. :: +preconditioner :class:`FDMPC `. We define a function that enables us to +compose :class:`FDMPC ` with an inner relaxation. :: def fdm_params(relax): @@ -93,16 +93,16 @@ using a sparse direct LU factorization. :: .. note:: - On this Cartesian mesh, the sparse operator constructed by :class:`~.FDMPC` + On this Cartesian mesh, the sparse operator constructed by :class:`FDMPC ` corresponds to the original operator. This is no longer the case with non-Cartesian meshes or more general PDEs, as the FDM basis only diagonalises very specific - problems. For such cases, :class:`~.FDMPC` will produce a sparse + problems. For such cases, :class:`FDMPC ` will produce a sparse approximation of the original operator. Moving on to a more complicated solver, we'll employ a two-level solver with -the lowest-order coarse space via :class:`~.P1PC`. As the fine level +the lowest-order coarse space via :class:`P1PC `. As the fine level relaxation we define an additive Schwarz method on vertex-star patches -implemented via :class:`~.ASMExtrudedStarPC` as we have an extruded mesh. +implemented via :class:`ASMExtrudedStarPC ` as we have an extruded mesh. In addition we specify `"use_coloring"` to group non-overlapping subsets of patches into sparse block-diagonal matrices via a mesh coloring, which reduces the overhead of calling many KSP solves for each patch.:: @@ -143,17 +143,17 @@ We observe degree-independent iteration counts: Static condensation ------------------- -Finally, we construct :class:`~.FDMPC` solver parameters using static +Finally, we construct :class:`FDMPC ` solver parameters using static condensation. The fast diagonalisation basis diagonalises the operator on cell interiors. So we define a solver that splits the interior and facet degrees of -freedom via :class:`~.FacetSplitPC` and fieldsplit options. We set the option -``fdm_static_condensation`` to tell :class:`~.FDMPC` to assemble a 2-by-2 block +freedom via :class:`FacetSplitPC ` and fieldsplit options. We set the option +``fdm_static_condensation`` to tell :class:`FDMPC ` to assemble a 2-by-2 block preconditioner where the lower-right block is replaced by the Schur complement resulting from eliminating the interior degrees of freedom. The Krylov solver is posed on the full set of degrees of freedom, and the preconditioner applies a symmetrized multiplicative sweep on the interior and the facet degrees of freedom. In general, we are not able to fully eliminate the -interior, as the sparse operator constructed by :class:`~.FDMPC` is only an +interior, as the sparse operator constructed by :class:`FDMPC ` is only an approximation on non-Cartesian meshes. We apply point-Jacobi on the interior block, and the two-level additive Schwarz method on the facets. :: diff --git a/demos/full_waveform_inversion/full_waveform_inversion.py.rst b/demos/full_waveform_inversion/full_waveform_inversion.py.rst index 06390072da..7be18c938a 100644 --- a/demos/full_waveform_inversion/full_waveform_inversion.py.rst +++ b/demos/full_waveform_inversion/full_waveform_inversion.py.rst @@ -278,7 +278,7 @@ To have the step 4, we need first to tape the forward problem. That is done by c misfit = guess_receiver - true_data_receivers[step] J_val += 0.5 * assemble(inner(misfit, misfit) * dx) -We now instantiate :class:`~.EnsembleReducedFunctional`:: +We now instantiate :class:`EnsembleReducedFunctional `:: J_hat = EnsembleReducedFunctional(J_val, Control(c_guess, riesz_map="l2"), @@ -289,7 +289,7 @@ where the :math:`J_s` and its gradients :math:`\nabla_{\mathtt{c\_guess}} J_s` a based on the ``my_ensemble`` configuration. -**Steps 4-6**: The instance of the :class:`~.EnsembleReducedFunctional`, named ``J_hat``, +**Steps 4-6**: The instance of the :class:`EnsembleReducedFunctional `, named ``J_hat``, is then passed as an argument to the ``minimize`` function. The default ``minimize`` function uses ``scipy.minimize``, and wraps the ``ReducedFunctional`` in a ``ReducedFunctionalNumPy`` that handles transferring data between Firedrake and numpy data structures. However, because diff --git a/demos/linear-wave-equation/linear_wave_equation.py.rst b/demos/linear-wave-equation/linear_wave_equation.py.rst index 770db2f44d..ecd876495c 100644 --- a/demos/linear-wave-equation/linear_wave_equation.py.rst +++ b/demos/linear-wave-equation/linear_wave_equation.py.rst @@ -128,7 +128,7 @@ Step forward :math:`\phi` by the second half timestep:: phi -= dt / 2 * p Advance time and output as appropriate, note how we pass the current -timestep value into the :meth:`~.VTKFile.write` method, so that when +timestep value into the :meth:`write ` method, so that when visualising the results Paraview will use it:: t += dt diff --git a/demos/ma-demo/ma-demo.py.rst b/demos/ma-demo/ma-demo.py.rst index 432042a20d..75ebea3c97 100644 --- a/demos/ma-demo/ma-demo.py.rst +++ b/demos/ma-demo/ma-demo.py.rst @@ -91,7 +91,7 @@ We then combine them together in a mixed function space. :: W = V*Sigma Next, we set up the source function, which must integrate to the area -of the domain. Note how in the integration of the :class:`~.Constant` +of the domain. Note how in the integration of the :class:`constant ` one, we must explicitly specify the domain we wish to integrate over. :: x, y = SpatialCoordinate(mesh) diff --git a/demos/matrix_free/navier_stokes.py.rst b/demos/matrix_free/navier_stokes.py.rst index f9ce8383a6..2e00b4d718 100644 --- a/demos/matrix_free/navier_stokes.py.rst +++ b/demos/matrix_free/navier_stokes.py.rst @@ -64,7 +64,7 @@ in a ``try/except`` block. :: else: raise e -Now we'll show an example using the :class:`~.PCDPC` preconditioner +Now we'll show an example using the :class:`PCDPC ` preconditioner that implements the pressure convection-diffusion approximation to the pressure Schur complement. We'll need more solver parameters this time, so again we'll set those up in a dictionary. :: diff --git a/demos/matrix_free/rayleigh-benard.py.rst b/demos/matrix_free/rayleigh-benard.py.rst index 8b0202d9fe..b56a00dc06 100644 --- a/demos/matrix_free/rayleigh-benard.py.rst +++ b/demos/matrix_free/rayleigh-benard.py.rst @@ -139,7 +139,7 @@ Now for the solve. :: Finally, we'll demonstrate recursive fieldsplitting. We'll use the same multiplicative fieldsplit preconditioner for the velocity-pressure and temperature blocks, but we'll precondition the -Navier-Stokes part with :class:`~.PCDPC` using a lower Schur +Navier-Stokes part with :class:`PCDPC ` using a lower Schur complement factorisation, and approximately invert the temperature block using algebraic multigrid. There are lots of parameters here, so let's run through them. Since there are many options here, in diff --git a/demos/matrix_free/stokes.py.rst b/demos/matrix_free/stokes.py.rst index fd9336b23d..8a7c29be3b 100644 --- a/demos/matrix_free/stokes.py.rst +++ b/demos/matrix_free/stokes.py.rst @@ -132,7 +132,7 @@ file.:: VTKFile("stokes.pvd").write(u, p) -By default, the mass matrix is assembled in the :class:`~.MassInvPC` +By default, the mass matrix is assembled in the :class:`MassInvPC ` preconditioner, however, this can be controlled using a ``mat_type`` argument. To do this, we must specify the ``mat_type`` inside the preconditioner. We can use the previous set of parameters and just diff --git a/demos/multicomponent/multicomponent.py.rst b/demos/multicomponent/multicomponent.py.rst index c21ebbc211..fdf5c88293 100644 --- a/demos/multicomponent/multicomponent.py.rst +++ b/demos/multicomponent/multicomponent.py.rst @@ -428,15 +428,15 @@ only apply to the normal component of H(div) functions. Elsewhere on the boundary we enforce :math:`J_i \cdot N = 0`. Finally, instead of specifying the value of the barycentric velocity :math:`v` on the inflows and outflows, we enforce :math:`v = \rho^{-1}(G_1 + G_2)`. Boundary conditions that couple -unknowns and/or are nonlinear must be implemented with :class:`~.EquationBC` instead of :class:`~.DirichletBC`. +unknowns and/or are nonlinear must be implemented with :class:`EquationBCs ` instead of :class:`DirichletBC `. Since the barycentric velocity is in :math:`[\textrm{CG}_k]^2` it has degrees of freedom located at the points where the inlets/outlet meet the walls. Even though the boundary conditions on the inlets/outlet -and the walls are compatible at these points, :class:`~.EquationBC` enforces the boundary conditions weakly whilst -:class:`~.DirichletBC` enforces them strongly. Hence, to avoid ambiguity, we set Dirichlet boundary +and the walls are compatible at these points, :class:`EquationBCs ` enforces the boundary conditions weakly whilst +:class:`DirichletBC ` enforces them strongly. Hence, to avoid ambiguity, we set Dirichlet boundary conditions on the boundary of the boundary, i.e. the points where the inlets/outlet meet the walls. To enforce these Dirichlet boundary conditions, tuples with the numbers of the boundary edges coincidental to these points need to be constructed first. This is then passed on to a Dirichlet boundary condition -which is passed on to :class:`~.EquationBC`.:: +which is passed on to :class:`EquationBCs `.:: # Reference species velocities, which we choose to symmetrize so that the molar fluxes agree v_ref_1 = Constant(0.4e-6) # Reference inflow velocity of benzene, m / s diff --git a/demos/multigrid/geometric_multigrid.py.rst b/demos/multigrid/geometric_multigrid.py.rst index 223a40b1d3..343b47a01a 100644 --- a/demos/multigrid/geometric_multigrid.py.rst +++ b/demos/multigrid/geometric_multigrid.py.rst @@ -14,7 +14,7 @@ Creating a geometric hierarchy Geometric multigrid requires a geometric hierarchy of meshes on which the equations will be discretised. To create a hierarchy, we use -:func:`~.MeshHierarchy` to create a hierarchy of meshes, the resulting +:func:`MeshHierarchy ` to create a hierarchy of meshes, the resulting object remembers the relationships between them. Currently, these hierarchies are constructed using regular bisection refinement, so we must create a coarse mesh. :: diff --git a/demos/patch/hcurl_riesz_star.py.rst b/demos/patch/hcurl_riesz_star.py.rst index 3bb3e83416..be9f686a66 100644 --- a/demos/patch/hcurl_riesz_star.py.rst +++ b/demos/patch/hcurl_riesz_star.py.rst @@ -7,10 +7,10 @@ and `Pablo Brubeck `_. Multigrid in H(div) and H(curl) also requires relaxation based on topological patches. Here, we demonstrate how to do this in the latter case. -We start by importing firedrake and setting up a :func:`.MeshHierarchy` and the +We start by importing firedrake and setting up a :func:`MeshHierarchy ` and the exact solution and forcing data. Crucially, the meshes must have an overlapping parallel domain decomposition that supports the vertex star patches. This is set -via the ``distribution_parameters`` kwarg of the :func:`.Mesh` constructor. :: +via the ``distribution_parameters`` kwarg of the :func:`Mesh ` constructor. :: from firedrake import * @@ -41,7 +41,7 @@ impose homogeneous Dirichlet boundary conditions:: return solver.snes.getLinearSolveIterations() -Having done both :class:`~.ASMStarPC` and :class:`~.PatchPC` in other demos, +Having done both :class:`ASMStarPC ` and :class:`PatchPC ` in other demos, here we simply opt for the former. Arnold, Falk, and Winther show that vertex patches yield a robust method. :: @@ -74,7 +74,7 @@ patches yield a robust method. :: Hiptmair proposed a finer space decomposition for Nedelec elements using edge patches on the original Nedelec space and vertex patches on the gradient of a Lagrange space. The python type -preconditioner :class:`~.HiptmairPC` automatically sets up an additive two-level method +preconditioner :class:`HiptmairPC ` automatically sets up an additive two-level method using the auxiliary Lagrange space in a multigrid hierarchy. Therefore, the overall multigrid relaxation composes the edge patches with the auxiliary space relaxation. For the latter, the residual on each level is restricted from the dual of H(curl) into the dual of H1 via the adjoint of the gradient, where a vertex patch relaxation is applied to obtain a correction that is prolonged from H1 into H(curl) via the gradient. :: diff --git a/demos/patch/hdiv_riesz_star.py.rst b/demos/patch/hdiv_riesz_star.py.rst index bbdcc55a52..a04aa415d9 100644 --- a/demos/patch/hdiv_riesz_star.py.rst +++ b/demos/patch/hdiv_riesz_star.py.rst @@ -7,10 +7,10 @@ and `Pablo Brubeck `_. Multigrid in H(div) and H(curl) also requires relaxation based on topological patches. Here, we demonstrate how to do this in the former case. -We start by importing firedrake and setting up a :func:`.MeshHierarchy` and the +We start by importing firedrake and setting up a :func:`MeshHierarchy ` and the exact solution and forcing data. Crucially, the meshes must have an overlapping parallel domain decomposition that supports the vertex star patches. This is set -via the ``distribution_parameters`` kwarg of the :func:`.Mesh` constructor. :: +via the ``distribution_parameters`` kwarg of the :func:`Mesh ` constructor. :: from firedrake import * @@ -41,7 +41,7 @@ impose homogeneous Dirichlet boundary conditions:: return solver.snes.getLinearSolveIterations() -Having done both :class:`~.ASMStarPC` and :class:`~.PatchPC` in other demos, here we simply opt for the former. +Having done both :class:`ASMStarPC ` and :class:`PatchPC ` in other demos, here we simply opt for the former. Arnold, Falk, and Winther show that either vertex (``construct_dim=0``) or edge patches (``construct_dim=1``) will be acceptable in three dimensions. :: diff --git a/demos/patch/poisson_mg_patches.py.rst b/demos/patch/poisson_mg_patches.py.rst index 9b6f713efc..551e17c0e0 100644 --- a/demos/patch/poisson_mg_patches.py.rst +++ b/demos/patch/poisson_mg_patches.py.rst @@ -20,10 +20,10 @@ degree-independent iteration counts. Here, all the degrees of freedom in the ce For many problems, point Jacobi is even worse, and patches are required even to get a convergent method. We refer the reader to other demos. -We start by importing firedrake and setting up a :func:`.MeshHierarchy` and the +We start by importing firedrake and setting up a :func:`MeshHierarchy ` and the exact solution and forcing data. Crucially, the meshes must have an overlapping parallel domain decomposition that supports the vertex star patches. This is set -via the ``distribution_parameters`` kwarg of the :func:`.Mesh` constructor. :: +via the ``distribution_parameters`` kwarg of the :func:`Mesh ` constructor. :: from firedrake import * @@ -88,8 +88,8 @@ degree increases. :: jacobi_relax = mg_params({"pc_type": "jacobi"}, mat_type="matfree") -These options specify an additive Schwarz relaxation through :class:`~.PatchPC`. -:class:`~.PatchPC` builds the patch operators by assembling the bilinear form over +These options specify an additive Schwarz relaxation through :class:`PatchPC `. +:class:`PatchPC ` builds the patch operators by assembling the bilinear form over each subdomain. Hence, it does not require the global stiffness matrix to be assembled. These options tell the patch mechanism to use vertex star patches, storing @@ -113,7 +113,7 @@ in dense format. :: "sub_pc_type": "lu"}}, mat_type="matfree") -:class:`~.ASMStarPC`, on the other hand, does no re-discretization, but extracts the +:class:`ASMStarPC `, on the other hand, does no re-discretization, but extracts the submatrices for each patch from the already-assembled global stiffness matrix. The `"tinyasm"` backend uses LAPACK to invert all the patch operators, which is ideal @@ -140,7 +140,7 @@ overhead costs of calling the sparse factorization library many times. :: Now, for each parameter choice, we report the iteration count for the Poisson problem over a range of polynomial degrees. We see that the Jacobi relaxation leads to growth -in iteration count, while both :class:`~.PatchPC` and :class:`~.ASMStarPC` do not. Mathematically, the two +in iteration count, while both :class:`PatchPC ` and :class:`ASMStarPC ` do not. Mathematically, the two latter options do the same operations, just via different code paths. :: names = {"Jacobi": jacobi_relax, @@ -170,7 +170,7 @@ For Jacobi, we expect output such as 7 19 ======== ================ -While for either :class:`~.PatchPC` or :class:`~.ASMStarPC` (with dense inversion or with coloring + sparse factorization), we expect +While for either :class:`PatchPC ` or :class:`ASMStarPC ` (with dense inversion or with coloring + sparse factorization), we expect ======== ================ Degree Iterations diff --git a/demos/patch/stokes_vanka_patches.py.rst b/demos/patch/stokes_vanka_patches.py.rst index caf1188fcc..ab3b4344ef 100644 --- a/demos/patch/stokes_vanka_patches.py.rst +++ b/demos/patch/stokes_vanka_patches.py.rst @@ -14,14 +14,14 @@ of the patch but not pressures. :align: center In practice, we arrive at mesh-independent multigrid convergence using these relaxation. -We can construct Vanka patches either through :class:`~.PatchPC`, in which the bilinear form -is assembled on each vertex patch, or through :class:`~.ASMVankaPC`, in which the patch +We can construct Vanka patches either through :class:`PatchPC `, in which the bilinear form +is assembled on each vertex patch, or through :class:`ASMVankaPC `, in which the patch operators are extracted from the globally assembled stiffness matrix. -We start by importing firedrake and setting up a :func:`.MeshHierarchy` and the +We start by importing firedrake and setting up a :func:`MeshHierarchy ` and the exact solution and forcing data. Crucially, the meshes must have an overlapping parallel domain decomposition that supports the Vanka patches. This is set -via the ``distribution_parameters`` kwarg of the :func:`.Mesh` constructor. :: +via the ``distribution_parameters`` kwarg of the :func:`Mesh ` constructor. :: from firedrake import * @@ -82,8 +82,8 @@ solver. :: } -These options specify an additive Schwarz relaxation through :class:`~.PatchPC`. -:class:`~.PatchPC` builds the patch operators by assembling the bilineary form over +These options specify an additive Schwarz relaxation through :class:`PatchPC `. +:class:`PatchPC ` builds the patch operators by assembling the bilineary form over each subdomain. Hence, it does not require the global stiffness matrix to be assembled. These are quite similar to the options used in :: @@ -103,7 +103,7 @@ matrix to be assembled. These are quite similar to the options used in "pc_patch_precompute_element_tensors": None}}, mat_type="matfree") -:class:`~.ASMStarPC`, on the other hand, does no re-discretization, but extracts the +:class:`ASMStarPC `, on the other hand, does no re-discretization, but extracts the patch operators for each patch from the already-assembled global stiffness matrix. :: asm_relax = mg_params( @@ -121,7 +121,7 @@ direct or Krylov method on each one. Now, for each parameter choice, we report the iteration count for the Poisson problem over a range of polynomial degrees. We see that the Jacobi relaxation leads to growth -in iteration count, while both :class:`~.PatchPC` and :class:`~.ASMStarPC` do not. Mathematically, the two +in iteration count, while both :class:`PatchPC ` and :class:`ASMStarPC ` do not. Mathematically, the two latter options do the same operations, just via different code paths. :: names = {"ASM Vanka": asm_relax, diff --git a/demos/quasigeostrophy_1layer/qg_1layer_wave.py.rst b/demos/quasigeostrophy_1layer/qg_1layer_wave.py.rst index cdcf471aea..a998d6f44f 100644 --- a/demos/quasigeostrophy_1layer/qg_1layer_wave.py.rst +++ b/demos/quasigeostrophy_1layer/qg_1layer_wave.py.rst @@ -128,7 +128,7 @@ Firedrake's ability to :doc:`interpolate UFL expressions <../interpolation>`. :: x = SpatialCoordinate(mesh) q0 = Function(Vdg).interpolate(0.1 * sin(x[0]) * sin(x[1])) -We define some :class:`~.Function`\s to store the fields:: +We define some :class:`function `\s to store the fields:: dq1 = Function(Vdg) # PV fields for different time steps qh = Function(Vdg) @@ -195,8 +195,8 @@ fill. :: "sub_pc_type": "ilu"}) To visualise the output of the simulation, we create a -:class:`~.vtk_output.VTKFile` object. To which we can store multiple -:class:`~.Function`\s. So that we can distinguish between them we will +:class:`VTKFile ` object. To which we can store multiple +:class:`function `\s. So that we can distinguish between them we will give them descriptive names. :: q0.rename("Potential vorticity") diff --git a/demos/reynolds_robust_navier_stokes_hdiv/reynolds_robust_navier_stokes_hdiv.py.rst b/demos/reynolds_robust_navier_stokes_hdiv/reynolds_robust_navier_stokes_hdiv.py.rst index d601ce8d6a..fad718bb85 100644 --- a/demos/reynolds_robust_navier_stokes_hdiv/reynolds_robust_navier_stokes_hdiv.py.rst +++ b/demos/reynolds_robust_navier_stokes_hdiv/reynolds_robust_navier_stokes_hdiv.py.rst @@ -323,7 +323,7 @@ The velocity block applies a full-cycle geometric multigrid preconditioner to the augmented Lagrangian. At each multigrid level, five steps of GMRES are applied, preconditioned by the additive Schwarz method with -vertex-star patches (:class:`~.ASMStarPC`). A star patch around a +vertex-star patches (:class:`ASMStarPC `). A star patch around a vertex consists of all cells sharing that vertex; these patches together stably partition the divergence-free subspace, ensuring that the smoother captures the kernel of :math:`\nabla \cdot` as required by diff --git a/demos/saddle_point_pc/saddle_point_systems.py.rst b/demos/saddle_point_pc/saddle_point_systems.py.rst index cc9117a9fd..b29e467e92 100644 --- a/demos/saddle_point_pc/saddle_point_systems.py.rst +++ b/demos/saddle_point_pc/saddle_point_systems.py.rst @@ -109,7 +109,7 @@ linear system, Firedrake allows specifying that the problem should be preconditioned with an operator different to the operator defining the problem to be solved. We will use this functionality in a number of cases later. The ``aP`` function will take one argument, the -:class:`~.FunctionSpace` defining the space, and return a bilinear +:class:`FunctionSpace ` defining the space, and return a bilinear form suitable for assembling as an operator. Obviously we only do so if ``aP`` is provided. :: @@ -118,7 +118,7 @@ if ``aP`` is provided. :: aP = aP(W) Now we have all the pieces to build our linear system. We will return a -:class:`~.LinearVariationalSolver` object from this function. It is here that +:class:`linear variational solver ` object from this function. It is here that we must specify whether we want a monolithic matrix or not, by setting the preconditioner matrix type in the solver parameters. :: @@ -147,7 +147,7 @@ To illustrate the problem, we first attempt to solve the problem on a sequence of finer and finer meshes preconditioning the problem with zero-fill incomplete LU factorisation. Configuration of the solver is carried out by providing appropriate parameters when constructing the -:class:`~.LinearVariationalSolver` object through the ``solver_parameters`` +:class:`linear variational solver ` object through the ``solver_parameters`` keyword argument which should be a :class:`dict` of parameters. These parameters are passed directly to PETSc_, and their form is described in more detail in :doc:`/solving-interface`. For this problem, we use @@ -449,7 +449,7 @@ we then use to solve the problem, we can provide one ourselves. Recall that :math:`S` is spectrally a Laplacian only in a discontinuous space. A natural choice is therefore to use an interior penalty DG formulation for the Laplacian term on the block of the scalar -variable. We can provide it as an :class:`~.AuxiliaryOperatorPC` via a python preconditioner. Note that the ```form``` method in ```AuxiliaryOperatorPC``` takes the test functions as the first argument and the trial functions as the second argument, which is the reverse of the usual convention. :: +variable. We can provide it as an :class:`AuxiliaryOperatorPC ` via a python preconditioner. Note that the ```form``` method in ```AuxiliaryOperatorPC``` takes the test functions as the first argument and the trial functions as the second argument, which is the reverse of the usual convention. :: class DGLaplacian(AuxiliaryOperatorPC): def form(self, pc, v, u): diff --git a/demos/submesh_reaction_diffusion/submesh_reaction_diffusion.py.rst b/demos/submesh_reaction_diffusion/submesh_reaction_diffusion.py.rst index d8004146ac..c45f1cd0ee 100644 --- a/demos/submesh_reaction_diffusion/submesh_reaction_diffusion.py.rst +++ b/demos/submesh_reaction_diffusion/submesh_reaction_diffusion.py.rst @@ -5,7 +5,7 @@ Coupled volume-surface reaction-diffusion on a torus with submesh Many problems couple PDEs posed in the volume with other PDEs on the surface. This demo illustrates how such problems may be solved with - the :func:`~.Submesh` functionality in Firedrake. + the :func:`Submesh ` functionality in Firedrake. The demo was contributed by `Patrick Farrell `__. @@ -115,12 +115,12 @@ Mesh hierarchy and submesh hierarchy ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The submesh for the surface can be built from -either the :func:`~.Submesh` or :func:`~.SubmeshHierarchy` constructors, +either the :func:`Submesh ` or :func:`SubmeshHierarchy ` constructors, but only the latter enables us to use a multigrid solver. Geometric multigrid requires a hierarchy of uniformly refined meshes. We build the volume and surface hierarchies together. -Like :class:`~.DirichletBC`, :func:`~.Submesh` +Like :class:`DirichletBC `, :func:`Submesh ` takes in a subdomain id to indicate which part of the mesh should be extracted. In this case we want the entire exterior facet mesh, which we can specify directly. :: @@ -135,7 +135,7 @@ Function spaces ~~~~~~~~~~~~~~~ We use continuous piecewise-linear elements on both the volume and the surface, -collected into a :func:`~.MixedFunctionSpace`. :: +collected into a :func:`MixedFunctionSpace `. :: V_v = FunctionSpace(mesh_v, "CG", 1) V_s = FunctionSpace(mesh_s, "CG", 1) diff --git a/demos/vlasov_poisson_1d/vp1d.py.rst b/demos/vlasov_poisson_1d/vp1d.py.rst index be950f2ac3..1aed6d42ce 100644 --- a/demos/vlasov_poisson_1d/vp1d.py.rst +++ b/demos/vlasov_poisson_1d/vp1d.py.rst @@ -177,7 +177,7 @@ specified through the ``vfamily``. :: Wbar = FunctionSpace(mesh, 'CG', 1, vfamily='R', vdegree=0) -We create a :class:`~.Function` to store the solution at the current +We create a :class:`function ` to store the solution at the current time, and then set its initial condition, .. math:: @@ -198,16 +198,16 @@ equation. :: One = Function(V).assign(1.0) fbar = assemble(fn*dx)/assemble(One*dx) -We create a :class:`~.Function` to store the electrostatic potential. :: +We create a :class:`function ` to store the electrostatic potential. :: phi = Function(Wbar, name="potential") The next task is to create the solver for the electrostatic potential, which will be called every timestep. -We create a :class:`~.Function` to store the intermediate densities at each +We create a :class:`function ` to store the intermediate densities at each Runge-Kutta stage. The right hand side of the Poisson equation will be -evaluated using this :class:`~.Function` to obtain the potential at each +evaluated using this :class:`function ` to obtain the potential at each stage. Defining this beforehand will enable us to reuse the solver. :: fstar = Function(V) @@ -235,12 +235,12 @@ will be non-singular and so solvable with direct methods. :: shift_eqn = dphi.dx(0)*psi.dx(0)*dx + dphi*psi*dx -We use these to define a :class:`~.LinearVariationalProblem`. :: +We use these to define a :class:`LinearVariationalProblem `. :: phi_problem = LinearVariationalProblem(lhs(phi_eqn), rhs(phi_eqn), phi, aP=shift_eqn) -Now we build the :class:`~.LinearVariationalSolver`. The problem +Now we build the :class:`linear variational solver `. The problem is preconditioned by the shifted operator which is solved using a direct solver, and we pass the nullspace of globally constant functions to the solver. :: @@ -304,7 +304,7 @@ parameters. :: dt = T/nsteps dtc.assign(dt) -We set up some :class:`~.Function`\s to store Runge-Kutta stage variables. :: +We set up some :class:`function `\s to store Runge-Kutta stage variables. :: f1 = Function(V) f2 = Function(V) diff --git a/docs/source/adjoint.rst b/docs/source/adjoint.rst index f0336af964..36c426a534 100644 --- a/docs/source/adjoint.rst +++ b/docs/source/adjoint.rst @@ -307,7 +307,7 @@ The numbered blocks in the tape visualisation are as follows: 6. The result of step 5 is added to step 3 resulting in the functional value. The oval variables with labels of the form `w_n` are of type Firedrake -:class:`~.function.Function` while the variables labelled with numbers +:class:`Function ` while the variables labelled with numbers are annotated scalars of type :class:`~pyadjoint.AdjFloat`. Visualising the tape makes it possible to verify that the computational @@ -415,7 +415,7 @@ Overloaded types Data types that are recorded on the tape, and hence that can be used as functional values or controls, are those that inherit from :class:`pyadjoint.OverloadedType`. In firedrake, the key such types are -:class:`~.function.Function`, :class:`~.cofunction.Cofunction` and the annotated float type +:class:`Function `, :class:`Cofunction ` and the annotated float type :class:`pyadjoint.AdjFloat`. Firedrake users do not usually need to concern themselves with this since annotated operations will return overloaded types. diff --git a/docs/source/boundary_conditions.rst b/docs/source/boundary_conditions.rst index ca6e643b66..f8525bf4da 100644 --- a/docs/source/boundary_conditions.rst +++ b/docs/source/boundary_conditions.rst @@ -8,7 +8,7 @@ Dirichlet boundary conditions ============================= Strong Dirichlet boundary conditions are imposed by providing a list -of :class:`~.DirichletBC` objects. The class +of :class:`DirichletBC ` objects. The class documentation provides the syntax, this document explains the mathematical formulation of the boundary conditions in Firedrake, and their implementation. @@ -249,7 +249,7 @@ systems, a single step of Newton is employed. In the following we will use ``F`` for the residual :class:`~ufl.form.Form` and ``J`` for the Jacobian :class:`~ufl.form.Form`. In both cases these forms do not include the Dirichlet boundary conditions. Additionally -``u`` will be the solution :class:`~.Function`. +``u`` will be the solution :class:`function `. Strong boundary conditions are applied as follows: @@ -285,7 +285,7 @@ solved with boundary conditions as follows: 1. When the user calls ``assemble(a)`` to assemble the bilinear form ``a``, no actual assembly takes place. Instead, Firedrake returns a - :class:`~.Matrix` object that records the fact that it is + :class:`Matrix ` object that records the fact that it is intended to be assembled from ``a``. 2. At the :func:`~firedrake.solving.solve` call, Firedrake determines @@ -296,7 +296,7 @@ solved with boundary conditions as follows: boundary conditions applied when :func:`~firedrake.assemble.assemble` was called on A are used, as are any boundary conditions subsequently added with - :meth:`~.DirichletBC.apply`. + :meth:`firedrake.DirichletBC.apply`. 3. In the linear system case, the Jacobian :class:`~ufl.form.Form` is ``a``. Using this and the boundary conditions, Firedrake assembles @@ -307,6 +307,6 @@ solved with boundary conditions as follows: (J^{00} + J^{\Gamma\Gamma})\hat{\mathrm{U}} = \mathrm{F}(u) - J^{\Gamma0}\hat{\mathrm{U}}^\Gamma 4. The matrix assembled is then stored in the - :class:`~.Matrix` so that reassembly is avoided if the + :class:`Matrix ` so that reassembly is avoided if the matrix is used in another :func:`~firedrake.solving.solve` call with the same boundary conditions. diff --git a/docs/source/checkpointing.rst b/docs/source/checkpointing.rst index 21aacd51e3..b64b311e22 100644 --- a/docs/source/checkpointing.rst +++ b/docs/source/checkpointing.rst @@ -14,13 +14,13 @@ pausing, and subsequently resuming, a simulation at a later time. Checkpointing with CheckpointFile ================================= -:class:`~.CheckpointFile` class facilitates saving/loading meshes and -:class:`~.Function` s to/from an HDF5_ file. -The implementation is scalable in that :class:`~.Function` s are +:class:`firedrake.CheckpointFile` class facilitates saving/loading meshes and +:class:`function ` s to/from an HDF5_ file. +The implementation is scalable in that :class:`function ` s are saved to and loaded from the file entirely in parallel without needing to pass through a single process. It also supports flexible checkpointing, where one can save meshes and -:class:`~.Function` s on :math:`N` processes and later load them on +:class:`function ` s on :math:`N` processes and later load them on :math:`P` processes. If :math:`P == N`, the parallel distribution and entity permutation (reordering) of the saved mesh is recovered on the loaded mesh by default. @@ -32,7 +32,7 @@ automatically generated by Firedrake. If the mesh has a non-standard distribution, e.g., generated by a partitioner with some non-standard parameters, it is recommended that the user set the distribution name explicitly when constructing a mesh; - see, e.g., :py:func:`~.Mesh`. + see, e.g., :py:func:`firedrake.Mesh`. .. warning:: @@ -49,7 +49,7 @@ automatically generated by Firedrake. Saving ------ -In the following example we save in "example.h5" file two :class:`~.Function` s, +In the following example we save in "example.h5" file two :class:`function ` s, along with the mesh on which they are defined. .. code-block:: python3 @@ -73,7 +73,7 @@ each mesh. Inspecting saved data --------------------- -Now "example.h5" file has been created and the mesh and :class:`~.Function` +Now "example.h5" file has been created and the mesh and :class:`function ` data have been saved. One can view the contents of the HDF5 file with "h5dump" utility shipped with the HDF5 installation; "h5dump -n example.h5", for instance, shows: @@ -167,7 +167,7 @@ the HDF5 installation; "h5dump -n example.h5", for instance, shows: Loading ------- -We can load the mesh and :class:`~.Function` s in "example.h5" as in the +We can load the mesh and :class:`function ` s in "example.h5" as in the following. .. code-block:: python3 @@ -177,7 +177,7 @@ following. f = afile.load_function(mesh, "f") g = afile.load_function(mesh, "g") -Note that one needs to load the mesh before loading the :class:`~.Function` s +Note that one needs to load the mesh before loading the :class:`function ` s that are defined on it. If the default mesh name, :data:`~.DEFAULT_MESH_NAME`, was used when saving, the mesh name can be ommitted when loading. @@ -205,7 +205,7 @@ name postfixed by "_extruded" is given to the extruded mesh. Timestepping ------------ -The following demonstrates how a :class:`~.Function` can be saved and loaded +The following demonstrates how a :class:`function ` can be saved and loaded at each timestep in a time-series simulation by setting the `idx` parameter: .. code-block:: python3 @@ -224,9 +224,9 @@ at each timestep in a time-series simulation by setting the `idx` parameter: for i in range(4): f = afile.load_function(mesh, "f", idx=i) -Note that each :class:`~.Function` can either be saved in the timestepping mode +Note that each :class:`function ` can either be saved in the timestepping mode with `idx` parameter always set or in the normal mode (non-timestepping mode) -with `idx` parameter always unset, and the same :class:`~.Function` can only be +with `idx` parameter always unset, and the same :class:`function ` can only be loaded using the same mode. @@ -368,12 +368,12 @@ Checkpointing with DumbCheckpoint .. warning:: - :class:`~.DumbCheckpoint` is deprecated and will be removed soon. - Users are encouraged to use :class:`~.CheckpointFile`, which is more + :class:`firedrake.DumbCheckpoint` is deprecated and will be removed soon. + Users are encouraged to use :class:`firedrake.CheckpointFile`, which is more robust and scalable. -The support for :class:`~.DumbCheckpoint` is somewhat limited. One may -only store :class:`~.Function`\s in the checkpoint object. Moreover, +The support for :class:`firedrake.DumbCheckpoint` is somewhat limited. One may +only store :class:`function `\s in the checkpoint object. Moreover, no remapping of data is performed. This means that resuming the checkpoint is only possible on the same number of processes as used to create the checkpoint file. Additionally, the *same* ``Mesh`` @@ -384,7 +384,7 @@ mesh used to generate the saved checkpoint state. Opening a checkpoint -------------------- -A checkpoint file is created using the :class:`~.DumbCheckpoint` +A checkpoint file is created using the :class:`firedrake.DumbCheckpoint` constructor. We pass a filename argument, and an access mode. Available modes are: @@ -418,12 +418,12 @@ appended automatically. Storing data ------------ -Once a checkpoint file is opened, :class:`~.Function` data can be +Once a checkpoint file is opened, :class:`function ` data can be stored in the checkpoint using :meth:`~.DumbCheckpoint.store`. -A :class:`~.Function` is referenced in the checkpoint file by its +A :class:`function ` is referenced in the checkpoint file by its ``Function.name``, but this may be overridden by explicitly passing an optional `name` argument. For example, to store a -:class:`~.Function` using its default name use: +:class:`function ` using its default name use: .. code-block:: python3 @@ -438,10 +438,10 @@ If instead we want to override the name we use: .. warning:: - No warning is provided when storing multiple :class:`~.Function`\s + No warning is provided when storing multiple :class:`function `\s with the same name, existing values are overwritten. - Moreover, attempting to store a :class:`~.Function` with a + Moreover, attempting to store a :class:`function ` with a different number of degrees of freedom into an existing name will cause an error. @@ -449,14 +449,14 @@ Loading data ------------ Once a checkpoint is created, we can use it to load saved state into -:class:`~.Function`\s to resume a simulation. To load data into a -:class:`~.Function` from a checkpoint, we pass it to +:class:`function `\s to resume a simulation. To load data into a +:class:`function ` from a checkpoint, we pass it to :meth:`~.DumbCheckpoint.load`. As before, the data is looked up by its ``Function.name``, although once again this may be overridden by optionally specifying the ``name`` as an argument. For example, assume we had previously saved a checkpoint containing -two different :class:`~.Function`\s with names ``"A"`` and +two different :class:`function `\s with names ``"A"`` and ``"B"``. We can load these as follows: .. code-block:: python3 @@ -475,7 +475,7 @@ two different :class:`~.Function`\s with names ``"A"`` and .. note:: - :class:`~.DumbCheckpoint` does not support reading data on a different + :class:`firedrake.DumbCheckpoint` does not support reading data on a different number of processes from that used to write it. An attribute records the number of processes, and opening the checkpoint for reading raises an error if it does not match the current number of processes. @@ -506,8 +506,8 @@ the object goes out of scope. To use this approach, we use the python Writing attributes ------------------ -In addition to storing :class:`~.Function` data, it is also possible -to store metadata in :class:`~.DumbCheckpoint` files using HDF5 +In addition to storing :class:`function ` data, it is also possible +to store metadata in :class:`firedrake.DumbCheckpoint` files using HDF5 attributes. This is carried out using h5py_ to manipulate the file. The interface allows setting attribute values, reading them, and checking if a file has a particular attribute: @@ -535,11 +535,11 @@ The checkpoint object supports multiple timesteps in the same on-disk file. The primary interface to this is via :meth:`~.DumbCheckpoint.set_timestep`. If never called on a checkpoint file, no timestep support is enabled, and storing a -:class:`~.Function` with the same name as an existing object +:class:`function ` with the same name as an existing object overwrites it (data is stored in the HDF5 group ``"/fields"``). If one wishes to store multiple timesteps, one should call :meth:`~.DumbCheckpoint.set_timestep`, providing the timestep value -(and optionally a timestep "index"). Storing a :class:`~.Function` +(and optionally a timestep "index"). Storing a :class:`function ` will now write to the group ``"/fields/IDX"``. To store the same function at a different time level, we just call :meth:`~.DumbCheckpoint.set_timestep` again with a new timestep @@ -561,12 +561,12 @@ Support for multiple on-disk files ---------------------------------- For large simulations, it may not be expedient to store all timesteps -in the same on-disk file. To this end, the :class:`~.DumbCheckpoint` +in the same on-disk file. To this end, the :class:`firedrake.DumbCheckpoint` object offers the facility to retain the same checkpoint object, but change the on-disk file used to store the data. To switch to a new on-disk file one uses :meth:`~.DumbCheckpoint.new_file`. There are two method of choosing the new file name. If the -:class:`~.DumbCheckpoint` object was created passing +:class:`firedrake.DumbCheckpoint` object was created passing ``single_file=False`` then calling :meth:`~.DumbCheckpoint.new_file` without any additional arguments will use an internal counter to create file names by appending this counter to the provided base diff --git a/docs/source/citing.rst b/docs/source/citing.rst index 58f5eb659e..f4c72f1d76 100644 --- a/docs/source/citing.rst +++ b/docs/source/citing.rst @@ -41,7 +41,7 @@ For Firedrake itself, please cite :cite:`FiredrakeUserManual`. If you use the :doc:`extruded mesh ` functionality please cite :cite:`McRae2016` and :cite:`Bercea2016`. When using quadrilateral meshes, please cite :cite:`Homolya2016` and :cite:`McRae2016`. If you use -:py:func:`~.VertexOnlyMesh`, please cite :cite:`nixonhill2023consistent`. +:py:func:`firedrake.VertexOnlyMesh`, please cite :cite:`nixonhill2023consistent`. If you use the interfaces to couple Firedrake and machine learning frameworks such as PyTorch or JAX, please cite :cite:`Bouziani2024`. If you use the :py:class:`AbstractExternalOperator ` diff --git a/docs/source/duals.rst b/docs/source/duals.rst index 453af77406..8c393d8b8b 100644 --- a/docs/source/duals.rst +++ b/docs/source/duals.rst @@ -57,7 +57,7 @@ For an arbitrary :py:class:`~.ufl.FunctionSpace`, ``V``, the corresponding dual V = FunctionSpace(mesh, "CG", 1) V_star = V.dual() -A :py:class:`~.ufl.Coefficient` defines a *known* function ``c`` in ``V``. A :py:class:`~.Function` is a subclass of :py:class:`~.ufl.Coefficient`. +A :py:class:`~.ufl.Coefficient` defines a *known* function ``c`` in ``V``. A :py:class:`function ` is a subclass of :py:class:`~.ufl.Coefficient`. Consequently, .. code-block:: python3 @@ -68,7 +68,7 @@ Consequently, is a symbolic expression for the integral of ``c`` over the domain and represents a scalar value. ``f_0`` is a Python object of type :py:class:`~.ufl.Form`, once assembled, it is a scalar object. -Conversely, :py:class:`~.Argument` defines a placeholder symbol ``a`` for an *unknown* function in ``V``. :py:class:`~firedrake.ufl_expr.TestFunction` and :py:class:`~firedrake.ufl_expr.TrialFunction` are syntactic sugar for ``Argument(V, 0)`` and ``Argument(V, 1)`` respectively. +Conversely, :py:class:`firedrake.Argument` defines a placeholder symbol ``a`` for an *unknown* function in ``V``. :py:class:`~firedrake.ufl_expr.TestFunction` and :py:class:`~firedrake.ufl_expr.TrialFunction` are syntactic sugar for ``Argument(V, 0)`` and ``Argument(V, 1)`` respectively. .. code-block:: python3 @@ -100,7 +100,7 @@ Furthermore, we will want to express unknown objects in the dual space. For exam Using the reflexivity of the function space :math:`U`. This form therefore has two arguments, one in the primal space :math:`V` and one in the dual space :math:`U^*`. Therefore, we need to represent *arguments* in the dual space - we will call these *coarguments*. The details of interpolation will be discussed in :ref:`its own section `. -A :py:class:`~.Coargument` can be constructed by either calling :py:class:`~.ufl.Argument` on a dual space object or calling :py:class:`~.Coargument` on a dual space. +A :py:class:`firedrake.Coargument` can be constructed by either calling :py:class:`~.ufl.Argument` on a dual space object or calling :py:class:`firedrake.Coargument` on a dual space. .. code-block:: @@ -109,7 +109,7 @@ A :py:class:`~.Coargument` can be constructed by either calling :py:class:`~.ufl w = Coargument(V.dual(), 3) # type Coargument -There is a further dual-related type avalilable in UFL. In :py:class:`~.ufl.Cofunction`, we have represented an assembled 1-form. However, commonly we also assemble 2-forms. :py:class:`~.Matrix` allows an analogous use, and assembled 2-forms can be naturally combined with 2-forms that have not yet been assembled: +There is a further dual-related type avalilable in UFL. In :py:class:`~.ufl.Cofunction`, we have represented an assembled 1-form. However, commonly we also assemble 2-forms. :py:class:`Matrix ` allows an analogous use, and assembled 2-forms can be naturally combined with 2-forms that have not yet been assembled: .. code-block:: @@ -158,5 +158,5 @@ In summary, this table describes the dual types corresponding to primal finite e - :py:class:`~.ufl.classes.DualSpace` * - :py:class:`~.ufl.Coefficient` - :py:class:`~.ufl.Cofunction` - * - :py:class:`~.Argument` - - :py:class:`~.Coargument` \ No newline at end of file + * - :py:class:`firedrake.Argument` + - :py:class:`firedrake.Coargument` \ No newline at end of file diff --git a/docs/source/ensemble_parallelism.rst b/docs/source/ensemble_parallelism.rst index 4517caf884..a53a67ac9d 100644 --- a/docs/source/ensemble_parallelism.rst +++ b/docs/source/ensemble_parallelism.rst @@ -34,11 +34,11 @@ Cartesian product over the original global communicator. each of which is executed in parallel over 5 processors. The additional functionality required to support ensemble parallelism -is the ability to send instances of :class:`~.Function` from one -ensemble to another. This is handled by the :class:`~.Ensemble` class. +is the ability to send instances of :class:`function ` from one +ensemble to another. This is handled by the :class:`firedrake.Ensemble` class. Each ensemble member must have the same spatial parallel domain decomposition, so -instantiating an :class:`~.Ensemble` requires a communicator to split +instantiating an :class:`firedrake.Ensemble` requires a communicator to split (usually, but not necessarily, ``MPI_COMM_WORLD``) plus the number of MPI processes to be used in each member of the ensemble (5 in the figure above, and 2 in the example code below). The number of ensemble @@ -58,7 +58,7 @@ raised if this is not the case. Then, the spatial sub-communicator ``Ensemble.comm`` must be passed to :func:`~.mesh.Mesh` (possibly via inbuilt mesh generators in :mod:`~.utility_meshes`), so that it will then be used by any -:func:`~.FunctionSpace` and :class:`~.Function` derived from the mesh. +:func:`function space ` and :class:`function ` derived from the mesh. .. literalinclude:: ../../tests/firedrake/ensemble/test_ensemble_manual.py :language: python3 @@ -78,7 +78,7 @@ The ensemble sub-communicator is then available through the attribute MPI communications across the spatial sub-communicator (i.e., within an ensemble member) are handled automatically by Firedrake, whilst MPI communications across the ensemble sub-communicator (i.e., between ensemble -members) are handled through methods of :class:`~.Ensemble`. Currently +members) are handled through methods of :class:`firedrake.Ensemble`. Currently send/recv, reductions and broadcasts are supported, as well as their non-blocking variants. The rank of the the ensemble member (``my_ensemble.ensemble_comm.rank``) @@ -105,37 +105,37 @@ can be accessed via the ``ensemble_rank`` and ``ensemble_size`` attributes. EnsembleFunction and EnsembleFunctionSpace ========================================== -A :class:`~.Function` is logically collective over a single spatial +A :class:`function ` is logically collective over a single spatial communicator ``Ensemble.comm``. However, for some applications we want -to treat multiple :class:`~.Function` instances on different ensemble +to treat multiple :class:`function ` instances on different ensemble members as a single collective object over the entire global communicator ``Ensemble.global_comm``. For example, in time-parallel -methods we may have a :class:`~.Function` for each timestep in a +methods we may have a :class:`function ` for each timestep in a timeseries, and each timestep may live on a separate ensemble member. In this case we want to treat the entire timeseries as a single object. -Firedrake implements this using :class:`~.EnsembleFunctionSpace` -and :class:`~.EnsembleFunction` (along with the dual objects -:class:`~.EnsembleDualSpace` and :class:`~.EnsembleCofunction`). -The :class:`~.EnsembleFunctionSpace` can be thought of as a mixed +Firedrake implements this using :class:`firedrake.EnsembleFunctionSpace` +and :class:`firedrake.EnsembleFunction` (along with the dual objects +:class:`firedrake.EnsembleDualSpace` and :class:`firedrake.EnsembleCofunction`). +The :class:`firedrake.EnsembleFunctionSpace` can be thought of as a mixed function space which is parallelised across the `components`, as opposed to just being parallelised in `space`, as would usually be the -case with :func:`~.FunctionSpace`. Each component of an -:class:`~.EnsembleFunctionSpace` is a Firedrake :func:`~.FunctionSpace` +case with :func:`function space `. Each component of an +:class:`firedrake.EnsembleFunctionSpace` is a Firedrake :func:`function space ` on a single spatial communicator. -To create an :class:`~.EnsembleFunctionSpace` you must provide an -:class:`~.Ensemble` and, on each spatial communicator, a list of -:func:`~.FunctionSpace` instances for the components on the local +To create an :class:`firedrake.EnsembleFunctionSpace` you must provide an +:class:`firedrake.Ensemble` and, on each spatial communicator, a list of +:func:`function space ` instances for the components on the local ``Ensemble.comm``. There can be a different number of local -:func:`~.FunctionSpace` on each ``Ensemble.comm``. In the example -below we create an :class:`~.EnsembleFunctionSpace` with two +:func:`function space ` on each ``Ensemble.comm``. In the example +below we create an :class:`firedrake.EnsembleFunctionSpace` with two components on the first ensemble member, and three components on every other ensemble member. Note that, unlike a -:func:`~.FunctionSpace`, a component of an -:class:`~.EnsembleFunctionSpace` may itself be a -:func:`~.MixedFunctionSpace`. +:func:`function space `, a component of an +:class:`firedrake.EnsembleFunctionSpace` may itself be a +:func:`MixedFunctionSpace `. .. literalinclude:: ../../tests/firedrake/ensemble/test_ensemble_manual.py :language: python3 @@ -143,19 +143,19 @@ every other ensemble member. Note that, unlike a :start-after: [test_ensemble_manual_example 5 >] :end-before: [test_ensemble_manual_example 5 <] -Analogously to accessing the components of a :func:`~.MixedFunctionSpace` -using ``subspaces``, the :func:`~.FunctionSpace` for each local component -of an :class:`~.EnsembleFunctionSpace` can be accessed via +Analogously to accessing the components of a :func:`MixedFunctionSpace ` +using ``subspaces``, the :func:`function space ` for each local component +of an :class:`firedrake.EnsembleFunctionSpace` can be accessed via ``EnsembleFunctionSpace.local_spaces``. Various other methods and -properties such as ``dual`` (to create an :class:`~.EnsembleDualSpace`) +properties such as ``dual`` (to create an :class:`firedrake.EnsembleDualSpace`) and ``nglobal_spaces`` (total number of components across all ranks) are also available. -An :class:`~.EnsembleFunction` and :class:`~.EnsembleCofunction` can be -created from the :class:`~.EnsembleFunctionSpace`. These have a ``subfunctions`` +An :class:`firedrake.EnsembleFunction` and :class:`firedrake.EnsembleCofunction` can be +created from the :class:`firedrake.EnsembleFunctionSpace`. These have a ``subfunctions`` property that can be used to access the components on the local ensemble member. Each element in ``EnsembleFunction.subfunctions`` is itself just a -normal Firedrake :class:`~.Function`. If a component of the +normal Firedrake :class:`function `. If a component of the ``EnsembleFunctionSpace`` is a ``MixedFunctionSpace``, then the corresponding component in ``EnsembleFunction.subfunctions`` will be a mixed ``Function`` in that ``MixedFunctionSpace``. @@ -166,20 +166,20 @@ that ``MixedFunctionSpace``. :start-after: [test_ensemble_manual_example 6 >] :end-before: [test_ensemble_manual_example 6 <] -:class:`~.EnsembleFunction` and :class:`~.EnsembleCofunction` have -a range of methods equivalent to those of :class:`~.Function` and -:class:`~.Cofunction`, such as ``assign``, ``zero``, +:class:`firedrake.EnsembleFunction` and :class:`firedrake.EnsembleCofunction` have +a range of methods equivalent to those of :class:`function ` and +:class:`Cofunction `, such as ``assign``, ``zero``, ``riesz_representation``, arithmetic operators e.g. ``+``, ``+=``, etc. These act component-wise on each local component. Because the components in ``EnsembleFunction.subfunctions`` -(``EnsembleCofunction.subfunctions``) are just :class:`~.Function` -(:class:`~.Cofunction`) instances, they can be used directly +(``EnsembleCofunction.subfunctions``) are just :class:`function ` +(:class:`Cofunction `) instances, they can be used directly with variational forms and solvers. In the example code below, -We create a :class:`~.LinearVariationalSolver` where the right -hand side is a component of an :class:`~.EnsembleCofunction`, +We create a :class:`linear variational solver ` where the right +hand side is a component of an :class:`firedrake.EnsembleCofunction`, and the solution is written into a component of an -:class:`~.EnsembleFunction`. Using the ``subfunctions`` +:class:`firedrake.EnsembleFunction`. Using the ``subfunctions`` directly like this can simplify ensemble code and reduce unnecessary copies. Note that the ``options_prefix`` is set using both the local ensemble @@ -201,11 +201,11 @@ on each ensemble member. ``EnsembleCofunction`` themselves do not carry any symbolic information so cannot be used in UFL expressions. -Internally, the :class:`~.EnsembleFunction` creates a ``PETSc.Vec`` +Internally, the :class:`firedrake.EnsembleFunction` creates a ``PETSc.Vec`` on the ``Ensemble.global_comm`` which contains the data for all local components on all ensemble members. This ``Vec`` can be accessed with a context manager, similarly to the ``Function.dat.vec`` context -managers used to access :class:`~.Function` data. There are also +managers used to access :class:`function ` data. There are also analogous ``vec_ro`` and ``vec_wo`` context managers for read/write only accesses. However note that, unlike the ``Function.dat.vec`` context managers, the ``EnsembleFunction.vec`` context managers diff --git a/docs/source/external_operators.rst b/docs/source/external_operators.rst index e0c1eecea3..5f7b5d0f87 100644 --- a/docs/source/external_operators.rst +++ b/docs/source/external_operators.rst @@ -50,7 +50,7 @@ for `u \in V`. For sake of simplicity, in what follows, we use `N` to denote bot and the operator `N`. Expressing external operators as linear forms facilitates their composition with variational forms of PDEs. Note that while `N` is linear with respect to `v^{*}`, its *argument*, it can be nonlinear with respect to `u`, its *operand*. In Firedrake, `u` would -be a :class:`~.Function` object, and `v^{*}` a :class:`~.Coargument` object. +be a :class:`function ` object, and `v^{*}` a :class:`firedrake.Coargument` object. Arbitrary UFL expressions defined on arbitrary finite element spaces, i.e. other than `V`, can also be passed as operands to the external operator using the symbolic :class:`~.Interpolate` operator. @@ -105,9 +105,9 @@ linear form on which they are applied. For example, let's consider the Jacobian \operatorname{action}\left(\frac{dN(u; \hat{u}, v^{*})}{du}, w\right) = \frac{dN(u; w, v^{*})}{du} \quad \forall w \in V where the external operator `\frac{dN(u; w, v^{*})}{du}` is the Jacobian action of `N` on `w`. -Hence, for a given :class:`~.Function` `w` in `V`, the external operator `\frac{dN(u; w, v^{*})}{du}` +Hence, for a given :class:`function ` `w` in `V`, the external operator `\frac{dN(u; w, v^{*})}{du}` is linear with respect to `w`, which is a known function in `V`, and `v^{*}`, which is an unknown -function in `V^{*}`, i.e. a :class:`~.Coargument` in `V^{*}`. Therefore, `\frac{dN(u; w, v^{*})}{du}` +function in `V^{*}`, i.e. a :class:`firedrake.Coargument` in `V^{*}`. Therefore, `\frac{dN(u; w, v^{*})}{du}` is a 1-form, i.e. it is a linear form with respect to one unknown argument. Similarly, the adjoint of the Jacobian of `N` can be written as: @@ -174,7 +174,7 @@ see :ref:`previous section `. Finally, the number of arguments of an external operator also determines the type of its output after being assembled. For instance, given that an external operator with one argument is a 1-form, its assembly -would result in a :class:`~.Function` or a :class:`~.Cofunction`. Similarly, an external operator +would result in a :class:`function ` or a :class:`Cofunction `. Similarly, an external operator with two arguments, i.e. a 2-form, would produce a :class:`~.MatrixBase` object. The following table illustrates an external operator `N` with two operands, `N \colon V \times V \times V^{*} \rightarrow \mathbb{R}`, along with the external operators @@ -213,7 +213,7 @@ and/or the arguments of the external operator. The external operator interface u users specifying which external operator implementation each method correspond to. More specifically, each evaluation method of the subclass needs to be decorated with the *assemble_method* decorator. This decorator takes in two arguments: `(i)` the derivative multi-index, and `(ii)` and a tuple containing the -arguments' numbers, wherein arguments that are not of type :class:`~.Argument` or :class:`~.Coargument` +arguments' numbers, wherein arguments that are not of type :class:`firedrake.Argument` or :class:`firedrake.Coargument` are denoted with `None`. For instance, the Jacobian of the previously introduced external operator `N(u, m; v^{*})` with @@ -236,9 +236,9 @@ derivative multi-index, but the arguments would be swapped. Hence, the specified @assemble_method((1, 0), (1, 0)) Likewise, if we take the action of the Hermitian transpose of the Jacobian matrix on a given -:class:`~.Cofunction`, the highest-numbered argument will be replaced by this cofunction. This implies that +:class:`Cofunction `, the highest-numbered argument will be replaced by this cofunction. This implies that the highest number in the second tuple of the decorator will be replaced by *None* as cofunctions are -not :class:`~.Argument` or :class:`~.Coargument`, which results in: +not :class:`firedrake.Argument` or :class:`firedrake.Coargument`, which results in: .. code-block:: python3 @@ -303,10 +303,10 @@ Note that building an external operator for the above operation is, in practice, can already be readily implemented using Firedrake's built-in functionalities. Also, because this translation operation is fully defined in Firedrake, the evaluation methods of the external operator we will build rely on Firedrake code. However, the external operator evaluation methods can contain any Python -code as long as they return compatible objects, e.g. :class:`~.Function` or :class:`~.MatrixBase` objects. +code as long as they return compatible objects, e.g. :class:`function ` or :class:`~.MatrixBase` objects. `N` takes in two operands `f, u \in V` and one argument `v^{*} \in V^{*}`. When assembled, -this external operator returns a :class:`~.Function` in `V` since the linear form `N` can also +this external operator returns a :class:`function ` in `V` since the linear form `N` can also be seen as an operator mapping to `V`, as :ref:`previously discussed `. To construct `N`, we need to subclass the :class:`~.AbstractExternalOperator` class and specify how `N` can be assembled. Given that `N` has `(0,)` as derivative multi-index and that it only has one argument, @@ -417,7 +417,7 @@ In many cases, computing the Jacobian of the residual form is not appropriate, o Instead, one may want to use matrix-free methods to solve the PDE problem of interest. In that case, the Jacobian of `F` won't be assembled. Instead, only the action of the Jacobian will be used. As a consequence, our external operator subclass will need to be equipped with an implementation stating how -the action of the Jacobian of `N` on a given :class:`~.Function` `w` can be assembled, i.e. how to +the action of the Jacobian of `N` on a given :class:`function ` `w` can be assembled, i.e. how to compute `\frac{\partial N(u, f; w, v^{*})}{\partial u}`. In this case, this implementation should simply return `w` as the Jacobian is the identity matrix. @@ -443,7 +443,7 @@ return `w` as the Jacobian is the identity matrix. The arguments of an external operator can be obtained via *.argument_slots()*. This will return all the arguments of the external operator, independently of whether they are -:class:`~.Argument`/ :class:`~.Coargument` or :class:`~.Function`/ :class:`~.Cofunction`. If you only want +:class:`firedrake.Argument`/ :class:`firedrake.Coargument` or :class:`function `/ :class:`Cofunction `. If you only want the unknown arguments, for example to determine the arity of the external operator, you can instead use *.arguments()*. We can now solve the variational problem using any matrix-free method: diff --git a/docs/source/extruded-meshes.rst b/docs/source/extruded-meshes.rst index b37532577c..1ac15be1c1 100644 --- a/docs/source/extruded-meshes.rst +++ b/docs/source/extruded-meshes.rst @@ -55,10 +55,10 @@ the performance should approach that of a fully structured mesh. Generating Extruded Meshes in Firedrake --------------------------------------- -Extruded meshes are built using :py:func:`~.ExtrudedMesh`. There +Extruded meshes are built using :py:func:`ExtrudedMesh `. There are several built-in extrusion types that generate commonly-used extruded meshes. To create a more complicated extruded mesh, one can either pass a -hand-written kernel to :py:func:`~.ExtrudedMesh`, or one +hand-written kernel to :py:func:`ExtrudedMesh `, or one can use a built-in extrusion type and modify the coordinate field afterwards. The following information may be passed in to the constructor: @@ -288,7 +288,7 @@ For more details on the implementation, see Function Spaces on Extruded Meshes ---------------------------------- -The syntax for building a :py:class:`~.FunctionSpace` on an extruded mesh is +The syntax for building a :py:class:`FunctionSpace ` on an extruded mesh is an extension of the existing syntax used with normal meshes. On a non-extruded mesh, the following syntax is used: diff --git a/docs/source/interpolation.rst b/docs/source/interpolation.rst index 66eeb59d83..5be151810d 100644 --- a/docs/source/interpolation.rst +++ b/docs/source/interpolation.rst @@ -8,11 +8,11 @@ Interpolation ============= Firedrake offers highly flexible capabilities for interpolating expressions -(functions of space) into finite element :py:class:`~.Function`\s. +(functions of space) into finite element :py:class:`function `\s. Interpolation is often used to set up initial conditions and/or boundary conditions. Mathematically, if :math:`e(x)` is a function of space and :math:`V` is a finite element function space then -:math:`\operatorname{interpolate}(e, V)` is the :py:class:`~.Function` +:math:`\operatorname{interpolate}(e, V)` is the :py:class:`function ` :math:`v_i \phi_i\in V` such that: .. math:: @@ -50,7 +50,7 @@ Here, the :py:func:`~.interpolate` function returned a **symbolic** UFL_ :py:cla expression. To calculate a concrete numerical result, we need to call :py:func:`~firedrake.assemble.assemble` on this expression. It is also possible to interpolate an expression directly into an existing -:py:class:`~.Function`: +:py:class:`function `: .. literalinclude:: ../../tests/firedrake/regression/test_interpolation_manual.py :language: python3 @@ -77,8 +77,8 @@ including: * The coordinates: in physical space as :py:class:`~ufl.SpatialCoordinate`, and in reference space as :py:class:`ufl.geometry.CellCoordinate`. -* Firedrake :py:class:`~.Function`\s, derivatives of - :py:class:`~.Function`\s, and :py:class:`~.Constant`\s. +* Firedrake :py:class:`function `\s, derivatives of + :py:class:`function `\s, and :py:class:`constant `\s. * Literal numbers, basic arithmetic operations, and also mathematical functions such as ``sin``, ``cos``, ``sqrt``, ``abs``, etc. * Conditional expressions using UFL :py:mod:`~ufl.conditional`. @@ -153,10 +153,10 @@ assemble this matrix by doing :start-after: [test_interpolate_operator 11] :end-before: [test_interpolate_operator 12] -Passing a :py:class:`~.FunctionSpace` into the dual slot of :py:func:`~.interpolate` is +Passing a :py:class:`FunctionSpace ` into the dual slot of :py:func:`~.interpolate` is syntactic sugar for ``TestFunction(V.dual())``. -If :math:`g\in U` is a :py:class:`~.Function`, then we can write it as :math:`g = g_j \psi_j` for +If :math:`g\in U` is a :py:class:`function `, then we can write it as :math:`g = g_j \psi_j` for some coefficients :math:`g_j`. Interpolating :math:`g` into :math:`V` gives .. math:: @@ -172,11 +172,11 @@ coefficients of the interpolated function. In Firedrake, we can do this by :start-after: [test_interpolate_operator 12] :end-before: [test_interpolate_operator 13] -:math:`h` is a :py:class:`~.Function` in :math:`V` representing the interpolation of :math:`g` into :math:`V`. +:math:`h` is a :py:class:`function ` in :math:`V` representing the interpolation of :math:`g` into :math:`V`. .. note:: - When interpolating a :py:class:`~.Function` directly, for example + When interpolating a :py:class:`function ` directly, for example .. code-block:: python3 @@ -193,7 +193,7 @@ The adjoint of the interpolation operator is defined as \mathcal{I}_{V}^{*} : V^{*} \to U^{*}. -This operator interpolates :py:class:`~.Cofunction`\s in the dual space :math:`V^{*}` into +This operator interpolates :py:class:`Cofunction `\s in the dual space :math:`V^{*}` into the dual space :math:`U^{*}`. The associated form is .. math:: @@ -217,7 +217,7 @@ The second way is to use UFL_'s :py:func:`~ufl.adjoint` operator, which takes a :start-after: [test_interpolate_operator 15] :end-before: [test_interpolate_operator 16] -If :math:`g^*` is a :py:class:`~.Cofunction` in :math:`V^{*}` then we can interpolate it into :math:`U^{*}` by doing +If :math:`g^*` is a :py:class:`Cofunction ` in :math:`V^{*}` then we can interpolate it into :math:`U^{*}` by doing .. math:: @@ -234,7 +234,7 @@ In Firedrake, we can do this by Again, Firedrake does not explicitly assemble the adjoint interpolation matrix, but performs the interpolation matrix-free. To perform the interpolation with the assembled adjoint interpolation operator, -we can take the :py:func:`~ufl.action` of the operator on the :py:class:`~.Cofunction`: +we can take the :py:func:`~ufl.action` of the operator on the :py:class:`Cofunction `: .. literalinclude:: ../../tests/firedrake/regression/test_interpolation_manual.py :language: python3 @@ -242,7 +242,7 @@ we can take the :py:func:`~ufl.action` of the operator on the :py:class:`~.Cofun :start-after: [test_interpolate_operator 17] :end-before: [test_interpolate_operator 18] -The final case is when we interpolate a :py:class:`~.Function` into :py:class:`~.Cofunction`: +The final case is when we interpolate a :py:class:`function ` into :py:class:`Cofunction `: .. literalinclude:: ../../tests/firedrake/regression/test_interpolation_manual.py :language: python3 @@ -349,7 +349,7 @@ coefficients which could not be set) are, by default, set to zero: :start-after: [test_cross_mesh 9] :end-before: [test_cross_mesh 10] -If we specify an output :py:class:`~.Function` then the missing DoFs are +If we specify an output :py:class:`function ` then the missing DoFs are unmodified. We can optionally specify a value to use for our missing DoFs. Here @@ -361,7 +361,7 @@ we set them to be ``nan`` ('not a number') for easy identification: :start-after: [test_cross_mesh 11] :end-before: [test_cross_mesh 12] -If we specify an output :py:class:`~.Function`, this overwrites the missing +If we specify an output :py:class:`function `, this overwrites the missing DoFs. If we don't set ``default_missing_val`` then any missing DoFs are left as @@ -379,7 +379,7 @@ they were prior to interpolation: :start-after: [test_cross_mesh 15] :end-before: [test_cross_mesh 16] -Similarly, using the :py:meth:`~.Function.interpolate` method on a :py:class:`~.Function` will not overwrite +Similarly, using the :py:meth:`~.Function.interpolate` method on a :py:class:`function ` will not overwrite the pre-existing values if ``default_missing_val`` is not set: .. literalinclude:: ../../tests/firedrake/regression/test_interpolation_manual.py @@ -394,7 +394,7 @@ Interpolation from external data -------------------------------- Unfortunately, UFL interpolation is not applicable if some of the -source data is not yet available as a Firedrake :py:class:`~.Function` +source data is not yet available as a Firedrake :py:class:`function ` or UFL expression. Here we describe a recipe for moving external data to Firedrake fields. @@ -403,7 +403,7 @@ input an :math:`n \times d` array, where :math:`n` is the number of points at which the data values are needed, and :math:`d` is the geometric dimension of the mesh. ``mydata(X)`` shall return a :math:`n` long vector of the scalar values evaluated at the points -provided. (Assuming that the target :py:class:`~.FunctionSpace` is +provided. (Assuming that the target :py:class:`FunctionSpace ` is scalar valued, although this recipe can be extended to vector or tensor valued fields.) Presumably ``mydata`` works by interpolating the external data source, but the precise details are not relevant diff --git a/docs/source/mesh-coordinates.rst b/docs/source/mesh-coordinates.rst index 450ed8be12..f43c4c2973 100644 --- a/docs/source/mesh-coordinates.rst +++ b/docs/source/mesh-coordinates.rst @@ -7,7 +7,7 @@ Changing mesh coordinates Users may want to change the coordinates of an existing mesh object for certain reasons. The coordinates can be accessed as a -:py:class:`~.Function` through ``mesh.coordinates`` where ``mesh`` is +:py:class:`function ` through ``mesh.coordinates`` where ``mesh`` is a mesh object. For example, .. code-block:: python3 @@ -43,7 +43,7 @@ Changing the coordinate function space For more complicated situations, one might wish to replace the mesh coordinates with a field which lives on a different -:py:class:`~.FunctionSpace` (e.g. higher-order meshes). +:py:class:`FunctionSpace ` (e.g. higher-order meshes). .. note:: @@ -64,9 +64,9 @@ mesh object from a field `f`: ``new_mesh`` has the same mesh topology as the original mesh, but its coordinate values and coordinate function space are from `f`. The coordinate function space must be a rank-1 -:py:class:`~.FunctionSpace`, constructed either with +:py:class:`FunctionSpace `, constructed either with :py:func:`~.VectorFunctionSpace`, or by providing a -:py:class:`~ufl.classes.VectorElement` to :py:func:`~.FunctionSpace`. For +:py:class:`~ufl.classes.VectorElement` to :py:func:`function space `. For efficiency, the new mesh object shares data with `f`. That is, changing the values of `f` will change the coordinate values of the mesh, and *vice versa*. If this behaviour is undesired, one should @@ -112,7 +112,7 @@ Replacing the mesh geometry of an existing function --------------------------------------------------- Creating a new mesh geometry object, as described above, leaves any -existing :py:class:`~.Function`\s untouched -- they continue to live +existing :py:class:`function `\s untouched -- they continue to live on their original mesh geometries. One may wish to move these functions over to the new mesh. To move `f` over to ``mesh``, use: @@ -121,7 +121,7 @@ functions over to the new mesh. To move `f` over to ``mesh``, use: g = Function(functionspaceimpl.WithGeometry(f.function_space(), mesh), val=f.topological) -This creates a :py:class:`~.Function` `g` which shares data with `f`, +This creates a :py:class:`function ` `g` which shares data with `f`, but its mesh geometry is ``mesh``. .. warning:: diff --git a/docs/source/optimising.rst b/docs/source/optimising.rst index 305a4889c6..d2901baa9f 100644 --- a/docs/source/optimising.rst +++ b/docs/source/optimising.rst @@ -158,8 +158,8 @@ repeated calls to :py:func:`~firedrake.solving.solve` will introduce some overhead. To get around this problem, users should instead instantiate -a variational problem (e.g. :py:class:`~.NonlinearVariationalProblem`) -and solver (e.g. :py:class:`~.NonlinearVariationalSolver`) outside of +a variational problem (e.g. :py:class:`NonlinearVariationalProblem `) +and solver (e.g. :py:class:`NonlinearVariationalSolver `) outside of the loop body. An example showing how this is done can be found in `this demo `_. diff --git a/docs/source/parallelism.rst b/docs/source/parallelism.rst index bc2528eba4..ac55358ef3 100644 --- a/docs/source/parallelism.rst +++ b/docs/source/parallelism.rst @@ -87,10 +87,10 @@ different simulations on the two halves we would write. .. note:: If you need to create Firedrake meshes on different communicators, - then usually the best approach is to use the :class:`~.Ensemble`, + then usually the best approach is to use the :class:`firedrake.Ensemble`, which manages splitting MPI communicators and communicating - :class:`~.Function` objects between the split communicators. More - information on using the :class:`~.Ensemble` can be found + :class:`function ` objects between the split communicators. More + information on using the :class:`firedrake.Ensemble` can be found :doc:`here `. To access the communicator a mesh was created on, we can use the diff --git a/docs/source/point-evaluation.rst b/docs/source/point-evaluation.rst index 7c27213966..70966531a9 100644 --- a/docs/source/point-evaluation.rst +++ b/docs/source/point-evaluation.rst @@ -5,7 +5,7 @@ Point evaluation ================ -Firedrake can evaluate :py:class:`~.Function`\s at arbitrary physical +Firedrake can evaluate :py:class:`function `\s at arbitrary physical points. This feature can be useful for the evaluation of the result of a simulation, or for creating expressions which contain point evaluations. Two APIs for this are offered: a Firedrake-specific one, and one from UFL. @@ -16,14 +16,14 @@ Primary API: Interpolation onto a vertex-only mesh -------------------------------------------------- Firedrake's principal API for evaluating functions at arbitrary points, -interpolation onto a :func:`~.VertexOnlyMesh`, is designed for evaluating a +interpolation onto a :func:`firedrake.VertexOnlyMesh`, is designed for evaluating a function at many points, or repeatedly, and for creating expressions which contain point evaluations. It is parallel-safe. Whilst :meth:`~.Function.at` produces a list of values, cross-mesh interpolation onto -:func:`~.VertexOnlyMesh` gives Firedrake :py:class:`~.Function`\s. +:func:`firedrake.VertexOnlyMesh` gives Firedrake :py:class:`function `\s. This is discussed in detail in :cite:`nixonhill2023consistent` but, briefly, -the idea is that the :func:`~.VertexOnlyMesh` is a mesh that represents a +the idea is that the :func:`firedrake.VertexOnlyMesh` is a mesh that represents a point cloud domain. Each cell of the mesh is a vertex at a chosen location in space. As usual for a mesh, we represent values by creating functions in function spaces on it. The only function space that makes sense for a mesh @@ -33,7 +33,7 @@ known as the Polynomial degree 0 Discontinuous Galerkin (P0DG) space. Our vertex-only meshes are immersed in some 'parent' mesh. We perform point evaluation of a function :math:`f` defined in a function space :math:`V` on the parent mesh by interpolating into the P0DG space on the -:func:`~.VertexOnlyMesh`. For example: +:func:`firedrake.VertexOnlyMesh`. For example: .. literalinclude:: ../../tests/firedrake/vertexonly/test_vertex_only_manual.py :language: python3 @@ -46,10 +46,10 @@ will print ``[0.02, 0.08, 0.18]`` when running in serial, the values of :math:`(0.3, 0.3)`. For details on viewing the outputs in parallel, see the :ref:`section on the input ordering property. ` -Note that ``f_at_points`` is a :py:class:`~.Function` which takes +Note that ``f_at_points`` is a :py:class:`function ` which takes on *all* the values of ``f`` evaluated at ``points``. The cell ordering of a -:func:`~.VertexOnlyMesh` follows the ordering of the list of points it is given -at construction. In general :func:`~.VertexOnlyMesh` accepts any numpy array of +:func:`firedrake.VertexOnlyMesh` follows the ordering of the list of points it is given +at construction. In general :func:`firedrake.VertexOnlyMesh` accepts any numpy array of shape ``(num_points, point_dim)`` (or equivalent list) as the set of points to create disconnected vertices at. @@ -85,7 +85,7 @@ for successful interpolation. Parallel behaviour ~~~~~~~~~~~~~~~~~~ -In parallel the ``points`` given to :func:`~.VertexOnlyMesh` are assumed to be +In parallel the ``points`` given to :func:`firedrake.VertexOnlyMesh` are assumed to be the same on each MPI process and are taken from rank 0. To let different ranks provide different points to the vertex-only mesh set the keyword argument ``redundant = False`` @@ -154,7 +154,7 @@ parent mesh and the points to evaluate at: point_evaluator = PointEvaluator(mesh, points) Internally, this creates a vertex-only mesh at the given points, immersed in the given mesh. -To evaluate a :py:class:`~.Function` defined on the parent mesh at the given points, +To evaluate a :py:class:`function ` defined on the parent mesh at the given points, we use :meth:`~.PointEvaluator.evaluate`: .. code-block:: python3 @@ -176,7 +176,7 @@ on different ranks, for example when using external point data. The parameters ``missing_points_behaviour`` and ``tolerance`` (discussed :ref:`here ` and :ref:`here ` respectively) can be set when creating the :py:class:`~.PointEvaluator` -and will be passed to the :func:`~.VertexOnlyMesh` it creates internally. +and will be passed to the :func:`firedrake.VertexOnlyMesh` it creates internally. If the :ref:`coordinates ` or the :ref:`tolerance ` of the parent mesh are changed after creating the :py:class:`~.PointEvaluator`, then the vertex-only mesh @@ -204,7 +204,7 @@ These equivalent expressions for point evaluation where :math:`N` is the number of points, :math:`x_i` is the :math:`i`\th point, :math:`\Omega` is a 'parent' mesh, :math:`f` is a function on that mesh, :math:`\delta` is a Dirac delta distribution can therefore be written in -Firedrake using :func:`~.VertexOnlyMesh` and :func:`~.interpolate` as +Firedrake using :func:`firedrake.VertexOnlyMesh` and :func:`~.interpolate` as .. literalinclude:: ../../tests/firedrake/vertexonly/test_vertex_only_manual.py :language: python3 @@ -223,8 +223,8 @@ Using the input ordering property ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Any set of points with associated data in our domain can be expressed as a -P0DG function on a :func:`~.VertexOnlyMesh`. The recommended way to import data -from an external source is via the :py:attr:`~.VertexOnlyMeshTopology.input_ordering` +P0DG function on a :func:`firedrake.VertexOnlyMesh`. The recommended way to import data +from an external source is via the :py:attr:`firedrake.VertexOnlyMeshTopology.input_ordering` property: this produces another vertex-only mesh which has points in the order and MPI rank that they were specified when first creating the original vertex-only mesh. For example: @@ -237,7 +237,7 @@ vertex-only mesh. For example: This is entirely parallel safe. -Similarly, we can use :py:attr:`~.VertexOnlyMeshTopology.input_ordering` to get data out +Similarly, we can use :py:attr:`firedrake.VertexOnlyMeshTopology.input_ordering` to get data out of a vertex-only mesh in a parallel-safe way. If we return to our example from :ref:`the section where we introduced vertex only meshes `, we had @@ -251,7 +251,7 @@ had In parallel, this will print the values of ``f`` at the given ``points`` list **after the points have been distributed over the parent mesh**. If we want the values of ``f`` at the ``points`` list **before the points have been -distributed** we can use :py:attr:`~.VertexOnlyMeshTopology.input_ordering` as follows: +distributed** we can use :py:attr:`firedrake.VertexOnlyMeshTopology.input_ordering` as follows: .. literalinclude:: ../../tests/firedrake/vertexonly/test_vertex_only_manual.py :language: python3 @@ -262,8 +262,8 @@ distributed** we can use :py:attr:`~.VertexOnlyMeshTopology.input_ordering` as f .. note:: When a vertex-only mesh is created with ``redundant = True`` (which is the - default when creating a :func:`~.VertexOnlyMesh`) the - :py:attr:`~.VertexOnlyMeshTopology.input_ordering` method will return a vertex-only + default when creating a :func:`firedrake.VertexOnlyMesh`) the + :py:attr:`firedrake.VertexOnlyMeshTopology.input_ordering` method will return a vertex-only mesh with all points on rank 0. If we ran the example in parallel, the above code would print @@ -287,7 +287,7 @@ a good idea to set the values to ``nan`` before the interpolation: More ways to interact with external data ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Aside from :py:attr:`~.VertexOnlyMeshTopology.input_ordering`, we can use +Aside from :py:attr:`firedrake.VertexOnlyMeshTopology.input_ordering`, we can use :func:`~.interpolate` to interact with external data to, for example, compare a PDE solution with the point data. The :math:`l_2` error norm (euclidean norm) of a function :math:`f` (which may be a PDE solution) @@ -307,7 +307,7 @@ We can express this in Firedrake as # or equivalently error = errornorm(interpolate(f, P0DG), y_pts) -We can then use the :py:attr:`~.VertexOnlyMeshTopology.input_ordering` vertex-only mesh +We can then use the :py:attr:`firedrake.VertexOnlyMeshTopology.input_ordering` vertex-only mesh to safely check the values of ``error`` at the points :math:`\{x_i\}_{i=0}^{N-1}`. diff --git a/docs/source/preconditioning.rst b/docs/source/preconditioning.rst index 4b4da32c07..f0eeb84b9e 100644 --- a/docs/source/preconditioning.rst +++ b/docs/source/preconditioning.rst @@ -73,7 +73,7 @@ multiplicatively within an MPI rank and additively between ranks. The additive Schwarz preconditioners listed here construct patches around mesh entities. Crucially, the mesh must have an overlapping parallel domain decomposition that supports the patches. This is set via the - `distribution_parameters` kwarg of the :func:`.Mesh` constructor. For + `distribution_parameters` kwarg of the :func:`Mesh ` constructor. For instance, vertex-star patches require :: distribution_parameters["overlap_type"] = (DistributedMeshOverlapType.VERTEX, 1) @@ -154,7 +154,7 @@ operator instead. :class:`.ASMExtrudedStarPC`. See details in :cite:`Brubeck2022` and :cite:`Brubeck2024`. :class:`.MassInvPC` Preconditioner for applying an inverse mass matrix. -:class:`~.PCDPC` +:class:`PCDPC ` A preconditioner providing the Pressure-Convection-Diffusion approximation to the Schur complement for the Navier-Stokes equations. Note that this implementation only treats problems with diff --git a/docs/source/quadrature.rst b/docs/source/quadrature.rst index fcf1e7ddf4..b3208a4f2e 100644 --- a/docs/source/quadrature.rst +++ b/docs/source/quadrature.rst @@ -51,7 +51,7 @@ provided as a convenient shorthand. For integrals that do not specify a fixed or maximum quadrature degree, a default value may be keyed as the ``"quadrature_degree"`` or ``"max_quadrature_degree"`` entry respectively in the ``form_compiler_parameters`` dictionary passed on to :py:func:`~firedrake.solving.solve`, -:py:func:`~.project`, :py:class:`~.NonlinearVariationalProblem`, or :py:func:`~firedrake.assemble.assemble`. +:py:func:`~.project`, :py:class:`NonlinearVariationalProblem `, or :py:func:`~firedrake.assemble.assemble`. .. code-block:: python3 @@ -97,7 +97,7 @@ lumped quadrature schemes to produce a diagonal mass matrix. The Quadrature space -------------------- -It is possible to define a finite element :py:class:`~.Function` on a quadrature rule. +It is possible to define a finite element :py:class:`function ` on a quadrature rule. The ``"Quadrature"`` and ``"Boundary Quadrature"`` spaces are useful to interpolate data at quadrature points on cell interiors and cell boundaries, respectively. @@ -110,7 +110,7 @@ respectively. The ``quad_scheme`` keyword argument again may be either :py:class:`~finat.quadrature.QuadratureRule` or a string. -If a :py:class:`~.Function` in the ``"Quadrature"`` space appears within an +If a :py:class:`function ` in the ``"Quadrature"`` space appears within an integral, Firedrake will automatically select the quadrature rule that corresponds to ``dx(degree=quad_degree, scheme=quad_scheme)`` to match the one associated with the quadrature space. @@ -124,7 +124,7 @@ Finite element spaces with :ref:`integral-type degrees of freedom ` constructors. For example, to construct a Crouzeix-Raviart space with degrees of freedom consisting of integrals along the edges computed from a 2-point average at the endpoints, one can set ``quad_scheme="KMV"``: diff --git a/docs/source/solving-interface.rst b/docs/source/solving-interface.rst index 77b1160f70..23810a7184 100644 --- a/docs/source/solving-interface.rst +++ b/docs/source/solving-interface.rst @@ -21,7 +21,7 @@ consider a weak variational problem we will call the bilinear and linear parts of this form ``a`` and ``L`` respectively. The strongly imposed boundary condition, :math:`u = u_0 \;\mathrm{on}\:\partial\Omega` will be represented by a variable -of type :py:class:`~.DirichletBC`, ``bc``. +of type :py:class:`DirichletBC `, ``bc``. Now that we have all the pieces of our variational problem, we can move forward to solving it. @@ -44,7 +44,7 @@ Linear variational problems If the problem is linear, that is ``a`` is linear in both the test and trial functions and ``L`` is linear in the test function, we can use the linear variational problem interface to ``solve``. To start, we -need a :py:class:`~.Function` to hold the value of +need a :py:class:`function ` to hold the value of the solution: .. code-block:: python3 @@ -58,7 +58,7 @@ We can then solve the problem, placing the solution in ``s`` with: solve(a == L, s) To apply boundary conditions, one passes a list of -:py:class:`~.DirichletBC` objects using the ``bcs`` +:py:class:`DirichletBC ` objects using the ``bcs`` keyword argument. For example, if there are two boundary conditions, in ``bc1`` and ``bc2``, we write: @@ -80,7 +80,7 @@ solve a problem: where the *residual* :math:`F(u; v)` is linear in the test function :math:`v` but possibly non-linear in the unknown -:py:class:`~.Function` :math:`u`. To solve such a +:py:class:`function ` :math:`u`. To solve such a problem we write, if ``F`` is the residual form: .. code-block:: python3 @@ -144,8 +144,8 @@ pass in. In the pre-assembled case, we are solving a linear system: Where :math:`A` is a known matrix, :math:`\vec{b}` is a known right hand side vector and :math:`\vec{x}` is the unknown solution vector. In Firedrake, :math:`A` is represented as a -:py:class:`~.Matrix`, while :math:`\vec{x}` is a :py:class:`~.Function`, and -:math:`\vec{b}` a :py:class:`~.Cofunction`. +:py:class:`Matrix `, while :math:`\vec{x}` is a :py:class:`function `, and +:math:`\vec{b}` a :py:class:`Cofunction `. We build these values by calling ``assemble`` on the UFL forms that define our problem, which, as before are denoted ``a`` and ``L``. Similarly to the linear variational case, we first need a function in @@ -474,7 +474,7 @@ computing :math:`S^{-1}`). .. note:: If you have given your - :py:class:`~.FunctionSpace`\s names, then + :py:class:`FunctionSpace `\s names, then instead of 0 and 1, you should use the name of the function space in these options. @@ -565,7 +565,7 @@ as follows: # ILU on the schur complement block "fieldsplit_1_pc_type": "ilu"} -In this example, none of the :class:`~.FunctionSpace`\s used had +In this example, none of the :class:`FunctionSpace `\s used had names, and hence we referred to the fields by number. If the function spaces are named, then any time a single field appears as a split, its options prefix is referred to by the space's *name* (rather @@ -801,7 +801,7 @@ in Firedrake, we first must define the null space, and then inform the solver of its existance. We use a :class:`~firedrake.nullspace.VectorSpaceBasis` to hold the vectors which span the null space. We must provide a list of -:class:`~.Function`\s spanning the space. Additionally, +:class:`function `\s spanning the space. Additionally, since removing a constant null space is such a common operation, we can pass ``constant=True`` to the constructor (rather than constructing the constant vector by hand). Note that the vectors we diff --git a/docs/source/variational-problems.rst b/docs/source/variational-problems.rst index 93f96bcc6e..e27eb05370 100644 --- a/docs/source/variational-problems.rst +++ b/docs/source/variational-problems.rst @@ -9,17 +9,17 @@ Firedrake uses a high-level language, `UFL`_, to describe variational problems. To do this, we need a number of pieces. We need a representation of the domain we're solving the :abbr:`PDE (partial differential equation)` on: Firedrake uses a -:py:func:`~.Mesh` for this. On top of this mesh, -we build :py:class:`~.FunctionSpace`\s which +:py:func:`firedrake.Mesh` for this. On top of this mesh, +we build :py:class:`FunctionSpace `\s which define the space in which the solutions to our equation live. Finally -we define :py:class:`~.Function`\s in those +we define :py:class:`function `\s in those function spaces to actually hold the solutions. Constructing meshes ------------------- Firedrake can read meshes in `Gmsh`_, `triangle`_, `CGNS`_, and -`Exodus`_ formats. To build a mesh one uses the :py:func:`~.Mesh` +`Exodus`_ formats. To build a mesh one uses the :py:func:`firedrake.Mesh` constructor, passing the name of the file as an argument, which see for more details. The mesh type is determined by the file extension, for example if the provided filename is ``coastline.msh`` the mesh is @@ -44,7 +44,7 @@ reordering on the adjacency matrix of the input mesh. If you know your mesh has a good numbering (perhaps your mesh generator uses space filling curves to number entities) then you can switch off this reordering by passing ``reorder=False`` to the appropriate -:py:func:`~.Mesh` constructor. You can control Firedrake's default +:py:func:`firedrake.Mesh` constructor. You can control Firedrake's default behaviour in reordering meshes with the ``"reorder_meshes"`` parameter. For example, to turn off mesh reordering globally: @@ -159,7 +159,7 @@ Building function spaces Now that we have a mesh of our domain, we need to build the function spaces the solution to our :abbr:`PDE (partial differential equation)` will live in, along with the spaces for the trial and test functions. -To do so, we use the :py:func:`~.FunctionSpace` constructor. +To do so, we use the :py:func:`function space ` constructor. This is the only way to obtain a function space for a scalar variable, such as pressure, which has a single value at each point in the domain. @@ -174,14 +174,14 @@ continuous piecewise-cubic polynomials, we write: There are three main routes to obtaining a function space for a vector-valued variable such as velocity. Firstly, you can pass the -:py:func:`~.FunctionSpace` constructor a natively *vector-valued* +:py:func:`function space ` constructor a natively *vector-valued* family such as ``"Raviart-Thomas"``. Secondly, you may use the :py:func:`~.VectorFunctionSpace` constructor with a *scalar-valued* family, which gives a vector-valued space where each component is identical to the appropriate scalar-valued -:py:class:`~.FunctionSpace`. Thirdly, you can create a +:py:class:`FunctionSpace `. Thirdly, you can create a :py:class:`~finat.ufl.mixedelement.VectorElement` directly (which is itself -*vector-valued* and pass that to the :py:func:`~.FunctionSpace` +*vector-valued* and pass that to the :py:func:`function space ` constructor). To build a vector-valued function space using the lowest-order @@ -292,7 +292,7 @@ For CG and DG spaces on simplices, Firedrake offers both equispaced points and the better conditioned recursive Legendre points from :cite:`Isaac2020` via the `recursivenodes`_ module. These are selected by passing ``variant="equispaced"`` or ``variant="spectral"`` to the :py:class:`~finat.ufl.finiteelement.FiniteElement` or -:py:func:`~.FunctionSpace` constructors. For example: +:py:func:`function space ` constructors. For example: .. code-block:: python3 @@ -357,14 +357,14 @@ see that the solve is invoked by writing solve(a == L, s) -but solver reuse can be achieved using :py:class:`~.LinearVariationalSolver`, +but solver reuse can be achieved using :py:class:`linear variational solver `, which is usually the most efficient option for timestepping problems. A nonlinear variational problem is defined in terms of a linear form :math:`F[u;v]` which is linear in the test function :math:`v` but may be nonlinear in the coefficient :math:`u`. The nonlinear variational problem seeks :math:`u\in V` such that :math:`F[u;v]=0\, \forall v\in -V`. In UFL, the solution variable should be of type :py:class:`~.Function` +V`. In UFL, the solution variable should be of type :py:class:`function ` instead of :py:class:`~firedrake.ufl_expr.TrialFunction`. .. code-block:: python3 @@ -372,7 +372,7 @@ instead of :py:class:`~firedrake.ufl_expr.TrialFunction`. solve(F == 0, s) but solver reuse can be achieved using -:py:class:`~.NonlinearVariationalSolver`, which is usually the most +:py:class:`NonlinearVariationalSolver `, which is usually the most efficient option for timestepping problems. The solution approach for this problems is some form of Newton's method. UFL automates the symbolic differentiation of :math:`F` to obtain the Jacobian expressed @@ -395,7 +395,7 @@ an appropriate space along with a function to hold the solution and perhaps a trial function. Test functions are obtained via a call to :py:class:`~firedrake.ufl_expr.TestFunction`, trial functions via :py:class:`~firedrake.ufl_expr.TrialFunction` and functions with -:py:class:`~.Function`. The former two are purely +:py:class:`function `. The former two are purely symbolic objects, the latter contains storage for the coefficients of the basis functions in the function space. We use them as follows: @@ -407,7 +407,7 @@ the basis functions in the function space. We use them as follows: .. note:: - A newly allocated :py:class:`~.Function` has + A newly allocated :py:class:`function ` has coefficients which are all zero. If ``V`` above were a @@ -524,13 +524,13 @@ but may vary in time. For example, a time-varying diffusivity, or a time-dependent forcing function. Although you can create a new form for each new value of this constant, this will not be efficient, since Firedrake must generate new code each time the value changes. A -better option is to use a :py:class:`~.Constant` coefficient. This -object behaves exactly like a :py:class:`~.Function`, except that it +better option is to use a :py:class:`constant ` coefficient. This +object behaves exactly like a :py:class:`function `, except that it has a single value over the whole mesh. One may assign a new value to -the :py:class:`~.Constant` using the :py:meth:`~.Constant.assign` +the :py:class:`constant ` using the :py:meth:`~.Constant.assign` method. As an example, let us consider a form which contains a time varying constant which we wish to assemble in a time loop. We can use -a :py:class:`~.Constant` to do this: +a :py:class:`constant ` to do this: .. code-block:: python3 @@ -550,7 +550,7 @@ a :py:class:`~.Constant` to do this: .. warning:: Although UFL supports computing the derivative of a form with - respect to a :py:class:`~.Constant`, the resulting form will have + respect to a :py:class:`constant `, the resulting form will have an unknown in the reals, which is currently unsupported by Firedrake. @@ -565,7 +565,7 @@ incorporated into the variational form. `Essential` (often termed of the solution, become prescriptions on the function space. In Firedrake, the former are naturally expressed as part of the formulation of the variational problem, the latter are represented as -:py:class:`~.DirichletBC` objects and are applied when +:py:class:`DirichletBC ` objects and are applied when solving the variational problem. Construction of such a strong boundary condition requires a function space (to impose the boundary condition in), a value and a subdomain to apply the boundary condition @@ -581,8 +581,8 @@ for the various :ref:`utility meshes ` are described in their respective constructor documentation. For externally generated meshes, Firedrake just uses whichever ids the mesh generator provided. The ``value`` may be either a scalar, or -more generally a UFL expression, for example a :class:`~.Function` or -:py:class:`~.Constant`, of the appropriate shape. You may also supply +more generally a UFL expression, for example a :class:`function ` or +:py:class:`constant `, of the appropriate shape. You may also supply an iterable of literal constants: .. code-block:: python3 @@ -634,12 +634,12 @@ Specifying conditions on components of a space ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ When solving a problem defined on either a -:class:`~.MixedFunctionSpace` or a rank-1 :class:`~.FunctionSpace`, it is +:class:`~.MixedFunctionSpace` or a rank-1 :class:`FunctionSpace `, it is common to want to specify boundary values for only some of the components. In the former case, this is the only supported method of setting boundary values, the latter also supports setting the value for all components. In both cases, the syntax is the same. When -defining the :py:class:`~.DirichletBC` we must index the function space +defining the :py:class:`DirichletBC ` we must index the function space used. For example, to specify that the third component of a :py:func:`~.VectorFunctionSpace` should take the boundary value 0, we write: @@ -682,12 +682,12 @@ Time dependent boundary conditions ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Imposition of time-dependent boundary conditions can by carried out by -modifying the value in the appropriate :py:class:`~.DirichletBC` +modifying the value in the appropriate :py:class:`DirichletBC ` object. Note that if you use a literal value to initialise the boundary condition object within the timestepping loop, this will necessitate a recompilation of code every time the boundary condition changes. For this reason we either recommend using a -:py:class:`~.Constant` if the boundary condition is spatially uniform, +:py:class:`constant ` if the boundary condition is spatially uniform, or a UFL expression if it has both space and time-dependence. For example, a purely time-varying boundary condition might be implemented as: diff --git a/docs/source/visualisation.rst b/docs/source/visualisation.rst index f9cd4e80ca..f1bf206f92 100644 --- a/docs/source/visualisation.rst +++ b/docs/source/visualisation.rst @@ -16,7 +16,7 @@ Creating output files ~~~~~~~~~~~~~~~~~~~~~ Output for visualisation purposes is managed with a -:class:`~.vtk_output.VTKFile` object. To create one, first import the +:class:`VTKFile ` object. To create one, first import the class from `firedrake.output`, then we just need to pass the name of the output file on disk. The file Firedrake creates is in PVD and therefore the requested file name must end in ``.pvd``. @@ -27,8 +27,8 @@ therefore the requested file name must end in ``.pvd``. # The following raises an error badfile = VTKFile("output.vtu") -To save functions to the :class:`~.vtk_output.VTKFile` we use the -:meth:`~.vtk_output.VTKFile.write` method. +To save functions to the :class:`VTKFile ` we use the +:meth:`write ` method. .. code-block:: python3 @@ -53,8 +53,8 @@ Saving time-dependent data Often, we have a time-dependent simulation and would like to save the same function at multiple timesteps. This is straightforward, we must -create the output :class:`~.vtk_output.VTKFile` outside the time loop -and call :meth:`~.vtk_output.VTKFile.write` inside. +create the output :class:`VTKFile ` outside the time loop +and call :meth:`write ` inside. .. code-block:: python3 @@ -69,9 +69,9 @@ and call :meth:`~.vtk_output.VTKFile.write` inside. The PVD data format supports specifying the timestep value for time-dependent data. We do not have to provide it to -:meth:`~.vtk_output.VTKFile.write`, by default an integer counter is +:meth:`write `, by default an integer counter is used that is incremented by 1 each time -:meth:`~.vtk_output.VTKFile.write` is called. It is possible to +:meth:`write ` is called. It is possible to override this by passing the keyword argument ``time``. .. code-block:: python3 @@ -99,7 +99,7 @@ the data to this format first. One option is to do so by hand before outputting. Either by :doc:`interpolating ` or else :func:`projecting ` the :doc:`mesh coordinates ` and then the field. Since this is such -a common operation, the :class:`~.vtk_output.VTKFile` object is set up +a common operation, the :class:`VTKFile ` object is set up to manage these operations automatically, we just need to choose whether we want data to be interpolated or projected. The default is to use interpolation. For example, assume we wish to output a @@ -127,7 +127,7 @@ If instead we want projection, we use use an older version of Paraview, you must manually interpolate mesh coordinates and field coordinates to a piecewise linear function space, represented with either a Lagrange (H1) or discontinuous - Lagrange (L2) basis. The :class:`~.vtk_output.VTKFile` is also setup + Lagrange (L2) basis. The :class:`VTKFile ` is also setup to manage this issue. For instance, we can force the output to be discontinuous piecewise linears via @@ -197,7 +197,7 @@ pressure in a fluids models. This is possible either by having a separate output file for each field, or by saving multiple fields to the same output file. The latter may be more convenient for subsequent analysis. To do this, we just need to pass multiple -:class:`~.Function`\s to :meth:`~.vtk_output.VTKFile.write`. +:class:`function `\s to :meth:`write `. .. code-block:: python3 @@ -332,11 +332,11 @@ Visualising a vertex-only mesh Plotting vertex-only mesh data with matplotlib ++++++++++++++++++++++++++++++++++++++++++++++ -Firedrake supports the visualisation of point data, represented as a :func:`~.VertexOnlyMesh`, in much the same way as its other plotting routines. +Firedrake supports the visualisation of point data, represented as a :func:`firedrake.VertexOnlyMesh`, in much the same way as its other plotting routines. In particular, :func:`scatter ` wraps matplotlib's ``scatter`` method and uses the coordinates of the mesh's constituent points to produce a scatter plot. Although separate from :func:`triplot `, it makes most sense to use it in conjuction with :func:`triplot ` which makes apparent the embedding of the vertex-only mesh inside its parent mesh. As the below code demonstrates, :func:`scatter ` gives the user the freedom to pass -either a :func:`~.VertexOnlyMesh` object or a scalar :class:`~.Function` defined on it, in which case, the values of the function will be used to colour the points. +either a :func:`firedrake.VertexOnlyMesh` object or a scalar :class:`function ` defined on it, in which case, the values of the function will be used to colour the points. .. literalinclude:: ../../tests/firedrake/output/test_vom_plotting_manual.py :language: python3 @@ -376,8 +376,8 @@ Last but not least, vector fields defined on a vertex-only mesh can be visualise Writing vertex-only mesh data to VTK ++++++++++++++++++++++++++++++++++++ -Vertex-only mesh data can be written to VTK output enabling point data visualisations in third-party software such as ParaView. A :class:`~.vtk_output.VTKFile` accepts :class:`~.Function`\s -defined on a :func:`~.VertexOnlyMesh` in the same way as functions defined on ordinary meshes. The output includes the point coordinates, the values of any supplied function(s), +Vertex-only mesh data can be written to VTK output enabling point data visualisations in third-party software such as ParaView. A :class:`VTKFile ` accepts :class:`function `\s +defined on a :func:`firedrake.VertexOnlyMesh` in the same way as functions defined on ordinary meshes. The output includes the point coordinates, the values of any supplied function(s), and a persistent particle ID field. In ParaView, for instance, this ID field can be used to colour particles by identity. .. literalinclude:: ../../tests/firedrake/output/test_pvd_output.py diff --git a/firedrake/adjoint/ensemble_reduced_functional.py b/firedrake/adjoint/ensemble_reduced_functional.py index 72979a5702..70207114e3 100644 --- a/firedrake/adjoint/ensemble_reduced_functional.py +++ b/firedrake/adjoint/ensemble_reduced_functional.py @@ -25,7 +25,7 @@ class EnsembleReducedFunctional(AbstractReducedFunctional): \\frac{dJ}{dm} = \\sum_{i=1}^{N} \\frac{dJ_i}{dm}, The :class:`EnsembleReducedFunctional` allows simultaneous evaluation of :math:`J_i` and - :math:`\\dfrac{dJ_i}{dm}`. After that, the allreduce :class:`~.ensemble.Ensemble` + :math:`\\dfrac{dJ_i}{dm}`. After that, the allreduce :class:`firedrake.Ensemble.Ensemble` operation is employed to sum the functionals and their gradients over an ensemble communicator. @@ -41,7 +41,7 @@ class EnsembleReducedFunctional(AbstractReducedFunctional): control : pyadjoint.Control or list of pyadjoint.Control A single or a list of Control instances, which you want to map to the functional. ensemble : Ensemble - An instance of the :class:`~.ensemble.Ensemble`. It is used to communicate the + An instance of the :class:`firedrake.Ensemble.Ensemble`. It is used to communicate the functionals and their derivatives between the ensemble members. scatter_control : bool Whether scattering a control (or a list of controls) over the ensemble communicator @@ -78,7 +78,7 @@ class EnsembleReducedFunctional(AbstractReducedFunctional): See Also -------- - :class:`~.ensemble.Ensemble`, :class:`pyadjoint.ReducedFunctional`. + :class:`firedrake.Ensemble.Ensemble`, :class:`pyadjoint.ReducedFunctional`. Notes ----- diff --git a/firedrake/checkpointing.py b/firedrake/checkpointing.py index baa1b9a80e..acbc9e7c6b 100644 --- a/firedrake/checkpointing.py +++ b/firedrake/checkpointing.py @@ -65,9 +65,9 @@ class DumbCheckpoint: r"""A very dumb checkpoint object. - This checkpoint object is capable of writing :class:`~.Function`\s + This checkpoint object is capable of writing :class:`function `\s to disk in parallel (using HDF5) and reloading them on the same - number of processes and a :func:`~.Mesh` constructed identically. + number of processes and a :func:`firedrake.Mesh` constructed identically. :arg basename: the base name of the checkpoint file. :arg single_file: Should the checkpoint object use only a single @@ -85,7 +85,7 @@ class DumbCheckpoint: .. note:: This object contains both a PETSc ``Viewer``, used for storing - and loading :class:`~.Function` data, and an :class:`h5py.File` + and loading :class:`function ` data, and an :class:`h5py.File` opened on the same file handle. *DO NOT* call :meth:`h5py.File.close` on the latter, this will cause breakages. @@ -93,7 +93,7 @@ class DumbCheckpoint: .. warning:: ``DumbCheckpoint`` is deprecated and will be removed soon. Use - :class:`~.CheckpointFile` instead. + :class:`firedrake.CheckpointFile` instead. """ def __init__(self, basename, single_file=True, @@ -158,7 +158,7 @@ def new_file(self, name=None): of ``.h5`` is automatically appended. If ``name`` is not provided, a filename is generated from the - ``basename`` used when creating the :class:`~.DumbCheckpoint` + ``basename`` used when creating the :class:`firedrake.DumbCheckpoint` object. If ``single_file`` is ``True``, then we write to ``BASENAME.h5`` otherwise, each time :meth:`~.DumbCheckpoint.new_file` is called, we create a new @@ -353,9 +353,9 @@ class HDF5File: r"""An object to facilitate checkpointing. - This checkpoint object is capable of writing :class:`~.Function`\s + This checkpoint object is capable of writing :class:`function `\s to disk in parallel (using HDF5) and reloading them on the same - number of processes and a :func:`~.Mesh` constructed identically. + number of processes and a :func:`firedrake.Mesh` constructed identically. :arg filename: filename (including suffix .h5) of checkpoint file. :arg file_mode: the access mode, passed directly to h5py, see @@ -369,7 +369,7 @@ class HDF5File: .. warning:: HDF5File class will soon be deprecated. - Use :class:`~.CheckpointFile` class instead. + Use :class:`firedrake.CheckpointFile` class instead. """ def __init__(self, filename, file_mode, comm=None): @@ -542,7 +542,7 @@ def _generate_function_space_name(V): class TemporaryFunctionCheckpointFile: - """An HDF5 file for saving and loading :class:`~.Function` data on a sub-communicator. + """An HDF5 file for saving and loading :class:`function ` data on a sub-communicator. This class has a deliberately narrow contract that differs from :class:`CheckpointFile` in several important ways: @@ -551,17 +551,17 @@ class TemporaryFunctionCheckpointFile: COMM_WORLD (e.g. ``COMM_SELF`` for per-rank files, or a node-local communicator for per-node files). All I/O is collective only on that communicator — no COMM_WORLD operations are performed. - - It stores and retrieves :class:`~.Function` *data* (the local Vec + - It stores and retrieves :class:`function ` *data* (the local Vec array) only. It has no knowledge of mesh topology, DM sections, or PETSc SF. This is why :meth:`load_function` takes a - :class:`~.FunctionSpace` rather than a mesh: the caller already holds + :class:`FunctionSpace ` rather than a mesh: the caller already holds the function space and we simply fill in the values. - It is ephemeral: files are not intended to survive between programme runs. The communicator layout (partition) must be identical on save and restore. - The caller is responsible for assigning unique ``name``/``idx`` pairs on save and for restoring the correct ``name`` and ``count`` on the - returned :class:`~.Function` after load. + returned :class:`function ` after load. These constraints are intentional. Using :class:`CheckpointFile` with a sub-communicator deadlocks on load because the mesh DM operations @@ -666,14 +666,14 @@ def __del__(self): class CheckpointFile: - r"""Checkpointing meshes and :class:`~.Function` s in an HDF5 file. + r"""Checkpointing meshes and :class:`function ` s in an HDF5 file. :arg filename: the name of the HDF5 checkpoint file (.h5 or .hdf5). :arg mode: the file access mode (:obj:`~.FILE_READ`, :obj:`~.FILE_CREATE`, :obj:`~.FILE_UPDATE`) or ('r', 'w', 'a'). :arg comm: the communicator. This object allows for a scalable and flexible checkpointing of states. - One can save and load meshes and :class:`~.Function` s entirely in parallel + One can save and load meshes and :class:`function ` s entirely in parallel without needing to gather them to or scatter them from a single process. One can also use different number of processes for saving and for loading. @@ -1073,9 +1073,9 @@ def _save_function_space_topology(self, tV): @PETSc.Log.EventDecorator("SaveFunction") def save_function(self, f, idx=None, name=None, timestepping_info={}): - r"""Save a :class:`~.Function`. + r"""Save a :class:`function `. - :arg f: the :class:`~.Function` to save. + :arg f: the :class:`function ` to save. :kwarg idx: optional timestepping index. A function can either be saved in timestepping mode or in normal mode (non-timestepping); for each function of interest, @@ -1327,13 +1327,13 @@ def load_mesh(self, name=DEFAULT_MESH_NAME, reorder=None, distribution_parameter @PETSc.Log.EventDecorator("LoadMeshTopology") def _load_mesh_topology(self, tmesh_name, reorder, distribution_parameters): - """Load the :class:`~.MeshTopology`. + """Load the :class:`firedrake.MeshTopology`. - :arg tmesh_name: The name of the :class:`~.MeshTopology` to load. - :arg reorder: whether to reorder the mesh (bool); see :func:`~.Mesh`. + :arg tmesh_name: The name of the :class:`firedrake.MeshTopology` to load. + :arg reorder: whether to reorder the mesh (bool); see :func:`firedrake.Mesh`. :arg distribution_parameters: the `distribution_parameters` used for - distributing the mesh; see :func:`~.Mesh`. - :returns: The loaded :class:`~.MeshTopology`. + distributing the mesh; see :func:`firedrake.Mesh`. + :returns: The loaded :class:`firedrake.MeshTopology`. """ # -- Load DMPlex -- path = self._path_to_distributions(tmesh_name) @@ -1476,13 +1476,13 @@ def _load_function_space_topology(self, tmesh, element): @PETSc.Log.EventDecorator("LoadFunction") def load_function(self, mesh, name, idx=None): - r"""Load a :class:`~.Function` defined on `mesh`. + r"""Load a :class:`function ` defined on `mesh`. :arg mesh: the mesh on which the function is defined. - :arg name: the name of the :class:`~.Function` to load. + :arg name: the name of the :class:`function ` to load. :kwarg idx: optional timestepping index. A function can be loaded with idx only when it was saved with idx. - :returns: the loaded :class:`~.Function`. + :returns: the loaded :class:`function `. """ # TODO: Add general MeshSequence support. mesh = mesh.unique() diff --git a/firedrake/cython/dmcommon.pyx b/firedrake/cython/dmcommon.pyx index ca12036c51..00770e3ab2 100644 --- a/firedrake/cython/dmcommon.pyx +++ b/firedrake/cython/dmcommon.pyx @@ -1192,7 +1192,7 @@ def entity_orientations(mesh, np.ndarray cell_closure): """Compute entity orientations. - :arg mesh: The :class:`~.MeshTopology` object encapsulating the mesh topology + :arg mesh: The :class:`firedrake.MeshTopology` object encapsulating the mesh topology :arg cell_closure: The two-dimensional array, each row of which contains the closure of the associated cell :returns: A 2D array of the same shape as cell_closure, each row of which diff --git a/firedrake/dmhooks.py b/firedrake/dmhooks.py index 189203e25d..757acbdceb 100644 --- a/firedrake/dmhooks.py +++ b/firedrake/dmhooks.py @@ -8,7 +8,7 @@ The way Firedrake interacts with these DMs is, broadly, as follows: -A DM is tied to a :class:`~.FunctionSpace` and remembers what function +A DM is tied to a :class:`FunctionSpace ` and remembers what function space that is. To avoid reference cycles defeating the garbage collector, the DM holds a weakref to the FunctionSpace (which holds a strong reference to the DM). Use :func:`get_function_space` to get @@ -48,7 +48,7 @@ @PETSc.Log.EventDecorator() def get_function_space(dm): - """Get the :class:`~.FunctionSpace` attached to this DM. + """Get the :class:`FunctionSpace ` attached to this DM. :arg dm: The DM to get the function space from. :raises RuntimeError: if no function space was found. @@ -74,7 +74,7 @@ def get_function_space(dm): @PETSc.Log.EventDecorator() def set_function_space(dm, V): - """Set the :class:`~.FunctionSpace` on this DM. + """Set the :class:`FunctionSpace ` on this DM. :arg dm: The DM :arg V: The function space. diff --git a/firedrake/embedding.py b/firedrake/embedding.py index 15f8a09075..e87693d94f 100644 --- a/firedrake/embedding.py +++ b/firedrake/embedding.py @@ -38,7 +38,7 @@ def get_embedding_dg_element(element, value_shape, broken_cg=False): def get_embedding_element_for_checkpointing(element, value_shape): - """Convert the given UFL element to an element that :class:`~.CheckpointFile` can handle.""" + """Convert the given UFL element to an element that :class:`firedrake.CheckpointFile` can handle.""" if element.family() in native_elements_for_checkpointing: return element else: diff --git a/firedrake/ensemble/ensemble_function.py b/firedrake/ensemble/ensemble_function.py index 74a5fbf305..bb199f10da 100644 --- a/firedrake/ensemble/ensemble_function.py +++ b/firedrake/ensemble/ensemble_function.py @@ -12,10 +12,10 @@ class EnsembleFunctionBase(EnsembleFunctionMixin): """ - A mixed (co)function defined on a :class:`~.ensemble.Ensemble`. + A mixed (co)function defined on a :class:`firedrake.Ensemble.Ensemble`. The subcomponents are distributed over the ensemble members, and are specified locally in an - :class:`~.ensemble_functionspace.EnsembleFunctionSpace`. + :class:`firedrake.Ensemble_functionspace.EnsembleFunctionSpace`. Parameters ---------- @@ -25,7 +25,7 @@ class EnsembleFunctionBase(EnsembleFunctionMixin): Notes ----- - Passing an :class:`~.ensemble_functionspace.EnsembleDualSpace` to + Passing an :class:`firedrake.Ensemble_functionspace.EnsembleDualSpace` to :class:`EnsembleFunction` will return an instance of :class:`EnsembleCofunction`. This class does not carry UFL symbolic information, unlike a @@ -287,7 +287,7 @@ def vec_wo(self): class EnsembleFunction(EnsembleFunctionBase): """ - A mixed Function defined on a :class:`~.ensemble.Ensemble`. + A mixed Function defined on a :class:`firedrake.Ensemble.Ensemble`. The subcomponents are distributed over the ensemble members, and are specified locally in an :class:`~firedrake.ensemble.ensemble_functionspace.EnsembleFunctionSpace`. @@ -309,10 +309,10 @@ class EnsembleFunction(EnsembleFunctionBase): See Also -------- - :class:`~.ensemble_functionspace.EnsembleFunctionSpace` - :class:`~.ensemble_function.EnsembleFunction` - :class:`~.ensemble_functionspace.EnsembleDualSpace` - :class:`~.ensemble_function.EnsembleCofunction` + :class:`firedrake.Ensemble_functionspace.EnsembleFunctionSpace` + :class:`firedrake.Ensemble_function.EnsembleFunction` + :class:`firedrake.Ensemble_functionspace.EnsembleDualSpace` + :class:`firedrake.Ensemble_function.EnsembleCofunction` """ def __new__(cls, function_space: EnsembleFunctionSpaceBase): if isinstance(function_space, EnsembleDualSpace): @@ -365,10 +365,10 @@ class EnsembleCofunction(EnsembleFunctionBase): See Also -------- - :class:`~.ensemble_functionspace.EnsembleFunctionSpace` - :class:`~.ensemble_function.EnsembleFunction` - :class:`~.ensemble_functionspace.EnsembleDualSpace` - :class:`~.ensemble_function.EnsembleCofunction` + :class:`firedrake.Ensemble_functionspace.EnsembleFunctionSpace` + :class:`firedrake.Ensemble_function.EnsembleFunction` + :class:`firedrake.Ensemble_functionspace.EnsembleDualSpace` + :class:`firedrake.Ensemble_function.EnsembleCofunction` """ def __init__(self, function_space: EnsembleDualSpace): if not isinstance(function_space, EnsembleDualSpace): diff --git a/firedrake/ensemble/ensemble_functionspace.py b/firedrake/ensemble/ensemble_functionspace.py index ee7c0582e8..6e25a53c31 100644 --- a/firedrake/ensemble/ensemble_functionspace.py +++ b/firedrake/ensemble/ensemble_functionspace.py @@ -20,7 +20,7 @@ def _is_primal_or_dual(local_spaces, ensemble): local_spaces : Collection The list of :class:`~firedrake.functionspaceimpl.FunctionSpace` on the local ensemble.comm. - ensemble : :class:`~.ensemble.Ensemble` + ensemble : :class:`firedrake.Ensemble.Ensemble` The Ensemble to test collectively over. Returns @@ -64,7 +64,7 @@ def _is_primal_or_dual(local_spaces, ensemble): class EnsembleFunctionSpaceBase: """ - Base class for mixed function spaces defined on an :class:`~.ensemble.Ensemble`. + Base class for mixed function spaces defined on an :class:`firedrake.Ensemble.Ensemble`. The subcomponents are distributed over the ensemble members, and are specified locally. @@ -110,25 +110,25 @@ def __init__(self, local_spaces: Collection, ensemble: Ensemble): @property def ensemble(self): - """The :class:`~.ensemble.Ensemble` that the function space is defined over + """The :class:`firedrake.Ensemble.Ensemble` that the function space is defined over """ return self._ensemble @property def comm(self): - """The spatial communicator from the :class:`~.ensemble.Ensemble` communicator. + """The spatial communicator from the :class:`firedrake.Ensemble.Ensemble` communicator. """ return self._ensemble.comm @property def ensemble_comm(self): - """The ensemble communicator from the :class:`~.ensemble.Ensemble` communicator. + """The ensemble communicator from the :class:`firedrake.Ensemble.Ensemble` communicator. """ return self._ensemble.ensemble_comm @property def global_comm(self): - """The global communicator from the :class:`~.ensemble.Ensemble` communicator. + """The global communicator from the :class:`firedrake.Ensemble.Ensemble` communicator. """ return self._ensemble.global_comm @@ -231,7 +231,7 @@ def __neq__(self, other): class EnsembleFunctionSpace(EnsembleFunctionSpaceBase): """ - A mixed primal function space defined on an :class:`~.ensemble.Ensemble`. + A mixed primal function space defined on an :class:`firedrake.Ensemble.Ensemble`. The subcomponents are distributed over the ensemble members, but are specified locally on each ensemble member. @@ -239,7 +239,7 @@ class EnsembleFunctionSpace(EnsembleFunctionSpaceBase): ---------- local_spaces : Collection The list of primal function spaces on the local ``Ensemble.comm``. - ensemble : :class:`~.ensemble.Ensemble` + ensemble : :class:`firedrake.Ensemble.Ensemble` The communicator that the function space is defined over. Notes diff --git a/firedrake/ensemble/ensemble_mat.py b/firedrake/ensemble/ensemble_mat.py index f600937594..3a37f67dd4 100644 --- a/firedrake/ensemble/ensemble_mat.py +++ b/firedrake/ensemble/ensemble_mat.py @@ -6,7 +6,7 @@ class EnsembleMatCtxBase: """ - Base class for python type Mats defined over an :class:`~.ensemble.Ensemble`. + Base class for python type Mats defined over an :class:`firedrake.Ensemble.Ensemble`. Parameters ---------- @@ -20,7 +20,7 @@ class EnsembleMatCtxBase: Notes ----- The main use of this base class is to enable users to implement the matrix - action as acting on and resulting in an :class:`~.ensemble_function.EnsembleFunction`. + action as acting on and resulting in an :class:`firedrake.Ensemble_function.EnsembleFunction`. This is done by implementing the ``mult_impl`` method. See Also @@ -106,8 +106,8 @@ def mult_impl(self, A, x: EnsembleFunctionBase, y: EnsembleFunctionBase): class EnsembleBlockDiagonalMatCtx(EnsembleMatCtxBase): """ - A python Mat context for a block diagonal matrix defined over an :class:`~.ensemble.Ensemble`. - Each block acts on a single subspace of an :class:`~.ensemble_functionspace.EnsembleFunctionSpace`. + A python Mat context for a block diagonal matrix defined over an :class:`.ensemble.Ensemble`. + Each block acts on a single subspace of an :class:`firedrake.Ensemble_functionspace.EnsembleFunctionSpace`. Parameters ---------- @@ -221,8 +221,8 @@ def EnsembleBlockDiagonalMat(block_mats: Iterable, row_space: EnsembleFunctionSpaceBase, col_space: EnsembleFunctionSpaceBase): """ - A Mat for a block diagonal matrix defined over an :class:`~.ensemble.Ensemble`. - Each block acts on a single subspace of an :class:`~.ensemble_functionspace.EnsembleFunctionSpace`. + A Mat for a block diagonal matrix defined over an :class:`firedrake.Ensemble.Ensemble`. + Each block acts on a single subspace of an :class:`firedrake.Ensemble_functionspace.EnsembleFunctionSpace`. This is a convenience function to create a PETSc.Mat with a :class:`.EnsembleBlockDiagonalMatCtx` Python context. Parameters diff --git a/firedrake/ensemble/ensemble_pc.py b/firedrake/ensemble/ensemble_pc.py index 1a3f96aaae..35a4b2bd3b 100644 --- a/firedrake/ensemble/ensemble_pc.py +++ b/firedrake/ensemble/ensemble_pc.py @@ -10,14 +10,14 @@ def obj_name(obj): class EnsemblePCBase(petsctools.PCBase): """ - Base class for python type PCs defined over an :class:`~.ensemble.Ensemble`. + Base class for python type PCs defined over an :class:`firedrake.Ensemble.Ensemble`. - The pc operators must be python Mats with :class:`~.ensemble_mat.EnsembleMatCtxBase`. + The pc operators must be python Mats with :class:`firedrake.Ensemble_mat.EnsembleMatCtxBase`. Notes ----- The main use of this base class is to enable users to implement the preconditioner - action as acting on and resulting in an :class:`~.ensemble_function.EnsembleFunction`. + action as acting on and resulting in an :class:`firedrake.Ensemble_function.EnsembleFunction`. This is done by implementing the ``apply_impl`` method. See Also @@ -58,8 +58,8 @@ def apply_impl(self, pc, x, y): class EnsembleBJacobiPC(EnsemblePCBase): """ - A python PC context for a block Jacobi method defined over an :class:`~.ensemble.Ensemble`. - Each block acts on a single subspace of an :class:`~.ensemble_functionspace.EnsembleFunctionSpace` + A python PC context for a block Jacobi method defined over an :class:`firedrake.Ensemble.Ensemble`. + Each block acts on a single subspace of an :class:`firedrake.Ensemble_functionspace.EnsembleFunctionSpace` and is (approximately) solved with its own KSP, which defaults to -ksp_type preonly. Available options: @@ -70,7 +70,7 @@ class EnsembleBJacobiPC(EnsemblePCBase): Notes ----- - Currently this is only implemented for :class:`~.ensemble_mat.EnsembleBlockDiagonalMatCtx` matrices. + Currently this is only implemented for :class:`firedrake.Ensemble_mat.EnsembleBlockDiagonalMatCtx` matrices. See Also -------- diff --git a/firedrake/exceptions.py b/firedrake/exceptions.py index e7c72cab43..a30493c1d8 100644 --- a/firedrake/exceptions.py +++ b/firedrake/exceptions.py @@ -25,7 +25,7 @@ class DofTypeError(FiredrakeException): class VertexOnlyMeshMissingPointsError(FiredrakeException): """Exception raised when 1 or more points are not found by a - :func:`~.VertexOnlyMesh` in its parent mesh. + :func:`firedrake.VertexOnlyMesh` in its parent mesh. Attributes ---------- diff --git a/firedrake/extrusion_utils.py b/firedrake/extrusion_utils.py index e0e3d91e02..071f20649c 100644 --- a/firedrake/extrusion_utils.py +++ b/firedrake/extrusion_utils.py @@ -24,9 +24,9 @@ def make_extruded_coords(extruded_topology, base_coords, ext_coords, :arg extruded_topology: an :class:`~.ExtrudedMeshTopology` to extrude a coordinate field for. - :arg base_coords: a :class:`~.Function` to read the base + :arg base_coords: a :class:`function ` to read the base coordinates from. - :arg ext_coords: a :class:`~.Function` to write the extruded + :arg ext_coords: a :class:`function ` to write the extruded coordinates into. :arg layer_height: the height for each layer. Either a scalar, where layers will be equi-spaced at the specified height, or a diff --git a/firedrake/function.py b/firedrake/function.py index 6d2d48d496..1bb5f4bc52 100644 --- a/firedrake/function.py +++ b/firedrake/function.py @@ -138,7 +138,7 @@ def sub(self, i): See also :attr:`subfunctions`. If the :class:`Function` is defined on a - rank-n :class:`~.FunctionSpace`, this returns a proxy object + rank-n :class:`FunctionSpace `, this returns a proxy object indexing the ith component of the space, suitable for use in boundary condition application.""" mixed = type(self.function_space().ufl_element()) is MixedElement @@ -212,7 +212,7 @@ def __str__(self): class Function(ufl.Coefficient, FunctionMixin): r"""A :class:`Function` represents a discretised field over the - domain defined by the underlying :func:`.Mesh`. Functions are + domain defined by the underlying :func:`Mesh `. Functions are represented as sums of basis functions: .. math:: @@ -582,7 +582,7 @@ def _at(self, arg, *args, **kwargs): :kwarg dont_raise: Do not raise an error if a point is not found. :kwarg tolerance: Tolerence to use when checking if a point is in a cell. Default is the ``tolerance`` provided when - creating the :func:`~.Mesh` the function is defined on. + creating the :func:`firedrake.Mesh` the function is defined on. Changing this from default will cause the rtree to be rebuilt which can take some time. """ @@ -780,7 +780,7 @@ def evaluate(self, function: Function) -> np.ndarray | Tuple[np.ndarray, ...]: .. warning:: This method returns a numpy array and hence isn't taped for use with firedrake-adjoint. - If you want to use point evaluation with the adjoint, create a :func:`~.VertexOnlyMesh` + If you want to use point evaluation with the adjoint, create a :func:`firedrake.VertexOnlyMesh` as described in the manual. """ from firedrake import assemble, interpolate diff --git a/firedrake/functionspacedata.py b/firedrake/functionspacedata.py index a1b6190cfb..a5ab93e549 100644 --- a/firedrake/functionspacedata.py +++ b/firedrake/functionspacedata.py @@ -1,8 +1,8 @@ """This module provides an object that encapsulates data that can be -shared between different :class:`~.FunctionSpace` objects. +shared between different :class:`FunctionSpace ` objects. The sharing is based on the idea of compatibility of function space -node layout. The shared data is stored on the :func:`~.Mesh` the +node layout. The shared data is stored on the :func:`firedrake.Mesh` the function space is created on, since the created objects are mesh-specific. The sharing is done on an individual key basis. So, for example, Sets can be shared between all function spaces with the diff --git a/firedrake/functionspaceimpl.py b/firedrake/functionspaceimpl.py index 36c2652615..ea5d316503 100644 --- a/firedrake/functionspaceimpl.py +++ b/firedrake/functionspaceimpl.py @@ -1,5 +1,5 @@ r""" -This module provides the implementations of :class:`~.FunctionSpace` +This module provides the implementations of :class:`FunctionSpace ` and :class:`~.MixedFunctionSpace` objects, along with some utility classes for attaching extra information to instances of these. """ @@ -79,7 +79,7 @@ def check_element(element, top=True): class WithGeometryBase: - r"""Attach geometric information to a :class:`~.FunctionSpace`. + r"""Attach geometric information to a :class:`FunctionSpace `. Function spaces on meshes with different geometry but the same topology can share data, except for their UFL cell. This class @@ -227,9 +227,9 @@ def max_work_functions(self, val): set_max_work_functions(self, val) def get_work_function(self, zero=True): - r"""Get a temporary work :class:`~.Function` on this :class:`FunctionSpace`. + r"""Get a temporary work :class:`function ` on this :class:`FunctionSpace`. - :arg zero: Should the :class:`~.Function` be guaranteed zero? + :arg zero: Should the :class:`function ` be guaranteed zero? If ``zero`` is ``False`` the returned function may or may not be zeroed, and the user is responsible for appropriate zeroing. @@ -241,7 +241,7 @@ def get_work_function(self, zero=True): This method is intended to be used for short-lived work functions, if you actually need a function for general - usage use the :class:`~.Function` constructor. + usage use the :class:`function ` constructor. When you are finished with the work function, you should restore it to the pool of available functions with @@ -343,7 +343,7 @@ def boundary_nodes(self, sub_domain): :returns: A numpy array of the unique function space nodes on the selected portion of the boundary. - See also :class:`~.DirichletBC` for details of the arguments. + See also :class:`DirichletBC ` for details of the arguments. """ # Have to replicate the definition from FunctionSpace because # we want to access the DM on the WithGeometry object. @@ -504,7 +504,7 @@ class FunctionSpace: topological mesh entities. The degree of freedom mapping is determined from the provided element. - :arg mesh: The :func:`~.Mesh` to build the function space on. + :arg mesh: The :func:`firedrake.Mesh` to build the function space on. :arg element: The :class:`finat.ufl.finiteelementbase.FiniteElementBase` describing the degrees of freedom. :kwarg name: An optional name for this :class:`FunctionSpace`, @@ -524,7 +524,7 @@ class FunctionSpace: .. warning:: Users should not build a :class:`FunctionSpace` directly, instead - they should use the utility :func:`~.FunctionSpace` function, + they should use the utility :func:`function space ` function, which provides extra error checking and argument sanitising. """ @@ -840,13 +840,13 @@ def exterior_facet_node_map(self): self.offset_quotient) def boundary_nodes(self, sub_domain): - r"""Return the boundary nodes for this :class:`~.FunctionSpace`. + r"""Return the boundary nodes for this :class:`FunctionSpace `. :arg sub_domain: the mesh marker selecting which subset of facets to consider. :returns: A numpy array of the unique function space nodes on the selected portion of the boundary. - See also :class:`~.DirichletBC` for details of the arguments. + See also :class:`DirichletBC ` for details of the arguments. """ return self._shared_data.boundary_nodes(self, sub_domain) diff --git a/firedrake/mesh.py b/firedrake/mesh.py index c31b8c682d..20196596f8 100644 --- a/firedrake/mesh.py +++ b/firedrake/mesh.py @@ -2273,7 +2273,7 @@ def cell_global_index(self): def input_ordering(self): """ Return the input ordering of the mesh vertices as a - :class:`~.VertexOnlyMeshTopology` whilst preserving other information, such as + :class:`firedrake.VertexOnlyMeshTopology` whilst preserving other information, such as the global indices and parent mesh cell information. Notes @@ -2318,7 +2318,7 @@ def _make_input_ordering_sf(swarm, nroots, ilocal): @cached_property # TODO: Recalculate if mesh moves def input_ordering_sf(self): """ - Return a PETSc SF which has :func:`~.VertexOnlyMesh` input ordering + Return a PETSc SF which has :func:`firedrake.VertexOnlyMesh` input ordering vertices as roots and this mesh's vertices (including any halo cells) as leaves. """ @@ -2335,7 +2335,7 @@ def input_ordering_sf(self): @cached_property # TODO: Recalculate if mesh moves def input_ordering_without_halos_sf(self): """ - Return a PETSc SF which has :func:`~.VertexOnlyMesh` input ordering + Return a PETSc SF which has :func:`firedrake.VertexOnlyMesh` input ordering vertices as roots and this mesh's non-halo vertices as leaves. """ # The leaves have been ordered according to the pyop2 classes with non-halo @@ -2447,7 +2447,7 @@ def coordinates(self, value): @cached_property def cell_sizes(self): - """A :class:`~.Function` in the :math:`P^1` space containing the local mesh size. + """A :class:`function ` in the :math:`P^1` space containing the local mesh size. This is computed by the :math:`L^2` projection of the local mesh element size.""" from firedrake.ufl_expr import CellSize @@ -2847,7 +2847,7 @@ def _c_locator(self, tolerance=None): def input_ordering(self): """ Return the input ordering of the mesh vertices as a - :func:`~.VertexOnlyMesh` whilst preserving other information, such as + :func:`firedrake.VertexOnlyMesh` whilst preserving other information, such as the global indices and parent mesh cell information. Notes @@ -4938,7 +4938,7 @@ def Submesh(mesh, subdim=None, subdomain_id=None, label_name=None, name=None, ig To make a submesh of co-dimension 1, the parent mesh must have been overlapped with :class:`DistributedMeshOverlapType` of {``None``, `VERTEX``, ``RIDGE``}; see ``distribution_parameters`` - kwarg of :func:`~.Mesh`. + kwarg of :func:`firedrake.Mesh`. To use interior facet integration on a submesh of co-dimension 1, the parent mesh must have been overlapped with diff --git a/firedrake/mg/mesh.py b/firedrake/mg/mesh.py index 8c1a6c237a..c0b172c216 100644 --- a/firedrake/mg/mesh.py +++ b/firedrake/mg/mesh.py @@ -91,7 +91,7 @@ def __len__(self): def __getitem__(self, idx): """Return a mesh in the hierarchy - :arg idx: The :func:`~.Mesh` to return""" + :arg idx: The :func:`firedrake.Mesh` to return""" return self.meshes[idx] def add_mesh(self, mesh, coarse_to_fine_cells=None, fine_to_coarse_cells=None): @@ -205,7 +205,7 @@ def MeshHierarchy(mesh, refinement_levels=0, If not False the hierachy is constructed using ngsPETSc, if None hierarchy constructed in a standard manner. distribution_parameters : dict - options controlling mesh distribution, see :py:func:`.Mesh` + options controlling mesh distribution, see :py:func:`Mesh ` for details. If ``None``, use the same distribution parameters as were used to distribute the coarse mesh, otherwise, these options override the default. @@ -341,7 +341,7 @@ def ExtrudedMeshHierarchy(base_hierarchy, height, base_layer=-1, refinement_rati :arg mesh_builder: function used to turn a ``Mesh`` into an extruded mesh. Used by pyadjoint. - See :func:`~.ExtrudedMesh` for the meaning of the remaining parameters. + See :func:`ExtrudedMesh ` for the meaning of the remaining parameters. """ if not isinstance(base_hierarchy, HierarchyBase): raise ValueError("Expecting a HierarchyBase, not a %r" % type(base_hierarchy)) @@ -394,7 +394,7 @@ def SemiCoarsenedExtrudedHierarchy(base_mesh, height, nref=1, base_layer=-1, ref :arg mesh_builder: function used to turn a ``Mesh`` into an extruded mesh. Used by pyadjoint. - See :func:`~.ExtrudedMesh` for the meaning of the remaining parameters. + See :func:`ExtrudedMesh ` for the meaning of the remaining parameters. See also :func:`~.ExtrudedMeshHierarchy` if you want to extruded a hierarchy of unstructured meshes. diff --git a/firedrake/nullspace.py b/firedrake/nullspace.py index d31b5de454..b38904a417 100644 --- a/firedrake/nullspace.py +++ b/firedrake/nullspace.py @@ -103,7 +103,7 @@ def rediscretise(self, function_space: firedrake.functionspaceimpl.WithGeometryB Parameters ---------- function_space - the new :class:`~.FunctionSpace`. + the new :class:`FunctionSpace `. Returns ------- @@ -263,7 +263,7 @@ def rediscretise(self, function_space: firedrake.functionspaceimpl.WithGeometryB Parameters ---------- function_space - the new :class:`~.FunctionSpace`. + the new :class:`FunctionSpace `. Returns ------- diff --git a/firedrake/preconditioners/asm.py b/firedrake/preconditioners/asm.py index afc5bc9c23..5a2f8f8b2a 100644 --- a/firedrake/preconditioners/asm.py +++ b/firedrake/preconditioners/asm.py @@ -111,7 +111,7 @@ def initialize(self, pc): def get_patches(self, V): ''' Get the patches used for PETSc PCASM - :param V: the :class:`~.FunctionSpace`. + :param V: the :class:`FunctionSpace `. :returns: a list of index sets defining the ASM patches in local numbering (before lgmap.apply has been called). diff --git a/firedrake/pyplot/mpl.py b/firedrake/pyplot/mpl.py index fef61abb68..58f48984d8 100644 --- a/firedrake/pyplot/mpl.py +++ b/firedrake/pyplot/mpl.py @@ -90,8 +90,8 @@ def scatter(vom_or_function: MeshGeometry | Function, axes: matplotlib.axes.Axes Parameters ---------- vom_or_function - A :func:`.VertexOnlyMesh` or a scalar-valued :class:`~.Function` defined on one. - If a :class:`~.Function` is provided, its values are used to colour the points. + A :func:`.VertexOnlyMesh` or a scalar-valued :class:`function ` defined on one. + If a :class:`function ` is provided, its values are used to colour the points. axes The axes on which to plot. If not provided, the current active axes are used. **kwargs @@ -302,11 +302,11 @@ def _plot_2d_field(method_name, function, *args, complex_component="real", **kwa @PETSc.Log.EventDecorator() def tricontourf(function, *args, complex_component="real", **kwargs): - r"""Create a filled contour plot of a 2D Firedrake :class:`~.Function` + r"""Create a filled contour plot of a 2D Firedrake :class:`function ` If the input function is a vector field, the magnitude will be plotted. - :arg function: the Firedrake :class:`~.Function` to plot + :arg function: the Firedrake :class:`function ` to plot :arg args: same as for matplotlib :func:`tricontourf ` :kwarg complex_component: If plotting complex data, which component? (``'real'`` or ``'imag'``). Default is ``'real'``. @@ -318,11 +318,11 @@ def tricontourf(function, *args, complex_component="real", **kwargs): @PETSc.Log.EventDecorator() def tricontour(function, *args, complex_component="real", **kwargs): - r"""Create a contour plot of a 2D Firedrake :class:`~.Function` + r"""Create a contour plot of a 2D Firedrake :class:`function ` If the input function is a vector field, the magnitude will be plotted. - :arg function: the Firedrake :class:`~.Function` to plot + :arg function: the Firedrake :class:`function ` to plot :arg args: same as for matplotlib :func:`tricontour ` :kwarg complex_component: If plotting complex data, which component? (``'real'`` or ``'imag'``). Default is ``'real'``. @@ -334,7 +334,7 @@ def tricontour(function, *args, complex_component="real", **kwargs): @PETSc.Log.EventDecorator() def tripcolor(function, *args, complex_component="real", **kwargs): - r"""Create a pseudo-color plot of a 2D Firedrake :class:`~.Function` + r"""Create a pseudo-color plot of a 2D Firedrake :class:`function ` If the input function is a vector field, the magnitude will be plotted. @@ -372,11 +372,11 @@ def _trisurf_3d(axes, function, *args, complex_component="real", vmin=None, vmax @PETSc.Log.EventDecorator() def trisurf(function, *args, complex_component="real", **kwargs): - r"""Create a 3D surface plot of a 2D Firedrake :class:`~.Function` + r"""Create a 3D surface plot of a 2D Firedrake :class:`function ` If the input function is a vector field, the magnitude will be plotted. - :arg function: the Firedrake :class:`~.Function` to plot + :arg function: the Firedrake :class:`function ` to plot :arg args: same as for matplotlib :meth:`plot_trisurf ` :kwarg complex_component: If plotting complex data, which component? (``'real'`` or ``'imag'``). Default is ``'real'``. @@ -415,7 +415,7 @@ def trisurf(function, *args, complex_component="real", **kwargs): @PETSc.Log.EventDecorator() def quiver(function: Function, *, complex_component: str = "real", **kwargs) -> matplotlib.quiver.Quiver: - r"""Make a quiver plot of a 2D vector Firedrake :class:`~.Function`. + r"""Make a quiver plot of a 2D vector Firedrake :class:`function `. Parameters ---------- @@ -473,7 +473,7 @@ def streamline(function, point, direction=+1, tolerance=3e-3, loc_tolerance=1e-1 complex_component="real"): r"""Generate a streamline of a vector field starting from a point - :arg function: the Firedrake :class:`~.Function` to plot + :arg function: the Firedrake :class:`function ` to plot :arg point: the starting point of the streamline :arg direction: either +1 or -1 to integrate forward or backward :arg tolerance: dimensionless tolerance for the RK12 adaptive integration @@ -695,7 +695,7 @@ def streamplot(function, resolution=None, min_length=None, max_time=None, Similar to matplotlib :func:`streamplot ` - :arg function: the Firedrake :class:`~.Function` to plot + :arg function: the Firedrake :class:`function ` to plot :arg resolution: minimum spacing between streamlines (defaults to domain size / 20) :arg min_length: minimum length of a streamline (defaults to 4x resolution) :arg max_time: maximum time to integrate a streamline @@ -829,9 +829,9 @@ def _default_update_prop(self, legend_handle, orig_handle): @PETSc.Log.EventDecorator() def plot(function, *args, num_sample_points=10, complex_component="real", **kwargs): - r"""Plot a 1D Firedrake :class:`~.Function` + r"""Plot a 1D Firedrake :class:`function ` - :arg function: The :class:`~.Function` to plot + :arg function: The :class:`function ` to plot :arg args: same as for matplotlib :func:`plot ` :arg num_sample_points: number of sample points for high-degree functions :kwarg complex_component: If plotting complex data, which @@ -910,7 +910,7 @@ def _bezier_plot(function, axes, complex_component="real", **kwargs): """Plot a 1D function on a function space with order no more than 4 using Bezier curves within each cell - :arg function: 1D :class:`~.Function` to plot + :arg function: 1D :class:`function ` to plot :arg axes: :class:`Axes ` for plotting :kwarg complex_component: If plotting complex data, which component? (``'real'`` or ``'imag'``). Default is ``'real'``. diff --git a/firedrake/slate/slate.py b/firedrake/slate/slate.py index dde4856ee1..03ba45aa7b 100644 --- a/firedrake/slate/slate.py +++ b/firedrake/slate/slate.py @@ -435,7 +435,7 @@ def __hash__(self): class AssembledVector(TensorBase): """This class is a symbolic representation of an assembled - vector of data contained in a :class:`~.Function`. + vector of data contained in a :class:`function `. :arg function: A firedrake function. """ @@ -524,7 +524,7 @@ def _key(self): class BlockAssembledVector(AssembledVector): """This class is a symbolic representation of an assembled - vector of data contained in a set of :class:`~.Function` s + vector of data contained in a set of :class:`function ` s defined on pieces of a split mixed function space. :arg functions: A tuple of firedrake functions. diff --git a/firedrake/solving.py b/firedrake/solving.py index 6139465b4e..1c70956788 100644 --- a/firedrake/solving.py +++ b/firedrake/solving.py @@ -98,7 +98,7 @@ def solve(*args, **kwargs): The nonlinear solver uses a PETSc SNES object under the hood. To pass options to it, use the same options names as you would for - pure PETSc code. See :class:`~.NonlinearVariationalSolver` for more + pure PETSc code. See :class:`NonlinearVariationalSolver ` for more details. .. code-block:: python3 @@ -137,7 +137,7 @@ def solve(*args, **kwargs): ------- firedrake.function.Function or None For a variational problem (cases 2 and 3 above), the (possibly - adapted) solution :class:`~.Function`. This may differ from the + adapted) solution :class:`function `. This may differ from the ``u`` that was passed in if the solver performed mesh adaptation during the solve. `None` is returned when solving a pre-assembled linear system (case 1 above). diff --git a/firedrake/tsfc_interface.py b/firedrake/tsfc_interface.py index cde7f678a1..fdca462cae 100644 --- a/firedrake/tsfc_interface.py +++ b/firedrake/tsfc_interface.py @@ -202,7 +202,7 @@ def compile_form(form, name, parameters=None, split=True, dont_split=(), diagona elements on embedded manifolds). The coordinates are extracted from the domain of the integral (a - :func:`~.Mesh`) + :func:`firedrake.Mesh`) """ diff --git a/firedrake/ufl_expr.py b/firedrake/ufl_expr.py index f71d111981..93406c6fb4 100644 --- a/firedrake/ufl_expr.py +++ b/firedrake/ufl_expr.py @@ -302,7 +302,7 @@ def action(form, coefficient, derivatives_expanded=None): """Compute the action of a form on a coefficient. :arg form: A UFL form, or a Slate tensor. - :arg coefficient: The :class:`~.Function` to act on. + :arg coefficient: The :class:`function ` to act on. :returns: a symbolic expression for the action. """ if isinstance(form, firedrake.slate.TensorBase): diff --git a/firedrake/utility_meshes.py b/firedrake/utility_meshes.py index 3d96a9aa09..f2795bcf2b 100644 --- a/firedrake/utility_meshes.py +++ b/firedrake/utility_meshes.py @@ -36,7 +36,6 @@ __all__ = [ "UnitIntervalMesh", - "PeriodicIntervalMesh", "PeriodicUnitIntervalMesh", "UnitTriangleMesh", "TensorRectangleMesh", @@ -117,7 +116,7 @@ def IntervalMesh( boundary point (in which case ``length_or_left`` should be the left boundary point). :kwarg distribution_parameters: options controlling mesh - distribution, see :func:`.Mesh` for details. + distribution, see :func:`Mesh ` for details. :kwarg reorder: (optional), should the mesh be reordered? :kwarg comm: Optional communicator to build the mesh on. :kwarg name: Optional name of the mesh. @@ -179,7 +178,7 @@ def UnitIntervalMesh( :arg ncells: The number of the cells over the interval. :kwarg distribution_parameters: options controlling mesh - distribution, see :func:`.Mesh` for details. + distribution, see :func:`Mesh ` for details. :kwarg reorder: (optional), should the mesh be reordered? :kwarg comm: Optional communicator to build the mesh on. :kwarg name: Optional name of the mesh. @@ -221,7 +220,7 @@ def PeriodicIntervalMesh( :arg ncells: The number of cells over the interval. :arg length: The length the interval. :kwarg distribution_parameters: options controlling mesh - distribution, see :func:`.Mesh` for details. + distribution, see :func:`Mesh ` for details. :kwarg reorder: (optional), should the mesh be reordered? :kwarg comm: Optional communicator to build the mesh on. :kwarg name: Optional name of the mesh. @@ -269,7 +268,7 @@ def PeriodicUnitIntervalMesh( :arg ncells: The number of cells in the interval. :kwarg distribution_parameters: options controlling mesh - distribution, see :func:`.Mesh` for details. + distribution, see :func:`Mesh ` for details. :kwarg reorder: (optional), should the mesh be reordered? :kwarg comm: Optional communicator to build the mesh on. :kwarg name: Optional name of the mesh. @@ -311,7 +310,7 @@ def OneElementThickMesh( :arg Lx: The width of the domain in the x-direction. :arg Ly: The width of the domain in the y-direction. :kwarg distribution_parameters: options controlling mesh - distribution, see :func:`.Mesh` for details. + distribution, see :func:`Mesh ` for details. :kwarg comm: Optional communicator to build the mesh on. :kwarg name: Optional name of the mesh. :kwarg distribution_name: the name of parallel distribution used @@ -491,7 +490,7 @@ def UnitTriangleMesh( :kwarg refinement_level: Number of uniform refinements to perform :kwarg distribution_parameters: options controlling mesh - distribution, see :func:`.Mesh` for details. + distribution, see :func:`Mesh ` for details. :kwarg comm: Optional communicator to build the mesh on. :kwarg name: Optional name of the mesh. :kwarg distribution_name: the name of parallel distribution used @@ -569,7 +568,7 @@ def RectangleMesh( :kwarg quadrilateral: (optional), creates quadrilateral mesh, defaults to False :kwarg reorder: (optional), should the mesh be reordered :kwarg distribution_parameters: options controlling mesh - distribution, see :func:`.Mesh` for details. + distribution, see :func:`Mesh ` for details. :kwarg comm: Optional communicator to build the mesh on. :kwarg diagonal: For triangular meshes, should the diagonal got from bottom left to top right (``"right"``), or top left to @@ -639,7 +638,7 @@ def TensorRectangleMesh( :kwarg quadrilateral: (optional), creates quadrilateral mesh. :kwarg reorder: (optional), should the mesh be reordered :kwarg distribution_parameters: options controlling mesh - distribution, see :func:`.Mesh` for details. + distribution, see :func:`Mesh ` for details. :kwarg comm: Optional communicator to build the mesh on. :kwarg diagonal: For triangular meshes, should the diagonal got from bottom left to top right (``"right"``), or top left to @@ -751,7 +750,7 @@ def SquareMesh( The refinement strategy used for non-quadrilateral meshes. Must be one of ``"crossed"``, ``"left"``, ``"right"``. distribution_parameters - Options controlling mesh distribution, see :func:`.Mesh` for details. + Options controlling mesh distribution, see :func:`Mesh ` for details. comm Optional communicator to build the mesh on. name @@ -824,7 +823,7 @@ def UnitSquareMesh( quadrilateral Flag indicating whether to create a quadrilateral mesh. distribution_parameters - Options controlling mesh distribution, see :func:`.Mesh` for details. + Options controlling mesh distribution, see :func:`Mesh ` for details. comm Optional communicator to build the mesh on. name @@ -902,7 +901,7 @@ def PeriodicRectangleMesh( reorder Flag indicating whether to reorder the mesh. distribution_parameters - Options controlling mesh distribution, see :func:`.Mesh` for details. + Options controlling mesh distribution, see :func:`Mesh ` for details. diagonal The refinement strategy used for non-quadrilateral meshes. Must be one of ``"crossed"``, ``"left"``, ``"right"``. @@ -1010,7 +1009,7 @@ def PeriodicSquareMesh( reorder Flag indicating whether to reorder the mesh. distribution_parameters - Options controlling mesh distribution, see :func:`.Mesh` for details. + Options controlling mesh distribution, see :func:`Mesh ` for details. diagonal The refinement strategy used for non-quadrilateral meshes. Must be one of ``"crossed"``, ``"left"``, ``"right"``. @@ -1089,7 +1088,7 @@ def PeriodicUnitSquareMesh( reorder Flag indicating whether to reorder the mesh. distribution_parameters - Options controlling mesh distribution, see :func:`.Mesh` for details. + Options controlling mesh distribution, see :func:`Mesh ` for details. diagonal The refinement strategy used for non-quadrilateral meshes. Must be one of ``"crossed"``, ``"left"``, ``"right"``. @@ -1158,7 +1157,7 @@ def CircleManifoldMesh( :kwarg degree: polynomial degree of coordinate space (e.g., cells are straight line segments if degree=1). :kwarg distribution_parameters: options controlling mesh - distribution, see :func:`.Mesh` for details. + distribution, see :func:`Mesh ` for details. :kwarg reorder: (optional), should the mesh be reordered? :kwarg comm: Optional communicator to build the mesh on. :kwarg name: Optional name of the mesh. @@ -1232,7 +1231,7 @@ def UnitDiskMesh( :kwarg refinement_level: optional number of refinements (0 is a diamond) :kwarg reorder: (optional), should the mesh be reordered? :kwarg distribution_parameters: options controlling mesh - distribution, see :func:`.Mesh` for details. + distribution, see :func:`Mesh ` for details. :kwarg comm: Optional communicator to build the mesh on. :kwarg name: Optional name of the mesh. :kwarg distribution_name: the name of parallel distribution used @@ -1312,7 +1311,7 @@ def UnitBallMesh( :kwarg refinement_level: optional number of refinements (0 is an octahedron) :kwarg reorder: (optional), should the mesh be reordered? :kwarg distribution_parameters: options controlling mesh - distribution, see :func:`.Mesh` for details. + distribution, see :func:`Mesh ` for details. :kwarg comm: Optional MPI communicator to build the mesh on. :kwarg name: Optional name of the mesh. :kwarg distribution_name: the name of parallel distribution used @@ -1436,7 +1435,7 @@ def TensorBoxMesh( :arg ycoords: Location of nodes in the y direction :arg zcoords: Location of nodes in the z direction :kwarg distribution_parameters: options controlling mesh - distribution, see :func:`.Mesh` for details. + distribution, see :func:`Mesh ` for details. :kwarg diagonal: Two ways of cutting hexadra, should be cut into 6 tetrahedra (``"default"``), or 5 tetrahedra thus less biased (``"crossed"``) @@ -1592,7 +1591,7 @@ def BoxMesh( :arg Lz: The extent in the z direction :kwarg hexahedral: (optional), creates hexahedral mesh. :kwarg distribution_parameters: options controlling mesh - distribution, see :func:`.Mesh` for details. + distribution, see :func:`Mesh ` for details. :kwarg diagonal: Two ways of cutting hexadra, should be cut into 6 tetrahedra (``"default"``), or 5 tetrahedra thus less biased (``"crossed"``) @@ -1672,7 +1671,7 @@ def CubeMesh( :kwarg hexahedral: (optional), creates hexahedral mesh. :kwarg reorder: (optional), should the mesh be reordered? :kwarg distribution_parameters: options controlling mesh - distribution, see :func:`.Mesh` for details. + distribution, see :func:`Mesh ` for details. :kwarg comm: Optional communicator to build the mesh on. :kwarg name: Optional name of the mesh. :kwarg distribution_name: the name of parallel distribution used @@ -1729,7 +1728,7 @@ def UnitCubeMesh( :kwarg hexahedral: (optional), creates hexahedral mesh. :kwarg reorder: (optional), should the mesh be reordered? :kwarg distribution_parameters: options controlling mesh - distribution, see :func:`.Mesh` for details. + distribution, see :func:`Mesh ` for details. :kwarg comm: Optional communicator to build the mesh on. :kwarg name: Optional name of the mesh. :kwarg distribution_name: the name of parallel distribution used @@ -1803,7 +1802,7 @@ def PeriodicBoxMesh( reorder : bool or None Whether to reorder the mesh. distribution_parameters : dict or None - Options controlling mesh distribution, see :func:`.Mesh` for details. + Options controlling mesh distribution, see :func:`Mesh ` for details. comm : Communicator to build the mesh on. name : str @@ -1969,7 +1968,7 @@ def PeriodicUnitCubeMesh( reorder : bool or None Should the mesh be reordered? distribution_parameters : dict or None - Options controlling mesh distribution, see :func:`.Mesh` for details. + Options controlling mesh distribution, see :func:`Mesh ` for details. comm : Communicator to build the mesh on. name : str @@ -2048,7 +2047,7 @@ def IcosahedralSphereMesh( flat triangles if degree=1). :kwarg reorder: (optional), should the mesh be reordered? :kwarg distribution_parameters: options controlling mesh - distribution, see :func:`.Mesh` for details. + distribution, see :func:`Mesh ` for details. :kwarg comm: Optional communicator to build the mesh on. :kwarg name: Optional name of the mesh. :kwarg distribution_name: the name of parallel distribution used @@ -2167,7 +2166,7 @@ def UnitIcosahedralSphereMesh( flat triangles if degree=1). :kwarg reorder: (optional), should the mesh be reordered? :kwarg distribution_parameters: options controlling mesh - distribution, see :func:`.Mesh` for details. + distribution, see :func:`Mesh ` for details. :kwarg comm: Optional communicator to build the mesh on. :kwarg name: Optional name of the mesh. :kwarg distribution_name: the name of parallel distribution used @@ -2221,7 +2220,7 @@ def OctahedralSphereMesh( are just pushed out radially from the equivalent P1 mesh. :kwarg reorder: (optional), should the mesh be reordered? :kwarg distribution_parameters: options controlling mesh - distribution, see :func:`.Mesh` for details. + distribution, see :func:`Mesh ` for details. :kwarg comm: Optional communicator to build the mesh on. :kwarg name: Optional name of the mesh. :kwarg distribution_name: the name of parallel distribution used @@ -2373,7 +2372,7 @@ def UnitOctahedralSphereMesh( are just pushed out radially from the equivalent P1 mesh. :kwarg reorder: (optional), should the mesh be reordered? :kwarg distribution_parameters: options controlling mesh - distribution, see :func:`.Mesh` for details. + distribution, see :func:`Mesh ` for details. :kwarg comm: Optional communicator to build the mesh on. :kwarg name: Optional name of the mesh. :kwarg distribution_name: the name of parallel distribution used @@ -2552,7 +2551,7 @@ def CubedSphereMesh( bilinear quads if degree=1). :kwarg reorder: (optional), should the mesh be reordered? :kwarg distribution_parameters: options controlling mesh - distribution, see :func:`.Mesh` for details. + distribution, see :func:`Mesh ` for details. :kwarg comm: Optional communicator to build the mesh on. :kwarg name: Optional name of the mesh. :kwarg distribution_name: the name of parallel distribution used @@ -2619,7 +2618,7 @@ def UnitCubedSphereMesh( bilinear quads if degree=1). :kwarg reorder: (optional), should the mesh be reordered? :kwarg distribution_parameters: options controlling mesh - distribution, see :func:`.Mesh` for details. + distribution, see :func:`Mesh ` for details. :kwarg comm: Optional communicator to build the mesh on. :kwarg name: Optional name of the mesh. :kwarg distribution_name: the name of parallel distribution used @@ -2664,7 +2663,7 @@ def TorusMesh( :kwarg quadrilateral: (optional), creates quadrilateral mesh. :kwarg reorder: (optional), should the mesh be reordered :kwarg distribution_parameters: options controlling mesh - distribution, see :func:`.Mesh` for details. + distribution, see :func:`Mesh ` for details. :kwarg comm: Optional communicator to build the mesh on. :kwarg name: Optional name of the mesh. :kwarg distribution_name: the name of parallel distribution used @@ -2753,7 +2752,7 @@ def AnnulusMesh( :kwarg nr: (optional), number of cells in the radial direction :kwarg nt: (optional), number of cells in the circumferential direction (min 3) :kwarg distribution_parameters: options controlling mesh - distribution, see :func:`.Mesh` for details. + distribution, see :func:`Mesh ` for details. :kwarg comm: Optional communicator to build the mesh on. :kwarg name: Optional name of the mesh. :kwarg distribution_name: the name of parallel distribution used @@ -2805,7 +2804,7 @@ def SolidTorusMesh( :kwarg refinement_level: (optional), number of times the base disk mesh is refined. :kwarg reorder: (optional), should the mesh be reordered :kwarg distribution_parameters: options controlling mesh - distribution, see :func:`.Mesh` for details. + distribution, see :func:`Mesh ` for details. :kwarg comm: Optional communicator to build the mesh on. :kwarg name: Optional name of the mesh. :kwarg distribution_name: the name of parallel distribution used @@ -2867,7 +2866,7 @@ def CylinderMesh( longitudinal axis of the cylinder. :kwarg quadrilateral: (optional), creates quadrilateral mesh. :kwarg distribution_parameters: options controlling mesh - distribution, see :func:`.Mesh` for details. + distribution, see :func:`Mesh ` for details. :kwarg diagonal: (optional), one of ``"crossed"``, ``"left"``, ``"right"``. Not valid for quad meshes. :kwarg comm: Optional communicator to build the mesh on. @@ -3034,7 +3033,7 @@ def PartiallyPeriodicRectangleMesh( :kwarg quadrilateral: (optional), creates quadrilateral mesh. :kwarg reorder: (optional), should the mesh be reordered :kwarg distribution_parameters: options controlling mesh - distribution, see :func:`.Mesh` for details. + distribution, see :func:`Mesh ` for details. :kwarg diagonal: (optional), one of ``"crossed"``, ``"left"``, ``"right"``. Not valid for quad meshes. :kwarg comm: Optional communicator to build the mesh on. diff --git a/firedrake/variational_solver.py b/firedrake/variational_solver.py index 597b5eb9a6..906742ce73 100644 --- a/firedrake/variational_solver.py +++ b/firedrake/variational_solver.py @@ -18,7 +18,7 @@ from functools import cached_property from collections.abc import Callable -__all__ = ["LinearVariationalProblem", "NonlinearVariationalProblem"] +__all__ = ["LinearVariationalProblem"] def check_pde_args(F, J, Jp, E=None): @@ -187,7 +187,7 @@ def rediscretise(self, An optional callable ``form_transform(form, coefficient_mapping)`` used instead of `ufl.replace` to reconstruct each UFL form. homogenize_bcs - Whether to homogenize the :class:`~.DirichletBC` values. + Whether to homogenize the :class:`DirichletBC ` values. Returns ------- @@ -502,14 +502,14 @@ def solve(self, bounds=None): ---------- bounds : tuple of firedrake.function.Function Optional bounds on the solution, given as ``(lower, upper)``. - ``lower`` and ``upper`` must both be :class:`~.Function`\s. + ``lower`` and ``upper`` must both be :class:`function `\s. Returns ------- firedrake.function.Function The (possibly adapted) solution. If the solver performed mesh adaptation during the solve, this is the solution - :class:`~.Function` on the adapted mesh, which may differ + :class:`function ` on the adapted mesh, which may differ from the ``u`` that was passed in to the :class:`.NonlinearVariationalProblem`. From ab5c79076091dfdebb90d6552edebc94cbee111a Mon Sep 17 00:00:00 2001 From: nwng04 Date: Thu, 3 Sep 2026 21:24:05 +0100 Subject: [PATCH 21/28] Amend module locations --- demos/burgers/burgers.py.rst | 8 +++---- demos/camassa-holm/camassaholm.py.rst | 2 +- .../full_waveform_inversion.py.rst | 4 ++-- .../qg_1layer_wave.py.rst | 2 +- docs/source/visualisation.rst | 22 +++++++++---------- 5 files changed, 19 insertions(+), 19 deletions(-) diff --git a/demos/burgers/burgers.py.rst b/demos/burgers/burgers.py.rst index 6ee2d7bacf..d0714fffdd 100644 --- a/demos/burgers/burgers.py.rst +++ b/demos/burgers/burgers.py.rst @@ -93,12 +93,12 @@ We now create an object for output visualisation:: Output only supports visualisation of linear fields (either P1, or P1DG). In this example we project to a linear space by hand. Another -option is to let the :class:`VTKFile ` object manage the +option is to let the :class:`VTKFile ` object manage the decimation. It supports both interpolation to linears (the default) or projection (by passing ``project_output=True`` when creating the -:class:`VTKFile `). Outputting data is carried out using -the :meth:`write ` method of -:class:`VTKFile ` objects:: +:class:`VTKFile `). Outputting data is carried out using +the :meth:`write ` method of +:class:`VTKFile ` objects:: outfile.write(project(u, V_out, name="Velocity")) diff --git a/demos/camassa-holm/camassaholm.py.rst b/demos/camassa-holm/camassaholm.py.rst index 1342ac3657..3f5aa86c63 100644 --- a/demos/camassa-holm/camassaholm.py.rst +++ b/demos/camassa-holm/camassaholm.py.rst @@ -168,7 +168,7 @@ e.g. for output. :: m0, u0 = w0.subfunctions m1, u1 = w1.subfunctions -We choose a final time, and initialise a :class:`VTKFile ` +We choose a final time, and initialise a :class:`VTKFile ` object for storing ``u``. as well as an array for storing the function to be visualised:: diff --git a/demos/full_waveform_inversion/full_waveform_inversion.py.rst b/demos/full_waveform_inversion/full_waveform_inversion.py.rst index 7be18c938a..87586c6b40 100644 --- a/demos/full_waveform_inversion/full_waveform_inversion.py.rst +++ b/demos/full_waveform_inversion/full_waveform_inversion.py.rst @@ -278,7 +278,7 @@ To have the step 4, we need first to tape the forward problem. That is done by c misfit = guess_receiver - true_data_receivers[step] J_val += 0.5 * assemble(inner(misfit, misfit) * dx) -We now instantiate :class:`EnsembleReducedFunctional `:: +We now instantiate :class:~.EnsembleReducedFunctional`:: J_hat = EnsembleReducedFunctional(J_val, Control(c_guess, riesz_map="l2"), @@ -289,7 +289,7 @@ where the :math:`J_s` and its gradients :math:`\nabla_{\mathtt{c\_guess}} J_s` a based on the ``my_ensemble`` configuration. -**Steps 4-6**: The instance of the :class:`EnsembleReducedFunctional `, named ``J_hat``, +**Steps 4-6**: The instance of the :class:~.EnsembleReducedFunctional`, named ``J_hat``, is then passed as an argument to the ``minimize`` function. The default ``minimize`` function uses ``scipy.minimize``, and wraps the ``ReducedFunctional`` in a ``ReducedFunctionalNumPy`` that handles transferring data between Firedrake and numpy data structures. However, because diff --git a/demos/quasigeostrophy_1layer/qg_1layer_wave.py.rst b/demos/quasigeostrophy_1layer/qg_1layer_wave.py.rst index a998d6f44f..5704fa28e7 100644 --- a/demos/quasigeostrophy_1layer/qg_1layer_wave.py.rst +++ b/demos/quasigeostrophy_1layer/qg_1layer_wave.py.rst @@ -195,7 +195,7 @@ fill. :: "sub_pc_type": "ilu"}) To visualise the output of the simulation, we create a -:class:`VTKFile ` object. To which we can store multiple +:class:`VTKFile ` object. To which we can store multiple :class:`function `\s. So that we can distinguish between them we will give them descriptive names. :: diff --git a/docs/source/visualisation.rst b/docs/source/visualisation.rst index f1bf206f92..f7c6639ea9 100644 --- a/docs/source/visualisation.rst +++ b/docs/source/visualisation.rst @@ -16,7 +16,7 @@ Creating output files ~~~~~~~~~~~~~~~~~~~~~ Output for visualisation purposes is managed with a -:class:`VTKFile ` object. To create one, first import the +:class:`VTKFile ` object. To create one, first import the class from `firedrake.output`, then we just need to pass the name of the output file on disk. The file Firedrake creates is in PVD and therefore the requested file name must end in ``.pvd``. @@ -27,8 +27,8 @@ therefore the requested file name must end in ``.pvd``. # The following raises an error badfile = VTKFile("output.vtu") -To save functions to the :class:`VTKFile ` we use the -:meth:`write ` method. +To save functions to the :class:`VTKFile ` we use the +:meth:`write ` method. .. code-block:: python3 @@ -53,8 +53,8 @@ Saving time-dependent data Often, we have a time-dependent simulation and would like to save the same function at multiple timesteps. This is straightforward, we must -create the output :class:`VTKFile ` outside the time loop -and call :meth:`write ` inside. +create the output :class:`VTKFile ` outside the time loop +and call :meth:`write ` inside. .. code-block:: python3 @@ -69,9 +69,9 @@ and call :meth:`write ` inside. The PVD data format supports specifying the timestep value for time-dependent data. We do not have to provide it to -:meth:`write `, by default an integer counter is +:meth:`write `, by default an integer counter is used that is incremented by 1 each time -:meth:`write ` is called. It is possible to +:meth:`write ` is called. It is possible to override this by passing the keyword argument ``time``. .. code-block:: python3 @@ -99,7 +99,7 @@ the data to this format first. One option is to do so by hand before outputting. Either by :doc:`interpolating ` or else :func:`projecting ` the :doc:`mesh coordinates ` and then the field. Since this is such -a common operation, the :class:`VTKFile ` object is set up +a common operation, the :class:`VTKFile ` object is set up to manage these operations automatically, we just need to choose whether we want data to be interpolated or projected. The default is to use interpolation. For example, assume we wish to output a @@ -127,7 +127,7 @@ If instead we want projection, we use use an older version of Paraview, you must manually interpolate mesh coordinates and field coordinates to a piecewise linear function space, represented with either a Lagrange (H1) or discontinuous - Lagrange (L2) basis. The :class:`VTKFile ` is also setup + Lagrange (L2) basis. The :class:`VTKFile ` is also setup to manage this issue. For instance, we can force the output to be discontinuous piecewise linears via @@ -197,7 +197,7 @@ pressure in a fluids models. This is possible either by having a separate output file for each field, or by saving multiple fields to the same output file. The latter may be more convenient for subsequent analysis. To do this, we just need to pass multiple -:class:`function `\s to :meth:`write `. +:class:`function `\s to :meth:`write `. .. code-block:: python3 @@ -376,7 +376,7 @@ Last but not least, vector fields defined on a vertex-only mesh can be visualise Writing vertex-only mesh data to VTK ++++++++++++++++++++++++++++++++++++ -Vertex-only mesh data can be written to VTK output enabling point data visualisations in third-party software such as ParaView. A :class:`VTKFile ` accepts :class:`function `\s +Vertex-only mesh data can be written to VTK output enabling point data visualisations in third-party software such as ParaView. A :class:`VTKFile ` accepts :class:`function `\s defined on a :func:`firedrake.VertexOnlyMesh` in the same way as functions defined on ordinary meshes. The output includes the point coordinates, the values of any supplied function(s), and a persistent particle ID field. In ParaView, for instance, this ID field can be used to colour particles by identity. From 0f838f4d6a1ef0e9fb357a6f3a3a81cc31e017f2 Mon Sep 17 00:00:00 2001 From: nwng04 Date: Sat, 5 Sep 2026 08:43:52 +0100 Subject: [PATCH 22/28] Update utils inport with complex_mode --- firedrake/mesh.py | 2 +- firedrake/pointeval_utils.py | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/firedrake/mesh.py b/firedrake/mesh.py index 20196596f8..b98aa72892 100644 --- a/firedrake/mesh.py +++ b/firedrake/mesh.py @@ -38,7 +38,7 @@ import firedrake.extrusion_utils as eutils import firedrake.cython.rtree as rtree import firedrake.utils as utils -from firedrake.utils import IntType, IntType_c, RealType, RealType_c, as_ctypes, cached_property_until +from firedrake.utils import IntType, IntType_c, RealType, RealType_c, as_ctypes, cached_property_until, complex_mode from firedrake.logging import logger from firedrake.parameters import parameters from firedrake.petsc import PETSc, DEFAULT_PARTITIONER diff --git a/firedrake/pointeval_utils.py b/firedrake/pointeval_utils.py index da8bac0d03..466b9b0025 100644 --- a/firedrake/pointeval_utils.py +++ b/firedrake/pointeval_utils.py @@ -1,5 +1,5 @@ import loopy as lp -from firedrake.utils import IntType, as_cstr +from firedrake.utils import IntType, as_cstr, complex_mode from finat.element_factory import as_fiat_cell from finat.point_set import UnknownPointSet From 68d753e07a0c65781c07cd598bb12553fb1c5a60 Mon Sep 17 00:00:00 2001 From: nwng04 Date: Sat, 5 Sep 2026 09:03:39 +0100 Subject: [PATCH 23/28] Fix imports in tests --- firedrake/pointeval_utils.py | 2 +- tests/firedrake/adjoint/test_ensemble_reduced_functional.py | 1 + tests/firedrake/multigrid/test_non_nested.py | 1 + tests/firedrake/multigrid/test_poisson_gmg.py | 1 + tests/firedrake/multigrid/test_transfer_manager.py | 1 + tests/firedrake/regression/test_2dcohomology.py | 1 + tests/firedrake/regression/test_appctx_cleanup.py | 1 + tests/firedrake/vertexonly/test_point_eval_immersed_manifold.py | 1 + 8 files changed, 8 insertions(+), 1 deletion(-) diff --git a/firedrake/pointeval_utils.py b/firedrake/pointeval_utils.py index 466b9b0025..da8bac0d03 100644 --- a/firedrake/pointeval_utils.py +++ b/firedrake/pointeval_utils.py @@ -1,5 +1,5 @@ import loopy as lp -from firedrake.utils import IntType, as_cstr, complex_mode +from firedrake.utils import IntType, as_cstr from finat.element_factory import as_fiat_cell from finat.point_set import UnknownPointSet diff --git a/tests/firedrake/adjoint/test_ensemble_reduced_functional.py b/tests/firedrake/adjoint/test_ensemble_reduced_functional.py index bd654ed52d..ea88f1b6fd 100644 --- a/tests/firedrake/adjoint/test_ensemble_reduced_functional.py +++ b/tests/firedrake/adjoint/test_ensemble_reduced_functional.py @@ -1,4 +1,5 @@ from firedrake import * +from firedrake import function from firedrake.adjoint import * from pyadjoint.reduced_functional_numpy import ReducedFunctionalNumPy import pytest diff --git a/tests/firedrake/multigrid/test_non_nested.py b/tests/firedrake/multigrid/test_non_nested.py index ac2008f60e..82ef136003 100644 --- a/tests/firedrake/multigrid/test_non_nested.py +++ b/tests/firedrake/multigrid/test_non_nested.py @@ -1,4 +1,5 @@ from firedrake import * +from firedrake import dmhooks from firedrake.mg.ufl_utils import coarsen as symbolic_coarsen from firedrake.petsc import DEFAULT_DIRECT_SOLVER_PARAMETERS from functools import singledispatch diff --git a/tests/firedrake/multigrid/test_poisson_gmg.py b/tests/firedrake/multigrid/test_poisson_gmg.py index f6629299be..4a2b85f8c3 100644 --- a/tests/firedrake/multigrid/test_poisson_gmg.py +++ b/tests/firedrake/multigrid/test_poisson_gmg.py @@ -1,4 +1,5 @@ from firedrake import * +from firedrake import function import numpy import pytest import warnings diff --git a/tests/firedrake/multigrid/test_transfer_manager.py b/tests/firedrake/multigrid/test_transfer_manager.py index 4e0dde7c07..4b36bbd264 100644 --- a/tests/firedrake/multigrid/test_transfer_manager.py +++ b/tests/firedrake/multigrid/test_transfer_manager.py @@ -2,6 +2,7 @@ import numpy import warnings from firedrake import * +from firedrake import dmhooks from firedrake.mg.ufl_utils import coarsen from firedrake.utils import complex_mode diff --git a/tests/firedrake/regression/test_2dcohomology.py b/tests/firedrake/regression/test_2dcohomology.py index 85ad069924..30fe5ca5d0 100644 --- a/tests/firedrake/regression/test_2dcohomology.py +++ b/tests/firedrake/regression/test_2dcohomology.py @@ -13,6 +13,7 @@ import numpy.linalg as linalg import numpy from firedrake import * +from firedrake import utils import pytest cwd = abspath(dirname(__file__)) diff --git a/tests/firedrake/regression/test_appctx_cleanup.py b/tests/firedrake/regression/test_appctx_cleanup.py index 7beb9868c9..f8da9d2467 100644 --- a/tests/firedrake/regression/test_appctx_cleanup.py +++ b/tests/firedrake/regression/test_appctx_cleanup.py @@ -1,5 +1,6 @@ import numpy from firedrake import * +from firedrake import dmhooks class NonePC(PCBase): diff --git a/tests/firedrake/vertexonly/test_point_eval_immersed_manifold.py b/tests/firedrake/vertexonly/test_point_eval_immersed_manifold.py index 51316c274a..9b25f7eb0e 100644 --- a/tests/firedrake/vertexonly/test_point_eval_immersed_manifold.py +++ b/tests/firedrake/vertexonly/test_point_eval_immersed_manifold.py @@ -1,4 +1,5 @@ from firedrake import * +from firedrake import function import numpy as np From e7f49f123fe11f2d3beaf00240b6158de855f561 Mon Sep 17 00:00:00 2001 From: nwng04 Date: Sat, 5 Sep 2026 09:20:01 +0100 Subject: [PATCH 24/28] Further refine references to modules in firedrake --- demos/burgers/burgers.py.rst | 8 ++-- demos/camassa-holm/camassaholm.py.rst | 2 +- .../linear_wave_equation.py.rst | 2 +- demos/matrix_free/poisson.py.rst | 2 +- demos/matrix_free/stokes.py.rst | 2 +- .../qg_1layer_wave.py.rst | 2 +- .../saddle_point_systems.py.rst | 2 +- docs/source/ensemble_parallelism.rst | 40 +++++++++---------- docs/source/external_operators.rst | 16 ++++---- docs/source/extruded-meshes.rst | 2 +- docs/source/matrix-free.rst | 2 +- docs/source/mesh-coordinates.rst | 4 +- docs/source/parallelism.rst | 4 +- docs/source/point-evaluation.rst | 2 +- docs/source/preconditioning.rst | 6 +-- docs/source/variational-problems.rst | 8 ++-- docs/source/visualisation.rst | 22 +++++----- .../adjoint/ensemble_reduced_functional.py | 6 +-- firedrake/bcs.py | 2 +- firedrake/cofunction.py | 2 +- firedrake/ensemble/ensemble_function.py | 24 +++++------ firedrake/ensemble/ensemble_functionspace.py | 16 ++++---- firedrake/ensemble/ensemble_mat.py | 10 ++--- firedrake/ensemble/ensemble_pc.py | 12 +++--- .../abstract_external_operators.py | 8 ++-- .../external_operators/point_expr_operator.py | 2 +- firedrake/function.py | 2 +- firedrake/linear_solver.py | 4 +- firedrake/mg/mesh.py | 2 +- firedrake/ml/jax/fem_operator.py | 2 +- firedrake/ml/pytorch/fem_operator.py | 2 +- firedrake/nullspace.py | 6 +-- firedrake/parloops.py | 6 +-- firedrake/preconditioners/auxiliary_snes.py | 2 +- firedrake/solving.py | 4 +- 35 files changed, 119 insertions(+), 119 deletions(-) diff --git a/demos/burgers/burgers.py.rst b/demos/burgers/burgers.py.rst index d0714fffdd..9bb131b096 100644 --- a/demos/burgers/burgers.py.rst +++ b/demos/burgers/burgers.py.rst @@ -93,12 +93,12 @@ We now create an object for output visualisation:: Output only supports visualisation of linear fields (either P1, or P1DG). In this example we project to a linear space by hand. Another -option is to let the :class:`VTKFile ` object manage the +option is to let the :class:`~.output.VTKFile` object manage the decimation. It supports both interpolation to linears (the default) or projection (by passing ``project_output=True`` when creating the -:class:`VTKFile `). Outputting data is carried out using -the :meth:`write ` method of -:class:`VTKFile ` objects:: +:class:`~.output.VTKFile`). Outputting data is carried out using +the :meth:`~.output.VTKFile.write` method of +:class:`~.output.VTKFile` objects:: outfile.write(project(u, V_out, name="Velocity")) diff --git a/demos/camassa-holm/camassaholm.py.rst b/demos/camassa-holm/camassaholm.py.rst index 3f5aa86c63..ebbec61807 100644 --- a/demos/camassa-holm/camassaholm.py.rst +++ b/demos/camassa-holm/camassaholm.py.rst @@ -168,7 +168,7 @@ e.g. for output. :: m0, u0 = w0.subfunctions m1, u1 = w1.subfunctions -We choose a final time, and initialise a :class:`VTKFile ` +We choose a final time, and initialise a :class:`~.output.VTKFile` object for storing ``u``. as well as an array for storing the function to be visualised:: diff --git a/demos/linear-wave-equation/linear_wave_equation.py.rst b/demos/linear-wave-equation/linear_wave_equation.py.rst index ecd876495c..63134fc7eb 100644 --- a/demos/linear-wave-equation/linear_wave_equation.py.rst +++ b/demos/linear-wave-equation/linear_wave_equation.py.rst @@ -70,7 +70,7 @@ Output the initial conditions:: outfile.write(phi) We next establish a boundary condition object. Since we have time-dependent -boundary conditions, we first create a :class:`.Constant` to hold the +boundary conditions, we first create a :class:`Constant ` to hold the value and use that:: bcval = Constant(0.0) diff --git a/demos/matrix_free/poisson.py.rst b/demos/matrix_free/poisson.py.rst index 7912930f36..03c61c5997 100644 --- a/demos/matrix_free/poisson.py.rst +++ b/demos/matrix_free/poisson.py.rst @@ -46,7 +46,7 @@ unassembled operator using the ``"mat_type"`` solver parameter.:: "pc_type": "none", "ksp_monitor": None}) -Finally, we demonstrate the use of a :class:`.AssembledPC` +Finally, we demonstrate the use of a :class:`AssembledPC ` preconditioner. This uses matrix-free actions but preconditions the Krylov iterations with an incomplete LU factorisation of the assembled operator.:: diff --git a/demos/matrix_free/stokes.py.rst b/demos/matrix_free/stokes.py.rst index 8a7c29be3b..45296f628e 100644 --- a/demos/matrix_free/stokes.py.rst +++ b/demos/matrix_free/stokes.py.rst @@ -87,7 +87,7 @@ the configured Krylov solver object.:: "pc_fieldsplit_schur_fact_type": "diag", Next we configure the solvers for the blocks. For the velocity block, -we use an :class:`.AssembledPC` and approximate the inverse of the +we use an :class:`AssembledPC ` and approximate the inverse of the vector laplacian using a single multigrid V-cycle.:: "fieldsplit_0_ksp_type": "preonly", diff --git a/demos/quasigeostrophy_1layer/qg_1layer_wave.py.rst b/demos/quasigeostrophy_1layer/qg_1layer_wave.py.rst index 5704fa28e7..22a2310774 100644 --- a/demos/quasigeostrophy_1layer/qg_1layer_wave.py.rst +++ b/demos/quasigeostrophy_1layer/qg_1layer_wave.py.rst @@ -195,7 +195,7 @@ fill. :: "sub_pc_type": "ilu"}) To visualise the output of the simulation, we create a -:class:`VTKFile ` object. To which we can store multiple +:class:`~.output.VTKFile` object. To which we can store multiple :class:`function `\s. So that we can distinguish between them we will give them descriptive names. :: diff --git a/demos/saddle_point_pc/saddle_point_systems.py.rst b/demos/saddle_point_pc/saddle_point_systems.py.rst index b29e467e92..bb8eb2cbdd 100644 --- a/demos/saddle_point_pc/saddle_point_systems.py.rst +++ b/demos/saddle_point_pc/saddle_point_systems.py.rst @@ -590,7 +590,7 @@ Let's see what the iteration count looks like now. :: Firedrake provides some facility to solve the :math:`H(\mathrm{div})` Riesz map in a scalable way. In particular either by employing a geometric multigrid method with overlapping Schwarz smoothers (using -:class:`.PatchPC`), or using the algebraic approach of +:class:`PatchPC `), or using the algebraic approach of :cite:`Hiptmair:2007` provided by `Hypre's `__ "auxiliary space" preconditioners ``AMS`` and ``ADS``. See the separate manual page on diff --git a/docs/source/ensemble_parallelism.rst b/docs/source/ensemble_parallelism.rst index a53a67ac9d..1fc46a2be2 100644 --- a/docs/source/ensemble_parallelism.rst +++ b/docs/source/ensemble_parallelism.rst @@ -35,10 +35,10 @@ Cartesian product over the original global communicator. The additional functionality required to support ensemble parallelism is the ability to send instances of :class:`function ` from one -ensemble to another. This is handled by the :class:`firedrake.Ensemble` class. +ensemble to another. This is handled by the :class:`~.ensemble` class. Each ensemble member must have the same spatial parallel domain decomposition, so -instantiating an :class:`firedrake.Ensemble` requires a communicator to split +instantiating an :class:`~.ensemble` requires a communicator to split (usually, but not necessarily, ``MPI_COMM_WORLD``) plus the number of MPI processes to be used in each member of the ensemble (5 in the figure above, and 2 in the example code below). The number of ensemble @@ -78,7 +78,7 @@ The ensemble sub-communicator is then available through the attribute MPI communications across the spatial sub-communicator (i.e., within an ensemble member) are handled automatically by Firedrake, whilst MPI communications across the ensemble sub-communicator (i.e., between ensemble -members) are handled through methods of :class:`firedrake.Ensemble`. Currently +members) are handled through methods of :class:`~.ensemble`. Currently send/recv, reductions and broadcasts are supported, as well as their non-blocking variants. The rank of the the ensemble member (``my_ensemble.ensemble_comm.rank``) @@ -115,26 +115,26 @@ timeseries, and each timestep may live on a separate ensemble member. In this case we want to treat the entire timeseries as a single object. -Firedrake implements this using :class:`firedrake.EnsembleFunctionSpace` -and :class:`firedrake.EnsembleFunction` (along with the dual objects -:class:`firedrake.EnsembleDualSpace` and :class:`firedrake.EnsembleCofunction`). -The :class:`firedrake.EnsembleFunctionSpace` can be thought of as a mixed +Firedrake implements this using :class:`~.ensembleFunctionSpace` +and :class:`~.ensembleFunction` (along with the dual objects +:class:`~.ensembleDualSpace` and :class:`~.ensembleCofunction`). +The :class:`~.ensembleFunctionSpace` can be thought of as a mixed function space which is parallelised across the `components`, as opposed to just being parallelised in `space`, as would usually be the case with :func:`function space `. Each component of an -:class:`firedrake.EnsembleFunctionSpace` is a Firedrake :func:`function space ` +:class:`~.ensembleFunctionSpace` is a Firedrake :func:`function space ` on a single spatial communicator. -To create an :class:`firedrake.EnsembleFunctionSpace` you must provide an -:class:`firedrake.Ensemble` and, on each spatial communicator, a list of +To create an :class:`~.ensembleFunctionSpace` you must provide an +:class:`~.ensemble` and, on each spatial communicator, a list of :func:`function space ` instances for the components on the local ``Ensemble.comm``. There can be a different number of local :func:`function space ` on each ``Ensemble.comm``. In the example -below we create an :class:`firedrake.EnsembleFunctionSpace` with two +below we create an :class:`~.ensembleFunctionSpace` with two components on the first ensemble member, and three components on every other ensemble member. Note that, unlike a :func:`function space `, a component of an -:class:`firedrake.EnsembleFunctionSpace` may itself be a +:class:`~.ensembleFunctionSpace` may itself be a :func:`MixedFunctionSpace `. .. literalinclude:: ../../tests/firedrake/ensemble/test_ensemble_manual.py @@ -145,14 +145,14 @@ every other ensemble member. Note that, unlike a Analogously to accessing the components of a :func:`MixedFunctionSpace ` using ``subspaces``, the :func:`function space ` for each local component -of an :class:`firedrake.EnsembleFunctionSpace` can be accessed via +of an :class:`~.ensembleFunctionSpace` can be accessed via ``EnsembleFunctionSpace.local_spaces``. Various other methods and -properties such as ``dual`` (to create an :class:`firedrake.EnsembleDualSpace`) +properties such as ``dual`` (to create an :class:`~.ensembleDualSpace`) and ``nglobal_spaces`` (total number of components across all ranks) are also available. -An :class:`firedrake.EnsembleFunction` and :class:`firedrake.EnsembleCofunction` can be -created from the :class:`firedrake.EnsembleFunctionSpace`. These have a ``subfunctions`` +An :class:`~.ensembleFunction` and :class:`~.ensembleCofunction` can be +created from the :class:`~.ensembleFunctionSpace`. These have a ``subfunctions`` property that can be used to access the components on the local ensemble member. Each element in ``EnsembleFunction.subfunctions`` is itself just a normal Firedrake :class:`function `. If a component of the @@ -166,7 +166,7 @@ that ``MixedFunctionSpace``. :start-after: [test_ensemble_manual_example 6 >] :end-before: [test_ensemble_manual_example 6 <] -:class:`firedrake.EnsembleFunction` and :class:`firedrake.EnsembleCofunction` have +:class:`~.ensembleFunction` and :class:`~.ensembleCofunction` have a range of methods equivalent to those of :class:`function ` and :class:`Cofunction `, such as ``assign``, ``zero``, ``riesz_representation``, arithmetic operators e.g. ``+``, ``+=``, @@ -177,9 +177,9 @@ Because the components in ``EnsembleFunction.subfunctions`` (:class:`Cofunction `) instances, they can be used directly with variational forms and solvers. In the example code below, We create a :class:`linear variational solver ` where the right -hand side is a component of an :class:`firedrake.EnsembleCofunction`, +hand side is a component of an :class:`~.ensembleCofunction`, and the solution is written into a component of an -:class:`firedrake.EnsembleFunction`. Using the ``subfunctions`` +:class:`~.ensembleFunction`. Using the ``subfunctions`` directly like this can simplify ensemble code and reduce unnecessary copies. Note that the ``options_prefix`` is set using both the local ensemble @@ -201,7 +201,7 @@ on each ensemble member. ``EnsembleCofunction`` themselves do not carry any symbolic information so cannot be used in UFL expressions. -Internally, the :class:`firedrake.EnsembleFunction` creates a ``PETSc.Vec`` +Internally, the :class:`~.ensembleFunction` creates a ``PETSc.Vec`` on the ``Ensemble.global_comm`` which contains the data for all local components on all ensemble members. This ``Vec`` can be accessed with a context manager, similarly to the ``Function.dat.vec`` context diff --git a/docs/source/external_operators.rst b/docs/source/external_operators.rst index 5f7b5d0f87..613ae5b08f 100644 --- a/docs/source/external_operators.rst +++ b/docs/source/external_operators.rst @@ -13,7 +13,7 @@ operators, such as machine learning models, into PDE or PDE-constrained optimisa We refer to these operators as *external operators*, as their implementation is left to be specified by the user, i.e "external" with respect to Firedrake. -External operators are represented by the :class:`~.AbstractExternalOperator` base class, +External operators are represented by the :class:`AbstractExternalOperator ` base class, which can be subclassed for defining specific operators. While the base class documentation provides the syntax, this document introduces the external operator abstraction in more detail and explains what you need to do if you want to define your own external operator. The external operator @@ -53,7 +53,7 @@ its *argument*, it can be nonlinear with respect to `u`, its *operand*. In Fired be a :class:`function ` object, and `v^{*}` a :class:`firedrake.Coargument` object. Arbitrary UFL expressions defined on arbitrary finite element spaces, i.e. other than `V`, can also -be passed as operands to the external operator using the symbolic :class:`~.Interpolate` operator. +be passed as operands to the external operator using the symbolic :class:`Interpolate ` operator. .. _differentiation: @@ -149,7 +149,7 @@ In this DAG representation, external operators are considered as distinct nodes, implementation is, by definition, left to be specified by the user. Consequently, in order to evaluate the expression of interest, we need a mechanism to map the assembly of the external operator nodes in the DAG to the corresponding implementation specified by the user. This stage is -referred to as the *external operator assembly*. This is achieved by the :class:`~.AbstractExternalOperator` +referred to as the *external operator assembly*. This is achieved by the :class:`AbstractExternalOperator ` base class, whose main role is to orchestrate the external operator assembly. Depending on the specific use case considered, one may need to specify one or more @@ -175,7 +175,7 @@ see :ref:`previous section `. Finally, the number of arguments of an external operator also determines the type of its output after being assembled. For instance, given that an external operator with one argument is a 1-form, its assembly would result in a :class:`function ` or a :class:`Cofunction `. Similarly, an external operator -with two arguments, i.e. a 2-form, would produce a :class:`~.MatrixBase` object. The following table +with two arguments, i.e. a 2-form, would produce a :class:`MatrixBase ` object. The following table illustrates an external operator `N` with two operands, `N \colon V \times V \times V^{*} \rightarrow \mathbb{R}`, along with the external operators resulting from different symbolic operations on it, such as differentiation or action/adjoint. @@ -196,12 +196,12 @@ Build your own external operator -------------------------------- External operators can be used to incorporate arbitrary operators within Firedrake. Some external -operators are already implemented, such as the :class:`~.MLOperator` for embedding machine learning +operators are already implemented, such as the :class:`MLOperator ` for embedding machine learning models within Firedrake, whose implementation is explained in more detail in :cite:`Bouziani2021` and :cite:`Bouziani2024`. However, you may want to build your own external operator for your specific problem. In this section, we discuss how new external operators can be defined. -To define a new external operator, one first needs to subclass the :class:`~.AbstractExternalOperator` +To define a new external operator, one first needs to subclass the :class:`AbstractExternalOperator ` class. Then, the external operator subclass needs to be equipped with methods specifying how the different types of external operator arising in the PDE system considered can be evaluated, such as the Jacobian of the operator. Note that you only need to specify the evaluation methods required for your @@ -303,12 +303,12 @@ Note that building an external operator for the above operation is, in practice, can already be readily implemented using Firedrake's built-in functionalities. Also, because this translation operation is fully defined in Firedrake, the evaluation methods of the external operator we will build rely on Firedrake code. However, the external operator evaluation methods can contain any Python -code as long as they return compatible objects, e.g. :class:`function ` or :class:`~.MatrixBase` objects. +code as long as they return compatible objects, e.g. :class:`function ` or :class:`MatrixBase ` objects. `N` takes in two operands `f, u \in V` and one argument `v^{*} \in V^{*}`. When assembled, this external operator returns a :class:`function ` in `V` since the linear form `N` can also be seen as an operator mapping to `V`, as :ref:`previously discussed `. To construct `N`, -we need to subclass the :class:`~.AbstractExternalOperator` class and specify how `N` can be assembled. +we need to subclass the :class:`AbstractExternalOperator ` class and specify how `N` can be assembled. Given that `N` has `(0,)` as derivative multi-index and that it only has one argument, the translation operator subclass can be defined as: diff --git a/docs/source/extruded-meshes.rst b/docs/source/extruded-meshes.rst index 1ac15be1c1..eb7f311a13 100644 --- a/docs/source/extruded-meshes.rst +++ b/docs/source/extruded-meshes.rst @@ -82,7 +82,7 @@ Uniform extrusion adds another spatial dimension to the mesh. For example, a are computed on the assumption that the layers are evenly spaced (hence the word 'uniform'). -Let ``m`` be a standard :py:func:`~.UnitSquareMesh`. The following code +Let ``m`` be a standard :py:func:`UnitSquareMesh `. The following code produces the extruded mesh, whose base mesh is ``m``, with 5 mesh layers and a layer thickness of 0.2: diff --git a/docs/source/matrix-free.rst b/docs/source/matrix-free.rst index 3e19bdb325..ba2e4cc5a6 100644 --- a/docs/source/matrix-free.rst +++ b/docs/source/matrix-free.rst @@ -58,7 +58,7 @@ As well as providing symbolic field splitting, the preconditioners. Since it contains a complete UFL description of the bilinear form, preconditioners can query or manipulate it as desired. As a particularly simple example, the class -:class:`.AssembledPC` simply passes the UFL into :func:`.assemble` +:class:`AssembledPC ` simply passes the UFL into :func:`.assemble` to produce an explicit matrix during set up. It also sets up a new PETSc PC context acting on this assembled matrix so that the user can configure it at run-time via the options database. This allows the diff --git a/docs/source/mesh-coordinates.rst b/docs/source/mesh-coordinates.rst index f43c4c2973..a7472d38a7 100644 --- a/docs/source/mesh-coordinates.rst +++ b/docs/source/mesh-coordinates.rst @@ -65,7 +65,7 @@ mesh object from a field `f`: coordinate values and coordinate function space are from `f`. The coordinate function space must be a rank-1 :py:class:`FunctionSpace `, constructed either with -:py:func:`~.VectorFunctionSpace`, or by providing a +:py:func:`VectorFunctionSpace `, or by providing a :py:class:`~ufl.classes.VectorElement` to :py:func:`function space `. For efficiency, the new mesh object shares data with `f`. That is, changing the values of `f` will change the coordinate values of the @@ -91,7 +91,7 @@ a lower dimensional mesh in a higher dimension, for example to create a mesh of a two-dimensional manifold immersed in 3D. This is accomplished by setting the value dimension of the new -:py:func:`~.VectorFunctionSpace` to that of the space in which it should be +:py:func:`VectorFunctionSpace ` to that of the space in which it should be immersed. For example, a mesh of square bent into a sine wave using linear (flat) elements can be created with: diff --git a/docs/source/parallelism.rst b/docs/source/parallelism.rst index ac55358ef3..fb58342992 100644 --- a/docs/source/parallelism.rst +++ b/docs/source/parallelism.rst @@ -87,10 +87,10 @@ different simulations on the two halves we would write. .. note:: If you need to create Firedrake meshes on different communicators, - then usually the best approach is to use the :class:`firedrake.Ensemble`, + then usually the best approach is to use the :class:`~.ensemble`, which manages splitting MPI communicators and communicating :class:`function ` objects between the split communicators. More - information on using the :class:`firedrake.Ensemble` can be found + information on using the :class:`~.ensemble` can be found :doc:`here `. To access the communicator a mesh was created on, we can use the diff --git a/docs/source/point-evaluation.rst b/docs/source/point-evaluation.rst index 70966531a9..2cc35cd52f 100644 --- a/docs/source/point-evaluation.rst +++ b/docs/source/point-evaluation.rst @@ -59,7 +59,7 @@ Vector and tensor valued function spaces When interpolating from vector or tensor valued function spaces, the P0DG function space on the vertex-only mesh must be a -:py:func:`~.VectorFunctionSpace` or :py:func:`~.TensorFunctionSpace` +:py:func:`VectorFunctionSpace ` or :py:func:`~.TensorFunctionSpace` respectively. For example: .. code-block:: python3 diff --git a/docs/source/preconditioning.rst b/docs/source/preconditioning.rst index f0eeb84b9e..021b9df887 100644 --- a/docs/source/preconditioning.rst +++ b/docs/source/preconditioning.rst @@ -57,14 +57,14 @@ be used with both sparse matrices and Firedrake's :doc:`matrix-free operators `, and can be applied either additively or multiplicatively within an MPI rank and additively between ranks. -:class:`.PatchPC` +:class:`PatchPC ` Small-block overlapping Schwarz smoother with topological definition of patches. Does not support extruded meshes. :class:`.PatchSNES` Nonlinear overlapping Schwarz smoother with topological definition of patches. Does not support extruded meshes. :class:`.PlaneSmoother` - A Python construction class for :class:`.PatchPC` and + A Python construction class for :class:`PatchPC ` and :class:`.PatchSNES` that approximately groups mesh entities into lines or planes (useful for advection-dominated problems). @@ -132,7 +132,7 @@ with PETSc's ``"jacobi"`` preconditioner, since they can provide their diagonal cheaply. For more complicated things, one must assemble an operator instead. -:class:`.AssembledPC` +:class:`AssembledPC ` Assemble an operator as a sparse matrix and then apply an inner preconditioner. For example, this might be used to assemble a coarse grid in an (otherwise matrix-free) multigrid diff --git a/docs/source/variational-problems.rst b/docs/source/variational-problems.rst index e27eb05370..c929e5d082 100644 --- a/docs/source/variational-problems.rst +++ b/docs/source/variational-problems.rst @@ -176,7 +176,7 @@ There are three main routes to obtaining a function space for a vector-valued variable such as velocity. Firstly, you can pass the :py:func:`function space ` constructor a natively *vector-valued* family such as ``"Raviart-Thomas"``. Secondly, you may use the -:py:func:`~.VectorFunctionSpace` constructor with a *scalar-valued* +:py:func:`VectorFunctionSpace ` constructor with a *scalar-valued* family, which gives a vector-valued space where each component is identical to the appropriate scalar-valued :py:class:`FunctionSpace `. Thirdly, you can create a @@ -210,11 +210,11 @@ Advanced usage of ``VectorFunctionSpace`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ By default, the number of components of a -:py:func:`~.VectorFunctionSpace` is the geometric dimension of the +:py:func:`VectorFunctionSpace ` is the geometric dimension of the mesh (e.g. 3, if the mesh is 3D). However, sometimes we might want the number of components in the vector to differ from the geometric dimension of the mesh. We can do this by passing a value for the -``dim`` argument to the :py:func:`~.VectorFunctionSpace` constructor. +``dim`` argument to the :py:func:`VectorFunctionSpace ` constructor. For example, if we wanted a vector-valued function space on the surface of a unit sphere mesh with only 2 components, we might write: @@ -641,7 +641,7 @@ setting boundary values, the latter also supports setting the value for all components. In both cases, the syntax is the same. When defining the :py:class:`DirichletBC ` we must index the function space used. For example, to specify that the third component of a -:py:func:`~.VectorFunctionSpace` should take the boundary value 0, we write: +:py:func:`VectorFunctionSpace ` should take the boundary value 0, we write: .. code-block:: python3 diff --git a/docs/source/visualisation.rst b/docs/source/visualisation.rst index f7c6639ea9..7f2047eca3 100644 --- a/docs/source/visualisation.rst +++ b/docs/source/visualisation.rst @@ -16,7 +16,7 @@ Creating output files ~~~~~~~~~~~~~~~~~~~~~ Output for visualisation purposes is managed with a -:class:`VTKFile ` object. To create one, first import the +:class:`~.output.VTKFile` object. To create one, first import the class from `firedrake.output`, then we just need to pass the name of the output file on disk. The file Firedrake creates is in PVD and therefore the requested file name must end in ``.pvd``. @@ -27,8 +27,8 @@ therefore the requested file name must end in ``.pvd``. # The following raises an error badfile = VTKFile("output.vtu") -To save functions to the :class:`VTKFile ` we use the -:meth:`write ` method. +To save functions to the :class:`~.output.VTKFile` we use the +:meth:`~.output.VTKFile.write` method. .. code-block:: python3 @@ -53,8 +53,8 @@ Saving time-dependent data Often, we have a time-dependent simulation and would like to save the same function at multiple timesteps. This is straightforward, we must -create the output :class:`VTKFile ` outside the time loop -and call :meth:`write ` inside. +create the output :class:`~.output.VTKFile` outside the time loop +and call :meth:`~.output.VTKFile.write` inside. .. code-block:: python3 @@ -69,9 +69,9 @@ and call :meth:`write ` inside. The PVD data format supports specifying the timestep value for time-dependent data. We do not have to provide it to -:meth:`write `, by default an integer counter is +:meth:`~.output.VTKFile.write`, by default an integer counter is used that is incremented by 1 each time -:meth:`write ` is called. It is possible to +:meth:`~.output.VTKFile.write` is called. It is possible to override this by passing the keyword argument ``time``. .. code-block:: python3 @@ -99,7 +99,7 @@ the data to this format first. One option is to do so by hand before outputting. Either by :doc:`interpolating ` or else :func:`projecting ` the :doc:`mesh coordinates ` and then the field. Since this is such -a common operation, the :class:`VTKFile ` object is set up +a common operation, the :class:`~.output.VTKFile` object is set up to manage these operations automatically, we just need to choose whether we want data to be interpolated or projected. The default is to use interpolation. For example, assume we wish to output a @@ -127,7 +127,7 @@ If instead we want projection, we use use an older version of Paraview, you must manually interpolate mesh coordinates and field coordinates to a piecewise linear function space, represented with either a Lagrange (H1) or discontinuous - Lagrange (L2) basis. The :class:`VTKFile ` is also setup + Lagrange (L2) basis. The :class:`~.output.VTKFile` is also setup to manage this issue. For instance, we can force the output to be discontinuous piecewise linears via @@ -197,7 +197,7 @@ pressure in a fluids models. This is possible either by having a separate output file for each field, or by saving multiple fields to the same output file. The latter may be more convenient for subsequent analysis. To do this, we just need to pass multiple -:class:`function `\s to :meth:`write `. +:class:`function `\s to :meth:`~.output.VTKFile.write`. .. code-block:: python3 @@ -376,7 +376,7 @@ Last but not least, vector fields defined on a vertex-only mesh can be visualise Writing vertex-only mesh data to VTK ++++++++++++++++++++++++++++++++++++ -Vertex-only mesh data can be written to VTK output enabling point data visualisations in third-party software such as ParaView. A :class:`VTKFile ` accepts :class:`function `\s +Vertex-only mesh data can be written to VTK output enabling point data visualisations in third-party software such as ParaView. A :class:`~.output.VTKFile` accepts :class:`function `\s defined on a :func:`firedrake.VertexOnlyMesh` in the same way as functions defined on ordinary meshes. The output includes the point coordinates, the values of any supplied function(s), and a persistent particle ID field. In ParaView, for instance, this ID field can be used to colour particles by identity. diff --git a/firedrake/adjoint/ensemble_reduced_functional.py b/firedrake/adjoint/ensemble_reduced_functional.py index 70207114e3..72979a5702 100644 --- a/firedrake/adjoint/ensemble_reduced_functional.py +++ b/firedrake/adjoint/ensemble_reduced_functional.py @@ -25,7 +25,7 @@ class EnsembleReducedFunctional(AbstractReducedFunctional): \\frac{dJ}{dm} = \\sum_{i=1}^{N} \\frac{dJ_i}{dm}, The :class:`EnsembleReducedFunctional` allows simultaneous evaluation of :math:`J_i` and - :math:`\\dfrac{dJ_i}{dm}`. After that, the allreduce :class:`firedrake.Ensemble.Ensemble` + :math:`\\dfrac{dJ_i}{dm}`. After that, the allreduce :class:`~.ensemble.Ensemble` operation is employed to sum the functionals and their gradients over an ensemble communicator. @@ -41,7 +41,7 @@ class EnsembleReducedFunctional(AbstractReducedFunctional): control : pyadjoint.Control or list of pyadjoint.Control A single or a list of Control instances, which you want to map to the functional. ensemble : Ensemble - An instance of the :class:`firedrake.Ensemble.Ensemble`. It is used to communicate the + An instance of the :class:`~.ensemble.Ensemble`. It is used to communicate the functionals and their derivatives between the ensemble members. scatter_control : bool Whether scattering a control (or a list of controls) over the ensemble communicator @@ -78,7 +78,7 @@ class EnsembleReducedFunctional(AbstractReducedFunctional): See Also -------- - :class:`firedrake.Ensemble.Ensemble`, :class:`pyadjoint.ReducedFunctional`. + :class:`~.ensemble.Ensemble`, :class:`pyadjoint.ReducedFunctional`. Notes ----- diff --git a/firedrake/bcs.py b/firedrake/bcs.py index 75816771c5..071b78d779 100644 --- a/firedrake/bcs.py +++ b/firedrake/bcs.py @@ -270,7 +270,7 @@ class DirichletBC(BCBase, DirichletBCMixin): should be applied. :arg g: the boundary condition values. This can be a :class:`.Function` on ``V``, or a UFL expression that can be interpolated into - ``V``, for example, a :class:`.Constant` , an iterable of + ``V``, for example, a :class:`Constant ` , an iterable of literal constants (converted to a UFL expression), or a literal constant which can be pointwise evaluated at the nodes of ``V``. diff --git a/firedrake/cofunction.py b/firedrake/cofunction.py index 55e4fe99cf..7574e210e2 100644 --- a/firedrake/cofunction.py +++ b/firedrake/cofunction.py @@ -131,7 +131,7 @@ def sub(self, i): See also :attr:`subfunctions`. If the :class:`Cofunction` is defined on a - :func:`~.VectorFunctionSpace` or :func:`~.TensorFunctionSpace` + :func:`VectorFunctionSpace ` or :func:`~.TensorFunctionSpace` this returns a proxy object indexing the ith component of the space, suitable for use in boundary condition application.""" mixed = type(self.function_space().ufl_element()) is MixedElement diff --git a/firedrake/ensemble/ensemble_function.py b/firedrake/ensemble/ensemble_function.py index bb199f10da..74a5fbf305 100644 --- a/firedrake/ensemble/ensemble_function.py +++ b/firedrake/ensemble/ensemble_function.py @@ -12,10 +12,10 @@ class EnsembleFunctionBase(EnsembleFunctionMixin): """ - A mixed (co)function defined on a :class:`firedrake.Ensemble.Ensemble`. + A mixed (co)function defined on a :class:`~.ensemble.Ensemble`. The subcomponents are distributed over the ensemble members, and are specified locally in an - :class:`firedrake.Ensemble_functionspace.EnsembleFunctionSpace`. + :class:`~.ensemble_functionspace.EnsembleFunctionSpace`. Parameters ---------- @@ -25,7 +25,7 @@ class EnsembleFunctionBase(EnsembleFunctionMixin): Notes ----- - Passing an :class:`firedrake.Ensemble_functionspace.EnsembleDualSpace` to + Passing an :class:`~.ensemble_functionspace.EnsembleDualSpace` to :class:`EnsembleFunction` will return an instance of :class:`EnsembleCofunction`. This class does not carry UFL symbolic information, unlike a @@ -287,7 +287,7 @@ def vec_wo(self): class EnsembleFunction(EnsembleFunctionBase): """ - A mixed Function defined on a :class:`firedrake.Ensemble.Ensemble`. + A mixed Function defined on a :class:`~.ensemble.Ensemble`. The subcomponents are distributed over the ensemble members, and are specified locally in an :class:`~firedrake.ensemble.ensemble_functionspace.EnsembleFunctionSpace`. @@ -309,10 +309,10 @@ class EnsembleFunction(EnsembleFunctionBase): See Also -------- - :class:`firedrake.Ensemble_functionspace.EnsembleFunctionSpace` - :class:`firedrake.Ensemble_function.EnsembleFunction` - :class:`firedrake.Ensemble_functionspace.EnsembleDualSpace` - :class:`firedrake.Ensemble_function.EnsembleCofunction` + :class:`~.ensemble_functionspace.EnsembleFunctionSpace` + :class:`~.ensemble_function.EnsembleFunction` + :class:`~.ensemble_functionspace.EnsembleDualSpace` + :class:`~.ensemble_function.EnsembleCofunction` """ def __new__(cls, function_space: EnsembleFunctionSpaceBase): if isinstance(function_space, EnsembleDualSpace): @@ -365,10 +365,10 @@ class EnsembleCofunction(EnsembleFunctionBase): See Also -------- - :class:`firedrake.Ensemble_functionspace.EnsembleFunctionSpace` - :class:`firedrake.Ensemble_function.EnsembleFunction` - :class:`firedrake.Ensemble_functionspace.EnsembleDualSpace` - :class:`firedrake.Ensemble_function.EnsembleCofunction` + :class:`~.ensemble_functionspace.EnsembleFunctionSpace` + :class:`~.ensemble_function.EnsembleFunction` + :class:`~.ensemble_functionspace.EnsembleDualSpace` + :class:`~.ensemble_function.EnsembleCofunction` """ def __init__(self, function_space: EnsembleDualSpace): if not isinstance(function_space, EnsembleDualSpace): diff --git a/firedrake/ensemble/ensemble_functionspace.py b/firedrake/ensemble/ensemble_functionspace.py index 6e25a53c31..ee7c0582e8 100644 --- a/firedrake/ensemble/ensemble_functionspace.py +++ b/firedrake/ensemble/ensemble_functionspace.py @@ -20,7 +20,7 @@ def _is_primal_or_dual(local_spaces, ensemble): local_spaces : Collection The list of :class:`~firedrake.functionspaceimpl.FunctionSpace` on the local ensemble.comm. - ensemble : :class:`firedrake.Ensemble.Ensemble` + ensemble : :class:`~.ensemble.Ensemble` The Ensemble to test collectively over. Returns @@ -64,7 +64,7 @@ def _is_primal_or_dual(local_spaces, ensemble): class EnsembleFunctionSpaceBase: """ - Base class for mixed function spaces defined on an :class:`firedrake.Ensemble.Ensemble`. + Base class for mixed function spaces defined on an :class:`~.ensemble.Ensemble`. The subcomponents are distributed over the ensemble members, and are specified locally. @@ -110,25 +110,25 @@ def __init__(self, local_spaces: Collection, ensemble: Ensemble): @property def ensemble(self): - """The :class:`firedrake.Ensemble.Ensemble` that the function space is defined over + """The :class:`~.ensemble.Ensemble` that the function space is defined over """ return self._ensemble @property def comm(self): - """The spatial communicator from the :class:`firedrake.Ensemble.Ensemble` communicator. + """The spatial communicator from the :class:`~.ensemble.Ensemble` communicator. """ return self._ensemble.comm @property def ensemble_comm(self): - """The ensemble communicator from the :class:`firedrake.Ensemble.Ensemble` communicator. + """The ensemble communicator from the :class:`~.ensemble.Ensemble` communicator. """ return self._ensemble.ensemble_comm @property def global_comm(self): - """The global communicator from the :class:`firedrake.Ensemble.Ensemble` communicator. + """The global communicator from the :class:`~.ensemble.Ensemble` communicator. """ return self._ensemble.global_comm @@ -231,7 +231,7 @@ def __neq__(self, other): class EnsembleFunctionSpace(EnsembleFunctionSpaceBase): """ - A mixed primal function space defined on an :class:`firedrake.Ensemble.Ensemble`. + A mixed primal function space defined on an :class:`~.ensemble.Ensemble`. The subcomponents are distributed over the ensemble members, but are specified locally on each ensemble member. @@ -239,7 +239,7 @@ class EnsembleFunctionSpace(EnsembleFunctionSpaceBase): ---------- local_spaces : Collection The list of primal function spaces on the local ``Ensemble.comm``. - ensemble : :class:`firedrake.Ensemble.Ensemble` + ensemble : :class:`~.ensemble.Ensemble` The communicator that the function space is defined over. Notes diff --git a/firedrake/ensemble/ensemble_mat.py b/firedrake/ensemble/ensemble_mat.py index 3a37f67dd4..55035d3bf3 100644 --- a/firedrake/ensemble/ensemble_mat.py +++ b/firedrake/ensemble/ensemble_mat.py @@ -6,7 +6,7 @@ class EnsembleMatCtxBase: """ - Base class for python type Mats defined over an :class:`firedrake.Ensemble.Ensemble`. + Base class for python type Mats defined over an :class:`~.ensemble.Ensemble`. Parameters ---------- @@ -20,7 +20,7 @@ class EnsembleMatCtxBase: Notes ----- The main use of this base class is to enable users to implement the matrix - action as acting on and resulting in an :class:`firedrake.Ensemble_function.EnsembleFunction`. + action as acting on and resulting in an :class:`~.ensemble_function.EnsembleFunction`. This is done by implementing the ``mult_impl`` method. See Also @@ -107,7 +107,7 @@ def mult_impl(self, A, x: EnsembleFunctionBase, y: EnsembleFunctionBase): class EnsembleBlockDiagonalMatCtx(EnsembleMatCtxBase): """ A python Mat context for a block diagonal matrix defined over an :class:`.ensemble.Ensemble`. - Each block acts on a single subspace of an :class:`firedrake.Ensemble_functionspace.EnsembleFunctionSpace`. + Each block acts on a single subspace of an :class:`~.ensemble_functionspace.EnsembleFunctionSpace`. Parameters ---------- @@ -221,8 +221,8 @@ def EnsembleBlockDiagonalMat(block_mats: Iterable, row_space: EnsembleFunctionSpaceBase, col_space: EnsembleFunctionSpaceBase): """ - A Mat for a block diagonal matrix defined over an :class:`firedrake.Ensemble.Ensemble`. - Each block acts on a single subspace of an :class:`firedrake.Ensemble_functionspace.EnsembleFunctionSpace`. + A Mat for a block diagonal matrix defined over an :class:`~.ensemble.Ensemble`. + Each block acts on a single subspace of an :class:`~.ensemble_functionspace.EnsembleFunctionSpace`. This is a convenience function to create a PETSc.Mat with a :class:`.EnsembleBlockDiagonalMatCtx` Python context. Parameters diff --git a/firedrake/ensemble/ensemble_pc.py b/firedrake/ensemble/ensemble_pc.py index 35a4b2bd3b..1a3f96aaae 100644 --- a/firedrake/ensemble/ensemble_pc.py +++ b/firedrake/ensemble/ensemble_pc.py @@ -10,14 +10,14 @@ def obj_name(obj): class EnsemblePCBase(petsctools.PCBase): """ - Base class for python type PCs defined over an :class:`firedrake.Ensemble.Ensemble`. + Base class for python type PCs defined over an :class:`~.ensemble.Ensemble`. - The pc operators must be python Mats with :class:`firedrake.Ensemble_mat.EnsembleMatCtxBase`. + The pc operators must be python Mats with :class:`~.ensemble_mat.EnsembleMatCtxBase`. Notes ----- The main use of this base class is to enable users to implement the preconditioner - action as acting on and resulting in an :class:`firedrake.Ensemble_function.EnsembleFunction`. + action as acting on and resulting in an :class:`~.ensemble_function.EnsembleFunction`. This is done by implementing the ``apply_impl`` method. See Also @@ -58,8 +58,8 @@ def apply_impl(self, pc, x, y): class EnsembleBJacobiPC(EnsemblePCBase): """ - A python PC context for a block Jacobi method defined over an :class:`firedrake.Ensemble.Ensemble`. - Each block acts on a single subspace of an :class:`firedrake.Ensemble_functionspace.EnsembleFunctionSpace` + A python PC context for a block Jacobi method defined over an :class:`~.ensemble.Ensemble`. + Each block acts on a single subspace of an :class:`~.ensemble_functionspace.EnsembleFunctionSpace` and is (approximately) solved with its own KSP, which defaults to -ksp_type preonly. Available options: @@ -70,7 +70,7 @@ class EnsembleBJacobiPC(EnsemblePCBase): Notes ----- - Currently this is only implemented for :class:`firedrake.Ensemble_mat.EnsembleBlockDiagonalMatCtx` matrices. + Currently this is only implemented for :class:`~.ensemble_mat.EnsembleBlockDiagonalMatCtx` matrices. See Also -------- diff --git a/firedrake/external_operators/abstract_external_operators.py b/firedrake/external_operators/abstract_external_operators.py index 3afc09f318..8a062a3bb7 100644 --- a/firedrake/external_operators/abstract_external_operators.py +++ b/firedrake/external_operators/abstract_external_operators.py @@ -14,14 +14,14 @@ class AssemblyRegisterMetaClass(UFLType): """Metaclass registering assembly methods specified by external operator subclasses. - This metaclass is used to register assembly methods specified by subclasses of :class:`~.AbstractExternalOperator`. + This metaclass is used to register assembly methods specified by subclasses of :class:`AbstractExternalOperator `. For any new external operator subclass, :class:`AssemblyRegisterMetaClass` will collect all assembly methods specified by the subclass and construct a registry to map from assembly identifiers, specified via the `assemble_method` decorator to the corresponding assembly methods, and attach that registry to the subclass. Notes ----- - This metaclass subclasses `UFLType` to avoid metaclass conflict for :class:`~.AbstractExternalOperator`. + This metaclass subclasses `UFLType` to avoid metaclass conflict for :class:`AbstractExternalOperator `. """ def __init__(cls, name, bases, attrs): cls._assembly_registry = {} @@ -40,9 +40,9 @@ class AbstractExternalOperator(ExternalOperator, metaclass=AssemblyRegisterMetaC def __init__(self, *operands, function_space, derivatives=None, argument_slots=(), operator_data=None): """External operator base class providing the interface to build new external operators. - The :class:`~.AbstractExternalOperator` encapsulates the external operator abstraction and is compatible + The :class:`AbstractExternalOperator ` encapsulates the external operator abstraction and is compatible with UFL symbolic operations, the Firedrake assembly, and the AD capabilities provided by `~.firedrake.adjoint`. - The :class:`~.AbstractExternalOperator` class orchestrates the external operator assembly by linking the + The :class:`AbstractExternalOperator ` class orchestrates the external operator assembly by linking the finite element assembly to the assembly implementations specified by the external operator subclasses. Parameters diff --git a/firedrake/external_operators/point_expr_operator.py b/firedrake/external_operators/point_expr_operator.py index 4e7183e47f..7fef2ab0bb 100644 --- a/firedrake/external_operators/point_expr_operator.py +++ b/firedrake/external_operators/point_expr_operator.py @@ -34,7 +34,7 @@ def __init__(self, *operands, function_space, derivatives=None, argument_slots=( Notes ----- - The :class:`~.PointexprOperator` class mimics the :class:`~.Interpolate` class and is mostly design + The :class:`~.PointexprOperator` class mimics the :class:`Interpolate ` class and is mostly design for debugging purposes. """ AbstractExternalOperator.__init__(self, *operands, function_space=function_space, derivatives=derivatives, diff --git a/firedrake/function.py b/firedrake/function.py index 1bb5f4bc52..ceefb608ce 100644 --- a/firedrake/function.py +++ b/firedrake/function.py @@ -327,7 +327,7 @@ def sub(self, i): See also :attr:`subfunctions`. If the :class:`Function` is defined on a - :func:`~.VectorFunctionSpace` or :func:`~.TensorFunctionSpace` this returns a proxy object + :func:`VectorFunctionSpace ` or :func:`~.TensorFunctionSpace` this returns a proxy object indexing the ith component of the space, suitable for use in boundary condition application.""" mixed = type(self.function_space().ufl_element()) is MixedElement diff --git a/firedrake/linear_solver.py b/firedrake/linear_solver.py index 6fb87d4a37..4371584f6c 100644 --- a/firedrake/linear_solver.py +++ b/firedrake/linear_solver.py @@ -12,8 +12,8 @@ class LinearSolver(LinearVariationalSolver): def __init__(self, A, *, P=None, **kwargs): """A linear solver for assembled systems (Ax = b) with constant A. - :arg A: a :class:`~.MatrixBase` (the operator). - :arg P: an optional :class:`~.MatrixBase` to construct any + :arg A: a :class:`MatrixBase ` (the operator). + :arg P: an optional :class:`MatrixBase ` to construct any preconditioner from; if none is supplied ``A`` is used to construct the preconditioner. :kwarg solver_parameters: (optional) dict of solver parameters. diff --git a/firedrake/mg/mesh.py b/firedrake/mg/mesh.py index c0b172c216..801cc45c63 100644 --- a/firedrake/mg/mesh.py +++ b/firedrake/mg/mesh.py @@ -103,7 +103,7 @@ def add_mesh(self, mesh, coarse_to_fine_cells=None, fine_to_coarse_cells=None): ---------- mesh : The mesh to add, usually obtained by calling - :meth:`~firedrake.mesh.MeshGeometry.refine_marked_elements` on the + :meth:`~.mesh.MeshGeometry.refine_marked_elements` on the current finest mesh. coarse_to_fine_cells : Map from the cells of the current finest mesh to the cells of diff --git a/firedrake/ml/jax/fem_operator.py b/firedrake/ml/jax/fem_operator.py index cee0d23a86..4793e40a5f 100644 --- a/firedrake/ml/jax/fem_operator.py +++ b/firedrake/ml/jax/fem_operator.py @@ -198,7 +198,7 @@ def from_jax(x: "jax.Array", V: Optional[WithGeometry] = None) -> Union[Function x JAX tensor to convert. V - Function space of the corresponding :class:`.Function` or None when `x` is to be mapped to a :class:`.Constant`. + Function space of the corresponding :class:`.Function` or None when `x` is to be mapped to a :class:`Constant `. Returns ------- diff --git a/firedrake/ml/pytorch/fem_operator.py b/firedrake/ml/pytorch/fem_operator.py index 22b57501c5..465e8caca1 100644 --- a/firedrake/ml/pytorch/fem_operator.py +++ b/firedrake/ml/pytorch/fem_operator.py @@ -203,7 +203,7 @@ def from_torch(x, V=None): x : torch.Tensor PyTorch tensor to convert. V : firedrake.functionspaceimpl.WithGeometry or None - Function space of the corresponding :class:`.Function` or None when `x` is to be mapped to a :class:`.Constant`. + Function space of the corresponding :class:`.Function` or None when `x` is to be mapped to a :class:`Constant `. Returns ------- diff --git a/firedrake/nullspace.py b/firedrake/nullspace.py index b38904a417..c16100a98e 100644 --- a/firedrake/nullspace.py +++ b/firedrake/nullspace.py @@ -176,7 +176,7 @@ def is_orthogonal(self): def _apply(self, matrix, transpose=False, near=False): r"""Set this VectorSpaceBasis as a nullspace for a matrix - :arg matrix: a :class:`~.MatrixBase` whose nullspace should + :arg matrix: a :class:`MatrixBase ` whose nullspace should be set. :kwarg transpose: Should this be set as the transpose nullspace instead? Used to orthogonalize the right hand @@ -318,7 +318,7 @@ def _apply_monolithic(self, matrix, transpose=False, near=False): r"""Set this class:`MixedVectorSpaceBasis` as a nullspace for a matrix. - :arg matrix: a :class:`~.MatrixBase` whose nullspace should + :arg matrix: a :class:`MatrixBase ` whose nullspace should be set. :kwarg transpose: Should this be set as the transpose @@ -347,7 +347,7 @@ def _apply_monolithic(self, matrix, transpose=False, near=False): def _apply(self, matrix_or_ises, transpose=False, near=False): r"""Set this :class:`MixedVectorSpaceBasis` as a nullspace for a matrix - :arg matrix_or_ises: either a :class:`~.MatrixBase` to set a + :arg matrix_or_ises: either a :class:`MatrixBase ` to set a nullspace on, or else a list of PETSc ISes to compose a nullspace with. :kwarg transpose: Should this be set as the transpose diff --git a/firedrake/parloops.py b/firedrake/parloops.py index 0a33cd4ae5..aeb44b2caf 100644 --- a/firedrake/parloops.py +++ b/firedrake/parloops.py @@ -180,7 +180,7 @@ def par_loop(kernel, measure, args, kernel_kwargs=None, **kwargs): **Argument definitions** Each item in the `args` dictionary maps a string to a tuple - containing a :class:`.Function` or :class:`.Constant` and an + containing a :class:`.Function` or :class:`Constant ` and an argument intent. The string is the c language variable name by which this function will be accessed in the kernel. The argument intent indicates how the kernel will access this variable: @@ -202,7 +202,7 @@ def par_loop(kernel, measure, args, kernel_kwargs=None, **kwargs): .. note:: - Only `READ` intents are valid for :class:`.Constant` + Only `READ` intents are valid for :class:`Constant ` coefficients, and an error will be raised in other cases. **The measure** @@ -250,7 +250,7 @@ def par_loop(kernel, measure, args, kernel_kwargs=None, **kwargs): In a direct :func:`par_loop`, the variables will all be of type `double*` with the single index being the vector component. - :class:`.Constant`\s are always of type `double*`, both for + :class:`Constant `\s are always of type `double*`, both for indirect and direct :func:`par_loop` calls. """ diff --git a/firedrake/preconditioners/auxiliary_snes.py b/firedrake/preconditioners/auxiliary_snes.py index 3d59de15b6..3b80780d71 100644 --- a/firedrake/preconditioners/auxiliary_snes.py +++ b/firedrake/preconditioners/auxiliary_snes.py @@ -160,7 +160,7 @@ def form(self, snes, u_k: Function, u: Function, test: Argument): Defaults to returning a copy of :math:`F(u)`, i.e. :math:`G(u_{k+1}; u_k)=F(u_{k+1})`. This means that ``AuxiliaryOperatorSNES`` can be used similarly - to :class:`.AssembledPC`, in that it can be used to specify + to :class:`AssembledPC `, in that it can be used to specify an alternative ``snes_type`` for solving the same residual form as the outer ``SNES``. diff --git a/firedrake/solving.py b/firedrake/solving.py index 1c70956788..f5f0141e7f 100644 --- a/firedrake/solving.py +++ b/firedrake/solving.py @@ -50,7 +50,7 @@ def solve(*args, **kwargs): to apply and PDEs to solve on the boundaries. For the format of ``solver_parameters`` see below. - Optionally, an argument ``P`` of type :class:`~.MatrixBase` can be passed to + Optionally, an argument ``P`` of type :class:`MatrixBase ` can be passed to construct any preconditioner from; if none is supplied ``A`` is used to construct the preconditioner. @@ -208,7 +208,7 @@ def _la_solve(A, x, b, **kwargs): :arg A: the assembled bilinear form, a :class:`.Matrix`. :arg x: the :class:`.Function` to write the solution into. :arg b: the :class:`.Function` defining the right hand side values. - :kwarg P: an optional :class:`~.MatrixBase` to construct any + :kwarg P: an optional :class:`MatrixBase ` to construct any preconditioner from; if none is supplied ``A`` is used to construct the preconditioner. :kwarg solver_parameters: optional solver parameters. From 4e22b4e573ca20125c36c04b631dfbc2dfb76fc4 Mon Sep 17 00:00:00 2001 From: nwng04 Date: Sun, 6 Sep 2026 13:53:52 +0100 Subject: [PATCH 25/28] fix vtk_output references --- demos/burgers/burgers.py.rst | 8 ++-- demos/camassa-holm/camassaholm.py.rst | 2 +- .../full_waveform_inversion.py.rst | 4 +- .../qg_1layer_wave.py.rst | 2 +- docs/source/ensemble_parallelism.rst | 40 +++++++++---------- docs/source/parallelism.rst | 4 +- docs/source/visualisation.rst | 22 +++++----- firedrake/mesh.py | 2 +- 8 files changed, 42 insertions(+), 42 deletions(-) diff --git a/demos/burgers/burgers.py.rst b/demos/burgers/burgers.py.rst index 9bb131b096..52fea37f42 100644 --- a/demos/burgers/burgers.py.rst +++ b/demos/burgers/burgers.py.rst @@ -93,12 +93,12 @@ We now create an object for output visualisation:: Output only supports visualisation of linear fields (either P1, or P1DG). In this example we project to a linear space by hand. Another -option is to let the :class:`~.output.VTKFile` object manage the +option is to let the :class:`~.vtk_output.VTKFile` object manage the decimation. It supports both interpolation to linears (the default) or projection (by passing ``project_output=True`` when creating the -:class:`~.output.VTKFile`). Outputting data is carried out using -the :meth:`~.output.VTKFile.write` method of -:class:`~.output.VTKFile` objects:: +:class:`~.vtk_output.VTKFile`). Outputting data is carried out using +the :meth:`~.vtk_output.VTKFile.write` method of +:class:`~.vtk_output.VTKFile` objects:: outfile.write(project(u, V_out, name="Velocity")) diff --git a/demos/camassa-holm/camassaholm.py.rst b/demos/camassa-holm/camassaholm.py.rst index ebbec61807..65784cdb30 100644 --- a/demos/camassa-holm/camassaholm.py.rst +++ b/demos/camassa-holm/camassaholm.py.rst @@ -168,7 +168,7 @@ e.g. for output. :: m0, u0 = w0.subfunctions m1, u1 = w1.subfunctions -We choose a final time, and initialise a :class:`~.output.VTKFile` +We choose a final time, and initialise a :class:`~.vtk_output.VTKFile` object for storing ``u``. as well as an array for storing the function to be visualised:: diff --git a/demos/full_waveform_inversion/full_waveform_inversion.py.rst b/demos/full_waveform_inversion/full_waveform_inversion.py.rst index 87586c6b40..06390072da 100644 --- a/demos/full_waveform_inversion/full_waveform_inversion.py.rst +++ b/demos/full_waveform_inversion/full_waveform_inversion.py.rst @@ -278,7 +278,7 @@ To have the step 4, we need first to tape the forward problem. That is done by c misfit = guess_receiver - true_data_receivers[step] J_val += 0.5 * assemble(inner(misfit, misfit) * dx) -We now instantiate :class:~.EnsembleReducedFunctional`:: +We now instantiate :class:`~.EnsembleReducedFunctional`:: J_hat = EnsembleReducedFunctional(J_val, Control(c_guess, riesz_map="l2"), @@ -289,7 +289,7 @@ where the :math:`J_s` and its gradients :math:`\nabla_{\mathtt{c\_guess}} J_s` a based on the ``my_ensemble`` configuration. -**Steps 4-6**: The instance of the :class:~.EnsembleReducedFunctional`, named ``J_hat``, +**Steps 4-6**: The instance of the :class:`~.EnsembleReducedFunctional`, named ``J_hat``, is then passed as an argument to the ``minimize`` function. The default ``minimize`` function uses ``scipy.minimize``, and wraps the ``ReducedFunctional`` in a ``ReducedFunctionalNumPy`` that handles transferring data between Firedrake and numpy data structures. However, because diff --git a/demos/quasigeostrophy_1layer/qg_1layer_wave.py.rst b/demos/quasigeostrophy_1layer/qg_1layer_wave.py.rst index 22a2310774..dfe0c36b0f 100644 --- a/demos/quasigeostrophy_1layer/qg_1layer_wave.py.rst +++ b/demos/quasigeostrophy_1layer/qg_1layer_wave.py.rst @@ -195,7 +195,7 @@ fill. :: "sub_pc_type": "ilu"}) To visualise the output of the simulation, we create a -:class:`~.output.VTKFile` object. To which we can store multiple +:class:`~.vtk_output.VTKFile` object. To which we can store multiple :class:`function `\s. So that we can distinguish between them we will give them descriptive names. :: diff --git a/docs/source/ensemble_parallelism.rst b/docs/source/ensemble_parallelism.rst index 1fc46a2be2..00042c422f 100644 --- a/docs/source/ensemble_parallelism.rst +++ b/docs/source/ensemble_parallelism.rst @@ -35,10 +35,10 @@ Cartesian product over the original global communicator. The additional functionality required to support ensemble parallelism is the ability to send instances of :class:`function ` from one -ensemble to another. This is handled by the :class:`~.ensemble` class. +ensemble to another. This is handled by the :class:`~.Ensemble` class. Each ensemble member must have the same spatial parallel domain decomposition, so -instantiating an :class:`~.ensemble` requires a communicator to split +instantiating an :class:`~.Ensemble` requires a communicator to split (usually, but not necessarily, ``MPI_COMM_WORLD``) plus the number of MPI processes to be used in each member of the ensemble (5 in the figure above, and 2 in the example code below). The number of ensemble @@ -78,7 +78,7 @@ The ensemble sub-communicator is then available through the attribute MPI communications across the spatial sub-communicator (i.e., within an ensemble member) are handled automatically by Firedrake, whilst MPI communications across the ensemble sub-communicator (i.e., between ensemble -members) are handled through methods of :class:`~.ensemble`. Currently +members) are handled through methods of :class:`~.Ensemble`. Currently send/recv, reductions and broadcasts are supported, as well as their non-blocking variants. The rank of the the ensemble member (``my_ensemble.ensemble_comm.rank``) @@ -115,26 +115,26 @@ timeseries, and each timestep may live on a separate ensemble member. In this case we want to treat the entire timeseries as a single object. -Firedrake implements this using :class:`~.ensembleFunctionSpace` -and :class:`~.ensembleFunction` (along with the dual objects -:class:`~.ensembleDualSpace` and :class:`~.ensembleCofunction`). -The :class:`~.ensembleFunctionSpace` can be thought of as a mixed +Firedrake implements this using :class:`~.EnsembleFunctionSpace` +and :class:`~.EnsembleFunction` (along with the dual objects +:class:`~.EnsembleDualSpace` and :class:`~.EnsembleCofunction`). +The :class:`~.EnsembleFunctionSpace` can be thought of as a mixed function space which is parallelised across the `components`, as opposed to just being parallelised in `space`, as would usually be the case with :func:`function space `. Each component of an -:class:`~.ensembleFunctionSpace` is a Firedrake :func:`function space ` +:class:`~.EnsembleFunctionSpace` is a Firedrake :func:`function space ` on a single spatial communicator. -To create an :class:`~.ensembleFunctionSpace` you must provide an -:class:`~.ensemble` and, on each spatial communicator, a list of +To create an :class:`~.EnsembleFunctionSpace` you must provide an +:class:`~.Ensemble` and, on each spatial communicator, a list of :func:`function space ` instances for the components on the local ``Ensemble.comm``. There can be a different number of local :func:`function space ` on each ``Ensemble.comm``. In the example -below we create an :class:`~.ensembleFunctionSpace` with two +below we create an :class:`~.EnsembleFunctionSpace` with two components on the first ensemble member, and three components on every other ensemble member. Note that, unlike a :func:`function space `, a component of an -:class:`~.ensembleFunctionSpace` may itself be a +:class:`~.EnsembleFunctionSpace` may itself be a :func:`MixedFunctionSpace `. .. literalinclude:: ../../tests/firedrake/ensemble/test_ensemble_manual.py @@ -145,14 +145,14 @@ every other ensemble member. Note that, unlike a Analogously to accessing the components of a :func:`MixedFunctionSpace ` using ``subspaces``, the :func:`function space ` for each local component -of an :class:`~.ensembleFunctionSpace` can be accessed via +of an :class:`~.EnsembleFunctionSpace` can be accessed via ``EnsembleFunctionSpace.local_spaces``. Various other methods and -properties such as ``dual`` (to create an :class:`~.ensembleDualSpace`) +properties such as ``dual`` (to create an :class:`~.EnsembleDualSpace`) and ``nglobal_spaces`` (total number of components across all ranks) are also available. -An :class:`~.ensembleFunction` and :class:`~.ensembleCofunction` can be -created from the :class:`~.ensembleFunctionSpace`. These have a ``subfunctions`` +An :class:`~.EnsembleFunction` and :class:`~.EnsembleCofunction` can be +created from the :class:`~.EnsembleFunctionSpace`. These have a ``subfunctions`` property that can be used to access the components on the local ensemble member. Each element in ``EnsembleFunction.subfunctions`` is itself just a normal Firedrake :class:`function `. If a component of the @@ -166,7 +166,7 @@ that ``MixedFunctionSpace``. :start-after: [test_ensemble_manual_example 6 >] :end-before: [test_ensemble_manual_example 6 <] -:class:`~.ensembleFunction` and :class:`~.ensembleCofunction` have +:class:`~.EnsembleFunction` and :class:`~.EnsembleCofunction` have a range of methods equivalent to those of :class:`function ` and :class:`Cofunction `, such as ``assign``, ``zero``, ``riesz_representation``, arithmetic operators e.g. ``+``, ``+=``, @@ -177,9 +177,9 @@ Because the components in ``EnsembleFunction.subfunctions`` (:class:`Cofunction `) instances, they can be used directly with variational forms and solvers. In the example code below, We create a :class:`linear variational solver ` where the right -hand side is a component of an :class:`~.ensembleCofunction`, +hand side is a component of an :class:`~.EnsembleCofunction`, and the solution is written into a component of an -:class:`~.ensembleFunction`. Using the ``subfunctions`` +:class:`~.EnsembleFunction`. Using the ``subfunctions`` directly like this can simplify ensemble code and reduce unnecessary copies. Note that the ``options_prefix`` is set using both the local ensemble @@ -201,7 +201,7 @@ on each ensemble member. ``EnsembleCofunction`` themselves do not carry any symbolic information so cannot be used in UFL expressions. -Internally, the :class:`~.ensembleFunction` creates a ``PETSc.Vec`` +Internally, the :class:`~.EnsembleFunction` creates a ``PETSc.Vec`` on the ``Ensemble.global_comm`` which contains the data for all local components on all ensemble members. This ``Vec`` can be accessed with a context manager, similarly to the ``Function.dat.vec`` context diff --git a/docs/source/parallelism.rst b/docs/source/parallelism.rst index fb58342992..370ed381df 100644 --- a/docs/source/parallelism.rst +++ b/docs/source/parallelism.rst @@ -87,10 +87,10 @@ different simulations on the two halves we would write. .. note:: If you need to create Firedrake meshes on different communicators, - then usually the best approach is to use the :class:`~.ensemble`, + then usually the best approach is to use the :class:`~.Ensemble`, which manages splitting MPI communicators and communicating :class:`function ` objects between the split communicators. More - information on using the :class:`~.ensemble` can be found + information on using the :class:`~.Ensemble` can be found :doc:`here `. To access the communicator a mesh was created on, we can use the diff --git a/docs/source/visualisation.rst b/docs/source/visualisation.rst index 7f2047eca3..9a192bff8f 100644 --- a/docs/source/visualisation.rst +++ b/docs/source/visualisation.rst @@ -16,7 +16,7 @@ Creating output files ~~~~~~~~~~~~~~~~~~~~~ Output for visualisation purposes is managed with a -:class:`~.output.VTKFile` object. To create one, first import the +:class:`~.vtk_output.VTKFile` object. To create one, first import the class from `firedrake.output`, then we just need to pass the name of the output file on disk. The file Firedrake creates is in PVD and therefore the requested file name must end in ``.pvd``. @@ -27,8 +27,8 @@ therefore the requested file name must end in ``.pvd``. # The following raises an error badfile = VTKFile("output.vtu") -To save functions to the :class:`~.output.VTKFile` we use the -:meth:`~.output.VTKFile.write` method. +To save functions to the :class:`~.vtk_output.VTKFile` we use the +:meth:`~.vtk_output.VTKFile.write` method. .. code-block:: python3 @@ -53,8 +53,8 @@ Saving time-dependent data Often, we have a time-dependent simulation and would like to save the same function at multiple timesteps. This is straightforward, we must -create the output :class:`~.output.VTKFile` outside the time loop -and call :meth:`~.output.VTKFile.write` inside. +create the output :class:`~.vtk_output.VTKFile` outside the time loop +and call :meth:`~.vtk_output.VTKFile.write` inside. .. code-block:: python3 @@ -69,9 +69,9 @@ and call :meth:`~.output.VTKFile.write` inside. The PVD data format supports specifying the timestep value for time-dependent data. We do not have to provide it to -:meth:`~.output.VTKFile.write`, by default an integer counter is +:meth:`~.vtk_output.VTKFile.write`, by default an integer counter is used that is incremented by 1 each time -:meth:`~.output.VTKFile.write` is called. It is possible to +:meth:`~.vtk_output.VTKFile.write` is called. It is possible to override this by passing the keyword argument ``time``. .. code-block:: python3 @@ -99,7 +99,7 @@ the data to this format first. One option is to do so by hand before outputting. Either by :doc:`interpolating ` or else :func:`projecting ` the :doc:`mesh coordinates ` and then the field. Since this is such -a common operation, the :class:`~.output.VTKFile` object is set up +a common operation, the :class:`~.vtk_output.VTKFile` object is set up to manage these operations automatically, we just need to choose whether we want data to be interpolated or projected. The default is to use interpolation. For example, assume we wish to output a @@ -127,7 +127,7 @@ If instead we want projection, we use use an older version of Paraview, you must manually interpolate mesh coordinates and field coordinates to a piecewise linear function space, represented with either a Lagrange (H1) or discontinuous - Lagrange (L2) basis. The :class:`~.output.VTKFile` is also setup + Lagrange (L2) basis. The :class:`~.vtk_output.VTKFile` is also setup to manage this issue. For instance, we can force the output to be discontinuous piecewise linears via @@ -197,7 +197,7 @@ pressure in a fluids models. This is possible either by having a separate output file for each field, or by saving multiple fields to the same output file. The latter may be more convenient for subsequent analysis. To do this, we just need to pass multiple -:class:`function `\s to :meth:`~.output.VTKFile.write`. +:class:`function `\s to :meth:`~.vtk_output.VTKFile.write`. .. code-block:: python3 @@ -376,7 +376,7 @@ Last but not least, vector fields defined on a vertex-only mesh can be visualise Writing vertex-only mesh data to VTK ++++++++++++++++++++++++++++++++++++ -Vertex-only mesh data can be written to VTK output enabling point data visualisations in third-party software such as ParaView. A :class:`~.output.VTKFile` accepts :class:`function `\s +Vertex-only mesh data can be written to VTK output enabling point data visualisations in third-party software such as ParaView. A :class:`~.vtk_output.VTKFile` accepts :class:`function `\s defined on a :func:`firedrake.VertexOnlyMesh` in the same way as functions defined on ordinary meshes. The output includes the point coordinates, the values of any supplied function(s), and a persistent particle ID field. In ParaView, for instance, this ID field can be used to colour particles by identity. diff --git a/firedrake/mesh.py b/firedrake/mesh.py index b98aa72892..20196596f8 100644 --- a/firedrake/mesh.py +++ b/firedrake/mesh.py @@ -38,7 +38,7 @@ import firedrake.extrusion_utils as eutils import firedrake.cython.rtree as rtree import firedrake.utils as utils -from firedrake.utils import IntType, IntType_c, RealType, RealType_c, as_ctypes, cached_property_until, complex_mode +from firedrake.utils import IntType, IntType_c, RealType, RealType_c, as_ctypes, cached_property_until from firedrake.logging import logger from firedrake.parameters import parameters from firedrake.petsc import PETSc, DEFAULT_PARTITIONER From 168b4c1d165c95422bae5eda9b4015f2aa676df4 Mon Sep 17 00:00:00 2001 From: nwng04 Date: Sun, 6 Sep 2026 14:06:51 +0100 Subject: [PATCH 26/28] Comment out __all__ declarations in firedrake modules --- docs/source/interpolation.rst | 2 +- docs/source/variational-problems.rst | 12 ++-- firedrake/adjoint/transformed_functional.py | 10 ++-- firedrake/adjoint_utils/checkpointing.py | 6 +- firedrake/bcs.py | 2 +- firedrake/checkpointing.py | 2 +- firedrake/cofunction.py | 2 +- firedrake/eigensolver.py | 4 +- firedrake/fml/form_manipulation_language.py | 4 +- firedrake/fml/replacement.py | 2 +- firedrake/function.py | 2 +- firedrake/functionspacedata.py | 2 +- firedrake/interpolation.py | 14 ++--- firedrake/linear_solver.py | 2 +- firedrake/matrix.py | 2 +- firedrake/matrix_free/operators.py | 2 +- firedrake/mesh.py | 12 ++-- firedrake/mg/interface.py | 2 +- firedrake/mg/mesh.py | 4 +- firedrake/mg/opencascade_mh.py | 2 +- firedrake/norms.py | 2 +- firedrake/output/paraview_reordering.py | 16 ++--- firedrake/output/vtk_output.py | 2 +- firedrake/parameters.py | 2 +- firedrake/parloops.py | 2 +- firedrake/petsc.py | 2 +- firedrake/preconditioners/asm.py | 2 +- firedrake/preconditioners/base.py | 2 +- firedrake/preconditioners/bddc.py | 2 +- firedrake/preconditioners/facet_split.py | 2 +- firedrake/preconditioners/fdm.py | 2 +- firedrake/preconditioners/hiptmair.py | 2 +- firedrake/preconditioners/hypre_ads.py | 2 +- firedrake/preconditioners/low_order.py | 2 +- firedrake/preconditioners/offload.py | 2 +- firedrake/projection.py | 2 +- firedrake/randomfunctiongen.py | 2 +- firedrake/slate/slac/compiler.py | 2 +- firedrake/slate/slate.py | 8 +-- .../static_condensation/hybridization.py | 2 +- firedrake/slope_limiter/limiter.py | 2 +- .../slope_limiter/vertex_based_limiter.py | 2 +- firedrake/supermeshing.py | 2 +- firedrake/ufl_expr.py | 8 +-- firedrake/utility_meshes.py | 60 +++++++++---------- firedrake/variational_solver.py | 2 +- 46 files changed, 113 insertions(+), 113 deletions(-) diff --git a/docs/source/interpolation.rst b/docs/source/interpolation.rst index 5be151810d..3398a7bafc 100644 --- a/docs/source/interpolation.rst +++ b/docs/source/interpolation.rst @@ -78,7 +78,7 @@ including: :py:class:`~ufl.SpatialCoordinate`, and in reference space as :py:class:`ufl.geometry.CellCoordinate`. * Firedrake :py:class:`function `\s, derivatives of - :py:class:`function `\s, and :py:class:`constant `\s. + :py:class:`function `\s, and :py:class:`Constant `\s. * Literal numbers, basic arithmetic operations, and also mathematical functions such as ``sin``, ``cos``, ``sqrt``, ``abs``, etc. * Conditional expressions using UFL :py:mod:`~ufl.conditional`. diff --git a/docs/source/variational-problems.rst b/docs/source/variational-problems.rst index c929e5d082..9792f883ef 100644 --- a/docs/source/variational-problems.rst +++ b/docs/source/variational-problems.rst @@ -524,13 +524,13 @@ but may vary in time. For example, a time-varying diffusivity, or a time-dependent forcing function. Although you can create a new form for each new value of this constant, this will not be efficient, since Firedrake must generate new code each time the value changes. A -better option is to use a :py:class:`constant ` coefficient. This +better option is to use a :py:class:`Constant ` coefficient. This object behaves exactly like a :py:class:`function `, except that it has a single value over the whole mesh. One may assign a new value to -the :py:class:`constant ` using the :py:meth:`~.Constant.assign` +the :py:class:`Constant ` using the :py:meth:`Constant.assign ` method. As an example, let us consider a form which contains a time varying constant which we wish to assemble in a time loop. We can use -a :py:class:`constant ` to do this: +a :py:class:`Constant ` to do this: .. code-block:: python3 @@ -550,7 +550,7 @@ a :py:class:`constant ` to do this: .. warning:: Although UFL supports computing the derivative of a form with - respect to a :py:class:`constant `, the resulting form will have + respect to a :py:class:`Constant `, the resulting form will have an unknown in the reals, which is currently unsupported by Firedrake. @@ -582,7 +582,7 @@ described in their respective constructor documentation. For externally generated meshes, Firedrake just uses whichever ids the mesh generator provided. The ``value`` may be either a scalar, or more generally a UFL expression, for example a :class:`function ` or -:py:class:`constant `, of the appropriate shape. You may also supply +:py:class:`Constant `, of the appropriate shape. You may also supply an iterable of literal constants: .. code-block:: python3 @@ -687,7 +687,7 @@ object. Note that if you use a literal value to initialise the boundary condition object within the timestepping loop, this will necessitate a recompilation of code every time the boundary condition changes. For this reason we either recommend using a -:py:class:`constant ` if the boundary condition is spatially uniform, +:py:class:`Constant ` if the boundary condition is spatially uniform, or a UFL expression if it has both space and time-dependence. For example, a purely time-varying boundary condition might be implemented as: diff --git a/firedrake/adjoint/transformed_functional.py b/firedrake/adjoint/transformed_functional.py index ce739edf4d..4c7d529dc0 100644 --- a/firedrake/adjoint/transformed_functional.py +++ b/firedrake/adjoint/transformed_functional.py @@ -14,11 +14,11 @@ from pyadjoint.reduced_functional import AbstractReducedFunctional import ufl -__all__ = \ - [ - "L2RieszMap", - "L2TransformedFunctional" - ] +# __all__ = \ +# [ +# "L2RieszMap", +# "L2TransformedFunctional" +# ] @contextmanager diff --git a/firedrake/adjoint_utils/checkpointing.py b/firedrake/adjoint_utils/checkpointing.py index a18eac5521..5945ebc8e5 100644 --- a/firedrake/adjoint_utils/checkpointing.py +++ b/firedrake/adjoint_utils/checkpointing.py @@ -14,9 +14,9 @@ disk_checkpointing_callback["firedrake"] = "Please call enable_disk_checkpointing() "\ "before checkpointing on the disk." -__all__ = ["enable_disk_checkpointing", "disk_checkpointing", - "pause_disk_checkpointing", "continue_disk_checkpointing", - "stop_disk_checkpointing", "checkpointable_mesh"] +# __all__ = ["enable_disk_checkpointing", "disk_checkpointing", +# "pause_disk_checkpointing", "continue_disk_checkpointing", +# "stop_disk_checkpointing", "checkpointable_mesh"] def current_checkpoint_file(init=None): diff --git a/firedrake/bcs.py b/firedrake/bcs.py index 071b78d779..396c5879f3 100644 --- a/firedrake/bcs.py +++ b/firedrake/bcs.py @@ -25,7 +25,7 @@ from firedrake.function import Function from firedrake.cofunction import Cofunction -__all__ = ['homogenize', 'EquationBC'] +#__all__ = ['homogenize', 'EquationBC'] class BCBase(object): diff --git a/firedrake/checkpointing.py b/firedrake/checkpointing.py index acbc9e7c6b..32ba12e5a7 100644 --- a/firedrake/checkpointing.py +++ b/firedrake/checkpointing.py @@ -23,7 +23,7 @@ import h5py -__all__ = ["HDF5File", "FILE_READ", "FILE_CREATE", "FILE_UPDATE"] +# __all__ = ["HDF5File", "FILE_READ", "FILE_CREATE", "FILE_UPDATE"] FILE_READ = PETSc.Viewer.Mode.READ diff --git a/firedrake/cofunction.py b/firedrake/cofunction.py index 7574e210e2..f65e457f10 100644 --- a/firedrake/cofunction.py +++ b/firedrake/cofunction.py @@ -16,7 +16,7 @@ from firedrake.petsc import PETSc -__all__ = ["RieszMap"] +# __all__ = ["RieszMap"] class Cofunction(ufl.Cofunction, CofunctionMixin): diff --git a/firedrake/eigensolver.py b/firedrake/eigensolver.py index be768b3049..54feba1756 100644 --- a/firedrake/eigensolver.py +++ b/firedrake/eigensolver.py @@ -11,8 +11,8 @@ from slepc4py import SLEPc except ImportError: SLEPc = None -__all__ = ["LinearEigenproblem", - "LinearEigensolver"] +#__all__ = ["LinearEigenproblem", +# "LinearEigensolver"] class LinearEigenproblem: diff --git a/firedrake/fml/form_manipulation_language.py b/firedrake/fml/form_manipulation_language.py index dafba9d99a..277eac8d66 100644 --- a/firedrake/fml/form_manipulation_language.py +++ b/firedrake/fml/form_manipulation_language.py @@ -7,8 +7,8 @@ from typing import Any, Callable, Mapping, Optional, Sequence, Tuple, Union -__all__ = ["Label", "Term", "LabelledForm", "identity", "drop", "all_terms", - "keep", "subject", "name_label"] +# __all__ = ["Label", "Term", "LabelledForm", "identity", "drop", "all_terms", +# "keep", "subject", "name_label"] # ---------------------------------------------------------------------------- # # Core routines for filtering terms diff --git a/firedrake/fml/replacement.py b/firedrake/fml/replacement.py index 08610fddd6..5028f144d4 100644 --- a/firedrake/fml/replacement.py +++ b/firedrake/fml/replacement.py @@ -7,7 +7,7 @@ from firedrake import split, MixedElement, Function, Argument from typing import Callable, Optional, Union -__all__ = ["replace_test_function", "replace_trial_function", "replace_subject"] +#__all__ = ["replace_test_function", "replace_trial_function", "replace_subject"] # ---------------------------------------------------------------------------- # diff --git a/firedrake/function.py b/firedrake/function.py index ceefb608ce..7bfdbebd5b 100644 --- a/firedrake/function.py +++ b/firedrake/function.py @@ -30,7 +30,7 @@ from firedrake.exceptions import PointNotInDomainError -__all__ = ['PointEvaluator'] +#__all__ = ['PointEvaluator'] class _CFunction(ctypes.Structure): diff --git a/firedrake/functionspacedata.py b/firedrake/functionspacedata.py index a5ab93e549..3957550127 100644 --- a/firedrake/functionspacedata.py +++ b/firedrake/functionspacedata.py @@ -34,7 +34,7 @@ from firedrake.petsc import PETSc -__all__ = ("get_shared_data", ) +#__all__ = ("get_shared_data", ) @PETSc.Log.EventDecorator("FunctionSpaceData: CreateElement") diff --git a/firedrake/interpolation.py b/firedrake/interpolation.py index 58823f5451..957bf703de 100644 --- a/firedrake/interpolation.py +++ b/firedrake/interpolation.py @@ -50,13 +50,13 @@ from pyadjoint.tape import no_annotations -__all__ = ( - "interpolate", - "Interpolate", - "get_interpolator", - "InterpolateOptions", - "Interpolator" -) +# __all__ = ( +# "interpolate", +# "Interpolate", +# "get_interpolator", +# "InterpolateOptions", +# "Interpolator" +# ) @dataclass(kw_only=True) diff --git a/firedrake/linear_solver.py b/firedrake/linear_solver.py index 4371584f6c..7be6695ee1 100644 --- a/firedrake/linear_solver.py +++ b/firedrake/linear_solver.py @@ -3,7 +3,7 @@ from firedrake.petsc import PETSc from firedrake.variational_solver import LinearVariationalProblem, LinearVariationalSolver -__all__ = ["LinearSolver"] +#__all__ = ["LinearSolver"] class LinearSolver(LinearVariationalSolver): diff --git a/firedrake/matrix.py b/firedrake/matrix.py index c588a5900e..1755c876c8 100644 --- a/firedrake/matrix.py +++ b/firedrake/matrix.py @@ -11,7 +11,7 @@ from firedrake.matrix_free import ImplicitMatrixContext from firedrake.slate import slate -__all__ = ("MatrixBase", "ImplicitMatrix", "AssembledMatrix") +#__all__ = ("MatrixBase", "ImplicitMatrix", "AssembledMatrix") class DummyOP2Mat: diff --git a/firedrake/matrix_free/operators.py b/firedrake/matrix_free/operators.py index e7ff2616af..1e3cdc48b9 100644 --- a/firedrake/matrix_free/operators.py +++ b/firedrake/matrix_free/operators.py @@ -17,7 +17,7 @@ from ufl.form import ZeroBaseForm -__all__ = ("ImplicitMatrixContext", ) +#__all__ = ("ImplicitMatrixContext", ) @PETSc.Log.EventDecorator() diff --git a/firedrake/mesh.py b/firedrake/mesh.py index 20196596f8..3808808f18 100644 --- a/firedrake/mesh.py +++ b/firedrake/mesh.py @@ -60,12 +60,12 @@ from firedrake import CoordinatelessFunction, Function -__all__ = [ - 'RelabeledMesh', 'SubDomainData', 'UNMARKED', - 'DistributedMeshOverlapType', 'DEFAULT_MESH_NAME', 'VertexOnlyMeshTopology', - 'MeshSequenceGeometry', 'MeshSequenceTopology', - 'Submesh' -] +# __all__ = [ +# 'RelabeledMesh', 'SubDomainData', 'UNMARKED', +# 'DistributedMeshOverlapType', 'DEFAULT_MESH_NAME', 'VertexOnlyMeshTopology', +# 'MeshSequenceGeometry', 'MeshSequenceTopology', +# 'Submesh' +# ] _cells = { diff --git a/firedrake/mg/interface.py b/firedrake/mg/interface.py index 4c544535cf..e2b4545a28 100644 --- a/firedrake/mg/interface.py +++ b/firedrake/mg/interface.py @@ -9,7 +9,7 @@ from . import kernels -__all__ = ["prolong", "restrict", "inject"] +#__all__ = ["prolong", "restrict", "inject"] def check_arguments(coarse, fine, needs_dual=False): diff --git a/firedrake/mg/mesh.py b/firedrake/mg/mesh.py index 801cc45c63..a5cc24d074 100644 --- a/firedrake/mg/mesh.py +++ b/firedrake/mg/mesh.py @@ -15,8 +15,8 @@ import firedrake.cython.dmcommon as dmcommon from .utils import set_level -__all__ = ("HierarchyBase", "MeshHierarchy", "ExtrudedMeshHierarchy", "NonNestedHierarchy", - "SemiCoarsenedExtrudedHierarchy", "SubmeshHierarchy") +# __all__ = ("HierarchyBase", "MeshHierarchy", "ExtrudedMeshHierarchy", "NonNestedHierarchy", +# "SemiCoarsenedExtrudedHierarchy", "SubmeshHierarchy") def make_unoverlapped_dm(dm): diff --git a/firedrake/mg/opencascade_mh.py b/firedrake/mg/opencascade_mh.py index d1e5c6c843..5f60a8cdd1 100644 --- a/firedrake/mg/opencascade_mh.py +++ b/firedrake/mg/opencascade_mh.py @@ -8,7 +8,7 @@ import warnings -__all__ = ("OpenCascadeMeshHierarchy",) +#__all__ = ("OpenCascadeMeshHierarchy",) def OpenCascadeMeshHierarchy(stepfile, element_size, levels, comm=COMM_WORLD, distribution_parameters=None, callbacks=None, order=1, mh_constructor=MeshHierarchy, cache=True, verbose=True, gmsh="gmsh", project_refinements_to_cad=True, reorder=None): diff --git a/firedrake/norms.py b/firedrake/norms.py index 605b1bd6ba..f1b718ae37 100644 --- a/firedrake/norms.py +++ b/firedrake/norms.py @@ -5,7 +5,7 @@ from firedrake.logging import warning from firedrake.petsc import PETSc -__all__ = ['errornorm', 'norm'] +#__all__ = ['errornorm', 'norm'] @PETSc.Log.EventDecorator() diff --git a/firedrake/output/paraview_reordering.py b/firedrake/output/paraview_reordering.py index 8b6edb147d..5a4f090b07 100644 --- a/firedrake/output/paraview_reordering.py +++ b/firedrake/output/paraview_reordering.py @@ -17,14 +17,14 @@ ) -__all__ = ( - "vtk_lagrange_tet_reorder", - "vtk_lagrange_hex_reorder", - "vtk_lagrange_interval_reorder", - "vtk_lagrange_triangle_reorder", - "vtk_lagrange_quad_reorder", - "vtk_lagrange_wedge_reorder", -) +# __all__ = ( +# "vtk_lagrange_tet_reorder", +# "vtk_lagrange_hex_reorder", +# "vtk_lagrange_interval_reorder", +# "vtk_lagrange_triangle_reorder", +# "vtk_lagrange_quad_reorder", +# "vtk_lagrange_wedge_reorder", +# ) def firedrake_local_to_cart(element): diff --git a/firedrake/output/vtk_output.py b/firedrake/output/vtk_output.py index 37dc3a739c..730810306c 100644 --- a/firedrake/output/vtk_output.py +++ b/firedrake/output/vtk_output.py @@ -13,7 +13,7 @@ from firedrake.utils import IntType from .paraview_reordering import * -__all__ = ("VTKFile",) +#__all__ = ("VTKFile",) VTK_VERTEX = 1 diff --git a/firedrake/parameters.py b/firedrake/parameters.py index 5863e76a77..3be4030ad7 100644 --- a/firedrake/parameters.py +++ b/firedrake/parameters.py @@ -6,7 +6,7 @@ max_float = sys.float_info[0] -__all__ = ['Parameters', 'parameters', 'disable_performance_optimisations'] +#__all__ = ['Parameters', 'parameters', 'disable_performance_optimisations'] class Parameters(dict): diff --git a/firedrake/parloops.py b/firedrake/parloops.py index aeb44b2caf..aac4f6769d 100644 --- a/firedrake/parloops.py +++ b/firedrake/parloops.py @@ -20,7 +20,7 @@ kernel_cache = LRUCache(maxsize=128) -__all__ = ['par_loop', 'direct', 'READ', 'WRITE', 'RW', 'INC', 'MIN', 'MAX'] +#__all__ = ['par_loop', 'direct', 'READ', 'WRITE', 'RW', 'INC', 'MIN', 'MAX'] class _DirectLoop(object): diff --git a/firedrake/petsc.py b/firedrake/petsc.py index 6eb2ab0864..a341940697 100644 --- a/firedrake/petsc.py +++ b/firedrake/petsc.py @@ -10,7 +10,7 @@ from pyop2 import mpi -__all__ = ("PETSc",) +#__all__ = ("PETSc",) class FiredrakePETScError(Exception): diff --git a/firedrake/preconditioners/asm.py b/firedrake/preconditioners/asm.py index 5a2f8f8b2a..483a7d5fd8 100644 --- a/firedrake/preconditioners/asm.py +++ b/firedrake/preconditioners/asm.py @@ -12,7 +12,7 @@ import numpy -__all__ = ("ASMPatchPC", "ASMVankaPC", "ASMLinesmoothPC") +#__all__ = ("ASMPatchPC", "ASMVankaPC", "ASMLinesmoothPC") class ASMPatchPC(PCBase): diff --git a/firedrake/preconditioners/base.py b/firedrake/preconditioners/base.py index 149c7c88d6..6314714f53 100644 --- a/firedrake/preconditioners/base.py +++ b/firedrake/preconditioners/base.py @@ -6,7 +6,7 @@ from firedrake.bcs import BCBase import ufl -__all__ = ("PCBase", "SNESBase") +#__all__ = ("PCBase", "SNESBase") class PCSNESBase(object, metaclass=abc.ABCMeta): diff --git a/firedrake/preconditioners/bddc.py b/firedrake/preconditioners/bddc.py index c35b16f899..d3f9584f02 100644 --- a/firedrake/preconditioners/bddc.py +++ b/firedrake/preconditioners/bddc.py @@ -21,7 +21,7 @@ from pyop2.utils import as_tuple import numpy -__all__ = ("BDDCPC",) +#__all__ = ("BDDCPC",) class BDDCPC(PCBase): diff --git a/firedrake/preconditioners/facet_split.py b/firedrake/preconditioners/facet_split.py index 08ac21aeb0..1619250d46 100644 --- a/firedrake/preconditioners/facet_split.py +++ b/firedrake/preconditioners/facet_split.py @@ -10,7 +10,7 @@ from pyop2.mpi import temp_internal_comm -__all__ = ['FacetSplitPC'] +#__all__ = ['FacetSplitPC'] class FacetSplitPC(PCBase): diff --git a/firedrake/preconditioners/fdm.py b/firedrake/preconditioners/fdm.py index 33ea7a67ff..ef1be57460 100644 --- a/firedrake/preconditioners/fdm.py +++ b/firedrake/preconditioners/fdm.py @@ -36,7 +36,7 @@ import ctypes -__all__ = ("PoissonFDMPC") +#__all__ = ("PoissonFDMPC") class FDMPC(PCBase): diff --git a/firedrake/preconditioners/hiptmair.py b/firedrake/preconditioners/hiptmair.py index c0e74a563e..4ca18998d2 100644 --- a/firedrake/preconditioners/hiptmair.py +++ b/firedrake/preconditioners/hiptmair.py @@ -17,7 +17,7 @@ from functools import cached_property -__all__ = ("TwoLevelPC", "HiptmairPC") +#__all__ = ("TwoLevelPC", "HiptmairPC") class TwoLevelPC(PCBase): diff --git a/firedrake/preconditioners/hypre_ads.py b/firedrake/preconditioners/hypre_ads.py index b4c2d31850..ae2358c283 100644 --- a/firedrake/preconditioners/hypre_ads.py +++ b/firedrake/preconditioners/hypre_ads.py @@ -10,7 +10,7 @@ from ufl import grad, curl, SpatialCoordinate from pyop2.utils import as_tuple -__all__ = ("HypreADS",) +#__all__ = ("HypreADS",) class HypreADS(PCBase): diff --git a/firedrake/preconditioners/low_order.py b/firedrake/preconditioners/low_order.py index f09d5412ef..5ebb15d409 100644 --- a/firedrake/preconditioners/low_order.py +++ b/firedrake/preconditioners/low_order.py @@ -1,6 +1,6 @@ from firedrake.preconditioners.pmg import PMGPC, PMGSNES -__all__ = ("LORPC") +#__all__ = ("LORPC") class P1PC(PMGPC): diff --git a/firedrake/preconditioners/offload.py b/firedrake/preconditioners/offload.py index 7cfe505edb..f67600d02a 100644 --- a/firedrake/preconditioners/offload.py +++ b/firedrake/preconditioners/offload.py @@ -4,7 +4,7 @@ import firedrake.dmhooks as dmhooks -__all__ = ("OffloadPC",) +#__all__ = ("OffloadPC",) _device_vector_impls = { diff --git a/firedrake/projection.py b/firedrake/projection.py index 5a2d83f371..6ad7f9af76 100644 --- a/firedrake/projection.py +++ b/firedrake/projection.py @@ -16,7 +16,7 @@ from firedrake.adjoint_utils import annotate_project -__all__ = ['project', 'Projector'] +#__all__ = ['project', 'Projector'] def sanitise_input(v, V): diff --git a/firedrake/randomfunctiongen.py b/firedrake/randomfunctiongen.py index 8f03504754..3073afdbb4 100644 --- a/firedrake/randomfunctiongen.py +++ b/firedrake/randomfunctiongen.py @@ -110,7 +110,7 @@ _deprecated_attributes = ['RandomGenerator', ] -__all__ = [name for name, _ in inspect.getmembers(randomgen, inspect.isclass)] + _deprecated_attributes +#__all__ = [name for name, _ in inspect.getmembers(randomgen, inspect.isclass)] + _deprecated_attributes # >>> [name for name, _ in inspect.getmembers(numpy.random) if not name.startswith('_')] _known_attributes = ['BitGenerator', 'Generator', 'MT19937', 'PCG64', 'PCG64DXSM', 'Philox', 'RandomState', 'SFC64', 'SeedSequence', 'beta', 'binomial', 'bit_generator', 'bytes', 'chisquare', 'choice', 'default_rng', 'dirichlet', 'exponential', 'f', 'gamma', 'geometric', 'get_bit_generator', 'get_state', 'gumbel', 'hypergeometric', 'laplace', 'logistic', 'lognormal', 'logseries', 'mtrand', 'multinomial', 'multivariate_normal', 'negative_binomial', 'noncentral_chisquare', 'noncentral_f', 'normal', 'pareto', 'permutation', 'poisson', 'power', 'rand', 'randint', 'randn', 'random', 'random_integers', 'random_sample', 'ranf', 'rayleigh', 'sample', 'seed', 'set_bit_generator', 'set_state', 'shuffle', 'standard_cauchy', 'standard_exponential', 'standard_gamma', 'standard_normal', 'standard_t', 'test', 'triangular', 'uniform', 'vonmises', 'wald', 'weibull', 'zipf'] diff --git a/firedrake/slate/slac/compiler.py b/firedrake/slate/slac/compiler.py index 567701ef4b..c68e0692d9 100644 --- a/firedrake/slate/slac/compiler.py +++ b/firedrake/slate/slac/compiler.py @@ -40,7 +40,7 @@ from petsc4py import PETSc -__all__ = ['compile_expression'] +#__all__ = ['compile_expression'] GREEN = "\033[1;37;32m%s\033[0m" diff --git a/firedrake/slate/slate.py b/firedrake/slate/slate.py index 03ba45aa7b..8bd667a81a 100644 --- a/firedrake/slate/slate.py +++ b/firedrake/slate/slate.py @@ -41,10 +41,10 @@ from tsfc.ufl_utils import extract_firedrake_constants -__all__ = ['AssembledVector', 'Block', 'Factorization', 'Tensor', - 'Inverse', 'Transpose', 'Negative', - 'Add', 'Mul', 'Solve', 'BlockAssembledVector', 'DiagonalTensor', - 'Reciprocal'] +# __all__ = ['AssembledVector', 'Block', 'Factorization', 'Tensor', +# 'Inverse', 'Transpose', 'Negative', +# 'Add', 'Mul', 'Solve', 'BlockAssembledVector', 'DiagonalTensor', +# 'Reciprocal'] # BlockFunction description type BlockFunction = namedtuple('BlockFunction', ['split_function', 'indices', 'orig_function']) diff --git a/firedrake/slate/static_condensation/hybridization.py b/firedrake/slate/static_condensation/hybridization.py index 2bfc075b19..d82ae536e8 100644 --- a/firedrake/slate/static_condensation/hybridization.py +++ b/firedrake/slate/static_condensation/hybridization.py @@ -12,7 +12,7 @@ from firedrake.slate.static_condensation.la_utils import SchurComplementBuilder from firedrake.ufl_expr import adjoint -__all__ = ['SchurComplementBuilder'] +#__all__ = ['SchurComplementBuilder'] class HybridizationPC(SCBase): diff --git a/firedrake/slope_limiter/limiter.py b/firedrake/slope_limiter/limiter.py index f4904136a8..b3a9d44257 100644 --- a/firedrake/slope_limiter/limiter.py +++ b/firedrake/slope_limiter/limiter.py @@ -1,6 +1,6 @@ from abc import ABCMeta, abstractmethod -__all__ = ("Limiter",) +#__all__ = ("Limiter",) class Limiter(object, metaclass=ABCMeta): diff --git a/firedrake/slope_limiter/vertex_based_limiter.py b/firedrake/slope_limiter/vertex_based_limiter.py index e06682ee26..d48152b3ba 100644 --- a/firedrake/slope_limiter/vertex_based_limiter.py +++ b/firedrake/slope_limiter/vertex_based_limiter.py @@ -7,7 +7,7 @@ from firedrake.slope_limiter.limiter import Limiter from firedrake import utils from ufl import inner -__all__ = ("VertexBasedLimiter",) +#__all__ = ("VertexBasedLimiter",) class VertexBasedLimiter(Limiter): diff --git a/firedrake/supermeshing.py b/firedrake/supermeshing.py index 6d2638e3a3..c6c4c305b1 100644 --- a/firedrake/supermeshing.py +++ b/firedrake/supermeshing.py @@ -25,7 +25,7 @@ from loopy import generate_code_v2 -__all__ = ["assemble_mixed_mass_matrix", "intersection_finder"] +#__all__ = ["assemble_mixed_mass_matrix", "intersection_finder"] # TODO replace with KAIJ (we require petsc4py wrappers) diff --git a/firedrake/ufl_expr.py b/firedrake/ufl_expr.py index 93406c6fb4..5ec6e785ce 100644 --- a/firedrake/ufl_expr.py +++ b/firedrake/ufl_expr.py @@ -12,10 +12,10 @@ from functools import cached_property -__all__ = ['Argument', 'Coargument', 'TestFunction', 'TrialFunction', - 'TestFunctions', 'TrialFunctions', - 'derivative', 'adjoint', - 'action', 'CellSize', 'FacetNormal'] +# __all__ = ['Argument', 'Coargument', 'TestFunction', 'TrialFunction', +# 'TestFunctions', 'TrialFunctions', +# 'derivative', 'adjoint', +# 'action', 'CellSize', 'FacetNormal'] class Argument(ufl.argument.Argument): diff --git a/firedrake/utility_meshes.py b/firedrake/utility_meshes.py index f2795bcf2b..6627228e12 100644 --- a/firedrake/utility_meshes.py +++ b/firedrake/utility_meshes.py @@ -34,36 +34,36 @@ from pyadjoint.tape import no_annotations -__all__ = [ - "UnitIntervalMesh", - "PeriodicUnitIntervalMesh", - "UnitTriangleMesh", - "TensorRectangleMesh", - "SquareMesh", - "UnitSquareMesh", - "PeriodicRectangleMesh", - "PeriodicSquareMesh", - "PeriodicUnitSquareMesh", - "CircleManifoldMesh", - "UnitDiskMesh", - "UnitBallMesh", - "UnitTetrahedronMesh", - "TensorBoxMesh", - "CubeMesh", - "UnitCubeMesh", - "PeriodicBoxMesh", - "PeriodicUnitCubeMesh", - "IcosahedralSphereMesh", - "UnitIcosahedralSphereMesh", - "OctahedralSphereMesh", - "UnitOctahedralSphereMesh", - "CubedSphereMesh", - "UnitCubedSphereMesh", - "TorusMesh", - "AnnulusMesh", - "SolidTorusMesh", - "CylinderMesh", -] +# __all__ = [ +# "UnitIntervalMesh", +# "PeriodicUnitIntervalMesh", +# "UnitTriangleMesh", +# "TensorRectangleMesh", +# "SquareMesh", +# "UnitSquareMesh", +# "PeriodicRectangleMesh", +# "PeriodicSquareMesh", +# "PeriodicUnitSquareMesh", +# "CircleManifoldMesh", +# "UnitDiskMesh", +# "UnitBallMesh", +# "UnitTetrahedronMesh", +# "TensorBoxMesh", +# "CubeMesh", +# "UnitCubeMesh", +# "PeriodicBoxMesh", +# "PeriodicUnitCubeMesh", +# "IcosahedralSphereMesh", +# "UnitIcosahedralSphereMesh", +# "OctahedralSphereMesh", +# "UnitOctahedralSphereMesh", +# "CubedSphereMesh", +# "UnitCubedSphereMesh", +# "TorusMesh", +# "AnnulusMesh", +# "SolidTorusMesh", +# "CylinderMesh", +# ] distribution_parameters_no_overlap = {"partition": True, diff --git a/firedrake/variational_solver.py b/firedrake/variational_solver.py index 906742ce73..62af9e5a1e 100644 --- a/firedrake/variational_solver.py +++ b/firedrake/variational_solver.py @@ -18,7 +18,7 @@ from functools import cached_property from collections.abc import Callable -__all__ = ["LinearVariationalProblem"] +#__all__ = ["LinearVariationalProblem"] def check_pde_args(F, J, Jp, E=None): From 4e3e9d8bfd0f8eecd5f5db5cd5854b4a7967657b Mon Sep 17 00:00:00 2001 From: nwng04 Date: Sun, 6 Sep 2026 14:25:13 +0100 Subject: [PATCH 27/28] Revert commenting of __all__ declarations --- firedrake/adjoint/transformed_functional.py | 10 ++-- firedrake/adjoint_utils/checkpointing.py | 6 +- firedrake/bcs.py | 2 +- firedrake/checkpointing.py | 2 +- firedrake/cofunction.py | 2 +- firedrake/eigensolver.py | 4 +- firedrake/fml/form_manipulation_language.py | 4 +- firedrake/fml/replacement.py | 2 +- firedrake/function.py | 2 +- firedrake/functionspacedata.py | 2 +- firedrake/interpolation.py | 14 ++--- firedrake/linear_solver.py | 2 +- firedrake/matrix.py | 2 +- firedrake/matrix_free/operators.py | 2 +- firedrake/mesh.py | 12 ++-- firedrake/mg/interface.py | 2 +- firedrake/mg/mesh.py | 4 +- firedrake/mg/opencascade_mh.py | 2 +- firedrake/norms.py | 2 +- firedrake/output/paraview_reordering.py | 16 ++--- firedrake/output/vtk_output.py | 2 +- firedrake/parameters.py | 2 +- firedrake/parloops.py | 2 +- firedrake/petsc.py | 2 +- firedrake/preconditioners/asm.py | 2 +- firedrake/preconditioners/base.py | 2 +- firedrake/preconditioners/bddc.py | 2 +- firedrake/preconditioners/facet_split.py | 2 +- firedrake/preconditioners/fdm.py | 2 +- firedrake/preconditioners/hiptmair.py | 2 +- firedrake/preconditioners/hypre_ads.py | 2 +- firedrake/preconditioners/low_order.py | 2 +- firedrake/preconditioners/offload.py | 2 +- firedrake/projection.py | 2 +- firedrake/randomfunctiongen.py | 2 +- firedrake/slate/slac/compiler.py | 2 +- firedrake/slate/slate.py | 8 +-- .../static_condensation/hybridization.py | 2 +- firedrake/slope_limiter/limiter.py | 2 +- .../slope_limiter/vertex_based_limiter.py | 2 +- firedrake/supermeshing.py | 2 +- firedrake/ufl_expr.py | 8 +-- firedrake/utility_meshes.py | 60 +++++++++---------- firedrake/variational_solver.py | 2 +- 44 files changed, 106 insertions(+), 106 deletions(-) diff --git a/firedrake/adjoint/transformed_functional.py b/firedrake/adjoint/transformed_functional.py index 4c7d529dc0..ce739edf4d 100644 --- a/firedrake/adjoint/transformed_functional.py +++ b/firedrake/adjoint/transformed_functional.py @@ -14,11 +14,11 @@ from pyadjoint.reduced_functional import AbstractReducedFunctional import ufl -# __all__ = \ -# [ -# "L2RieszMap", -# "L2TransformedFunctional" -# ] +__all__ = \ + [ + "L2RieszMap", + "L2TransformedFunctional" + ] @contextmanager diff --git a/firedrake/adjoint_utils/checkpointing.py b/firedrake/adjoint_utils/checkpointing.py index 5945ebc8e5..a18eac5521 100644 --- a/firedrake/adjoint_utils/checkpointing.py +++ b/firedrake/adjoint_utils/checkpointing.py @@ -14,9 +14,9 @@ disk_checkpointing_callback["firedrake"] = "Please call enable_disk_checkpointing() "\ "before checkpointing on the disk." -# __all__ = ["enable_disk_checkpointing", "disk_checkpointing", -# "pause_disk_checkpointing", "continue_disk_checkpointing", -# "stop_disk_checkpointing", "checkpointable_mesh"] +__all__ = ["enable_disk_checkpointing", "disk_checkpointing", + "pause_disk_checkpointing", "continue_disk_checkpointing", + "stop_disk_checkpointing", "checkpointable_mesh"] def current_checkpoint_file(init=None): diff --git a/firedrake/bcs.py b/firedrake/bcs.py index 396c5879f3..071b78d779 100644 --- a/firedrake/bcs.py +++ b/firedrake/bcs.py @@ -25,7 +25,7 @@ from firedrake.function import Function from firedrake.cofunction import Cofunction -#__all__ = ['homogenize', 'EquationBC'] +__all__ = ['homogenize', 'EquationBC'] class BCBase(object): diff --git a/firedrake/checkpointing.py b/firedrake/checkpointing.py index 32ba12e5a7..acbc9e7c6b 100644 --- a/firedrake/checkpointing.py +++ b/firedrake/checkpointing.py @@ -23,7 +23,7 @@ import h5py -# __all__ = ["HDF5File", "FILE_READ", "FILE_CREATE", "FILE_UPDATE"] +__all__ = ["HDF5File", "FILE_READ", "FILE_CREATE", "FILE_UPDATE"] FILE_READ = PETSc.Viewer.Mode.READ diff --git a/firedrake/cofunction.py b/firedrake/cofunction.py index f65e457f10..7574e210e2 100644 --- a/firedrake/cofunction.py +++ b/firedrake/cofunction.py @@ -16,7 +16,7 @@ from firedrake.petsc import PETSc -# __all__ = ["RieszMap"] +__all__ = ["RieszMap"] class Cofunction(ufl.Cofunction, CofunctionMixin): diff --git a/firedrake/eigensolver.py b/firedrake/eigensolver.py index 54feba1756..be768b3049 100644 --- a/firedrake/eigensolver.py +++ b/firedrake/eigensolver.py @@ -11,8 +11,8 @@ from slepc4py import SLEPc except ImportError: SLEPc = None -#__all__ = ["LinearEigenproblem", -# "LinearEigensolver"] +__all__ = ["LinearEigenproblem", + "LinearEigensolver"] class LinearEigenproblem: diff --git a/firedrake/fml/form_manipulation_language.py b/firedrake/fml/form_manipulation_language.py index 277eac8d66..dafba9d99a 100644 --- a/firedrake/fml/form_manipulation_language.py +++ b/firedrake/fml/form_manipulation_language.py @@ -7,8 +7,8 @@ from typing import Any, Callable, Mapping, Optional, Sequence, Tuple, Union -# __all__ = ["Label", "Term", "LabelledForm", "identity", "drop", "all_terms", -# "keep", "subject", "name_label"] +__all__ = ["Label", "Term", "LabelledForm", "identity", "drop", "all_terms", + "keep", "subject", "name_label"] # ---------------------------------------------------------------------------- # # Core routines for filtering terms diff --git a/firedrake/fml/replacement.py b/firedrake/fml/replacement.py index 5028f144d4..08610fddd6 100644 --- a/firedrake/fml/replacement.py +++ b/firedrake/fml/replacement.py @@ -7,7 +7,7 @@ from firedrake import split, MixedElement, Function, Argument from typing import Callable, Optional, Union -#__all__ = ["replace_test_function", "replace_trial_function", "replace_subject"] +__all__ = ["replace_test_function", "replace_trial_function", "replace_subject"] # ---------------------------------------------------------------------------- # diff --git a/firedrake/function.py b/firedrake/function.py index 7bfdbebd5b..ceefb608ce 100644 --- a/firedrake/function.py +++ b/firedrake/function.py @@ -30,7 +30,7 @@ from firedrake.exceptions import PointNotInDomainError -#__all__ = ['PointEvaluator'] +__all__ = ['PointEvaluator'] class _CFunction(ctypes.Structure): diff --git a/firedrake/functionspacedata.py b/firedrake/functionspacedata.py index 3957550127..a5ab93e549 100644 --- a/firedrake/functionspacedata.py +++ b/firedrake/functionspacedata.py @@ -34,7 +34,7 @@ from firedrake.petsc import PETSc -#__all__ = ("get_shared_data", ) +__all__ = ("get_shared_data", ) @PETSc.Log.EventDecorator("FunctionSpaceData: CreateElement") diff --git a/firedrake/interpolation.py b/firedrake/interpolation.py index 957bf703de..58823f5451 100644 --- a/firedrake/interpolation.py +++ b/firedrake/interpolation.py @@ -50,13 +50,13 @@ from pyadjoint.tape import no_annotations -# __all__ = ( -# "interpolate", -# "Interpolate", -# "get_interpolator", -# "InterpolateOptions", -# "Interpolator" -# ) +__all__ = ( + "interpolate", + "Interpolate", + "get_interpolator", + "InterpolateOptions", + "Interpolator" +) @dataclass(kw_only=True) diff --git a/firedrake/linear_solver.py b/firedrake/linear_solver.py index 7be6695ee1..4371584f6c 100644 --- a/firedrake/linear_solver.py +++ b/firedrake/linear_solver.py @@ -3,7 +3,7 @@ from firedrake.petsc import PETSc from firedrake.variational_solver import LinearVariationalProblem, LinearVariationalSolver -#__all__ = ["LinearSolver"] +__all__ = ["LinearSolver"] class LinearSolver(LinearVariationalSolver): diff --git a/firedrake/matrix.py b/firedrake/matrix.py index 1755c876c8..c588a5900e 100644 --- a/firedrake/matrix.py +++ b/firedrake/matrix.py @@ -11,7 +11,7 @@ from firedrake.matrix_free import ImplicitMatrixContext from firedrake.slate import slate -#__all__ = ("MatrixBase", "ImplicitMatrix", "AssembledMatrix") +__all__ = ("MatrixBase", "ImplicitMatrix", "AssembledMatrix") class DummyOP2Mat: diff --git a/firedrake/matrix_free/operators.py b/firedrake/matrix_free/operators.py index 1e3cdc48b9..e7ff2616af 100644 --- a/firedrake/matrix_free/operators.py +++ b/firedrake/matrix_free/operators.py @@ -17,7 +17,7 @@ from ufl.form import ZeroBaseForm -#__all__ = ("ImplicitMatrixContext", ) +__all__ = ("ImplicitMatrixContext", ) @PETSc.Log.EventDecorator() diff --git a/firedrake/mesh.py b/firedrake/mesh.py index 3808808f18..20196596f8 100644 --- a/firedrake/mesh.py +++ b/firedrake/mesh.py @@ -60,12 +60,12 @@ from firedrake import CoordinatelessFunction, Function -# __all__ = [ -# 'RelabeledMesh', 'SubDomainData', 'UNMARKED', -# 'DistributedMeshOverlapType', 'DEFAULT_MESH_NAME', 'VertexOnlyMeshTopology', -# 'MeshSequenceGeometry', 'MeshSequenceTopology', -# 'Submesh' -# ] +__all__ = [ + 'RelabeledMesh', 'SubDomainData', 'UNMARKED', + 'DistributedMeshOverlapType', 'DEFAULT_MESH_NAME', 'VertexOnlyMeshTopology', + 'MeshSequenceGeometry', 'MeshSequenceTopology', + 'Submesh' +] _cells = { diff --git a/firedrake/mg/interface.py b/firedrake/mg/interface.py index e2b4545a28..4c544535cf 100644 --- a/firedrake/mg/interface.py +++ b/firedrake/mg/interface.py @@ -9,7 +9,7 @@ from . import kernels -#__all__ = ["prolong", "restrict", "inject"] +__all__ = ["prolong", "restrict", "inject"] def check_arguments(coarse, fine, needs_dual=False): diff --git a/firedrake/mg/mesh.py b/firedrake/mg/mesh.py index a5cc24d074..801cc45c63 100644 --- a/firedrake/mg/mesh.py +++ b/firedrake/mg/mesh.py @@ -15,8 +15,8 @@ import firedrake.cython.dmcommon as dmcommon from .utils import set_level -# __all__ = ("HierarchyBase", "MeshHierarchy", "ExtrudedMeshHierarchy", "NonNestedHierarchy", -# "SemiCoarsenedExtrudedHierarchy", "SubmeshHierarchy") +__all__ = ("HierarchyBase", "MeshHierarchy", "ExtrudedMeshHierarchy", "NonNestedHierarchy", + "SemiCoarsenedExtrudedHierarchy", "SubmeshHierarchy") def make_unoverlapped_dm(dm): diff --git a/firedrake/mg/opencascade_mh.py b/firedrake/mg/opencascade_mh.py index 5f60a8cdd1..d1e5c6c843 100644 --- a/firedrake/mg/opencascade_mh.py +++ b/firedrake/mg/opencascade_mh.py @@ -8,7 +8,7 @@ import warnings -#__all__ = ("OpenCascadeMeshHierarchy",) +__all__ = ("OpenCascadeMeshHierarchy",) def OpenCascadeMeshHierarchy(stepfile, element_size, levels, comm=COMM_WORLD, distribution_parameters=None, callbacks=None, order=1, mh_constructor=MeshHierarchy, cache=True, verbose=True, gmsh="gmsh", project_refinements_to_cad=True, reorder=None): diff --git a/firedrake/norms.py b/firedrake/norms.py index f1b718ae37..605b1bd6ba 100644 --- a/firedrake/norms.py +++ b/firedrake/norms.py @@ -5,7 +5,7 @@ from firedrake.logging import warning from firedrake.petsc import PETSc -#__all__ = ['errornorm', 'norm'] +__all__ = ['errornorm', 'norm'] @PETSc.Log.EventDecorator() diff --git a/firedrake/output/paraview_reordering.py b/firedrake/output/paraview_reordering.py index 5a4f090b07..8b6edb147d 100644 --- a/firedrake/output/paraview_reordering.py +++ b/firedrake/output/paraview_reordering.py @@ -17,14 +17,14 @@ ) -# __all__ = ( -# "vtk_lagrange_tet_reorder", -# "vtk_lagrange_hex_reorder", -# "vtk_lagrange_interval_reorder", -# "vtk_lagrange_triangle_reorder", -# "vtk_lagrange_quad_reorder", -# "vtk_lagrange_wedge_reorder", -# ) +__all__ = ( + "vtk_lagrange_tet_reorder", + "vtk_lagrange_hex_reorder", + "vtk_lagrange_interval_reorder", + "vtk_lagrange_triangle_reorder", + "vtk_lagrange_quad_reorder", + "vtk_lagrange_wedge_reorder", +) def firedrake_local_to_cart(element): diff --git a/firedrake/output/vtk_output.py b/firedrake/output/vtk_output.py index 730810306c..37dc3a739c 100644 --- a/firedrake/output/vtk_output.py +++ b/firedrake/output/vtk_output.py @@ -13,7 +13,7 @@ from firedrake.utils import IntType from .paraview_reordering import * -#__all__ = ("VTKFile",) +__all__ = ("VTKFile",) VTK_VERTEX = 1 diff --git a/firedrake/parameters.py b/firedrake/parameters.py index 3be4030ad7..5863e76a77 100644 --- a/firedrake/parameters.py +++ b/firedrake/parameters.py @@ -6,7 +6,7 @@ max_float = sys.float_info[0] -#__all__ = ['Parameters', 'parameters', 'disable_performance_optimisations'] +__all__ = ['Parameters', 'parameters', 'disable_performance_optimisations'] class Parameters(dict): diff --git a/firedrake/parloops.py b/firedrake/parloops.py index aac4f6769d..aeb44b2caf 100644 --- a/firedrake/parloops.py +++ b/firedrake/parloops.py @@ -20,7 +20,7 @@ kernel_cache = LRUCache(maxsize=128) -#__all__ = ['par_loop', 'direct', 'READ', 'WRITE', 'RW', 'INC', 'MIN', 'MAX'] +__all__ = ['par_loop', 'direct', 'READ', 'WRITE', 'RW', 'INC', 'MIN', 'MAX'] class _DirectLoop(object): diff --git a/firedrake/petsc.py b/firedrake/petsc.py index a341940697..6eb2ab0864 100644 --- a/firedrake/petsc.py +++ b/firedrake/petsc.py @@ -10,7 +10,7 @@ from pyop2 import mpi -#__all__ = ("PETSc",) +__all__ = ("PETSc",) class FiredrakePETScError(Exception): diff --git a/firedrake/preconditioners/asm.py b/firedrake/preconditioners/asm.py index 483a7d5fd8..5a2f8f8b2a 100644 --- a/firedrake/preconditioners/asm.py +++ b/firedrake/preconditioners/asm.py @@ -12,7 +12,7 @@ import numpy -#__all__ = ("ASMPatchPC", "ASMVankaPC", "ASMLinesmoothPC") +__all__ = ("ASMPatchPC", "ASMVankaPC", "ASMLinesmoothPC") class ASMPatchPC(PCBase): diff --git a/firedrake/preconditioners/base.py b/firedrake/preconditioners/base.py index 6314714f53..149c7c88d6 100644 --- a/firedrake/preconditioners/base.py +++ b/firedrake/preconditioners/base.py @@ -6,7 +6,7 @@ from firedrake.bcs import BCBase import ufl -#__all__ = ("PCBase", "SNESBase") +__all__ = ("PCBase", "SNESBase") class PCSNESBase(object, metaclass=abc.ABCMeta): diff --git a/firedrake/preconditioners/bddc.py b/firedrake/preconditioners/bddc.py index d3f9584f02..c35b16f899 100644 --- a/firedrake/preconditioners/bddc.py +++ b/firedrake/preconditioners/bddc.py @@ -21,7 +21,7 @@ from pyop2.utils import as_tuple import numpy -#__all__ = ("BDDCPC",) +__all__ = ("BDDCPC",) class BDDCPC(PCBase): diff --git a/firedrake/preconditioners/facet_split.py b/firedrake/preconditioners/facet_split.py index 1619250d46..08ac21aeb0 100644 --- a/firedrake/preconditioners/facet_split.py +++ b/firedrake/preconditioners/facet_split.py @@ -10,7 +10,7 @@ from pyop2.mpi import temp_internal_comm -#__all__ = ['FacetSplitPC'] +__all__ = ['FacetSplitPC'] class FacetSplitPC(PCBase): diff --git a/firedrake/preconditioners/fdm.py b/firedrake/preconditioners/fdm.py index ef1be57460..33ea7a67ff 100644 --- a/firedrake/preconditioners/fdm.py +++ b/firedrake/preconditioners/fdm.py @@ -36,7 +36,7 @@ import ctypes -#__all__ = ("PoissonFDMPC") +__all__ = ("PoissonFDMPC") class FDMPC(PCBase): diff --git a/firedrake/preconditioners/hiptmair.py b/firedrake/preconditioners/hiptmair.py index 4ca18998d2..c0e74a563e 100644 --- a/firedrake/preconditioners/hiptmair.py +++ b/firedrake/preconditioners/hiptmair.py @@ -17,7 +17,7 @@ from functools import cached_property -#__all__ = ("TwoLevelPC", "HiptmairPC") +__all__ = ("TwoLevelPC", "HiptmairPC") class TwoLevelPC(PCBase): diff --git a/firedrake/preconditioners/hypre_ads.py b/firedrake/preconditioners/hypre_ads.py index ae2358c283..b4c2d31850 100644 --- a/firedrake/preconditioners/hypre_ads.py +++ b/firedrake/preconditioners/hypre_ads.py @@ -10,7 +10,7 @@ from ufl import grad, curl, SpatialCoordinate from pyop2.utils import as_tuple -#__all__ = ("HypreADS",) +__all__ = ("HypreADS",) class HypreADS(PCBase): diff --git a/firedrake/preconditioners/low_order.py b/firedrake/preconditioners/low_order.py index 5ebb15d409..f09d5412ef 100644 --- a/firedrake/preconditioners/low_order.py +++ b/firedrake/preconditioners/low_order.py @@ -1,6 +1,6 @@ from firedrake.preconditioners.pmg import PMGPC, PMGSNES -#__all__ = ("LORPC") +__all__ = ("LORPC") class P1PC(PMGPC): diff --git a/firedrake/preconditioners/offload.py b/firedrake/preconditioners/offload.py index f67600d02a..7cfe505edb 100644 --- a/firedrake/preconditioners/offload.py +++ b/firedrake/preconditioners/offload.py @@ -4,7 +4,7 @@ import firedrake.dmhooks as dmhooks -#__all__ = ("OffloadPC",) +__all__ = ("OffloadPC",) _device_vector_impls = { diff --git a/firedrake/projection.py b/firedrake/projection.py index 6ad7f9af76..5a2d83f371 100644 --- a/firedrake/projection.py +++ b/firedrake/projection.py @@ -16,7 +16,7 @@ from firedrake.adjoint_utils import annotate_project -#__all__ = ['project', 'Projector'] +__all__ = ['project', 'Projector'] def sanitise_input(v, V): diff --git a/firedrake/randomfunctiongen.py b/firedrake/randomfunctiongen.py index 3073afdbb4..8f03504754 100644 --- a/firedrake/randomfunctiongen.py +++ b/firedrake/randomfunctiongen.py @@ -110,7 +110,7 @@ _deprecated_attributes = ['RandomGenerator', ] -#__all__ = [name for name, _ in inspect.getmembers(randomgen, inspect.isclass)] + _deprecated_attributes +__all__ = [name for name, _ in inspect.getmembers(randomgen, inspect.isclass)] + _deprecated_attributes # >>> [name for name, _ in inspect.getmembers(numpy.random) if not name.startswith('_')] _known_attributes = ['BitGenerator', 'Generator', 'MT19937', 'PCG64', 'PCG64DXSM', 'Philox', 'RandomState', 'SFC64', 'SeedSequence', 'beta', 'binomial', 'bit_generator', 'bytes', 'chisquare', 'choice', 'default_rng', 'dirichlet', 'exponential', 'f', 'gamma', 'geometric', 'get_bit_generator', 'get_state', 'gumbel', 'hypergeometric', 'laplace', 'logistic', 'lognormal', 'logseries', 'mtrand', 'multinomial', 'multivariate_normal', 'negative_binomial', 'noncentral_chisquare', 'noncentral_f', 'normal', 'pareto', 'permutation', 'poisson', 'power', 'rand', 'randint', 'randn', 'random', 'random_integers', 'random_sample', 'ranf', 'rayleigh', 'sample', 'seed', 'set_bit_generator', 'set_state', 'shuffle', 'standard_cauchy', 'standard_exponential', 'standard_gamma', 'standard_normal', 'standard_t', 'test', 'triangular', 'uniform', 'vonmises', 'wald', 'weibull', 'zipf'] diff --git a/firedrake/slate/slac/compiler.py b/firedrake/slate/slac/compiler.py index c68e0692d9..567701ef4b 100644 --- a/firedrake/slate/slac/compiler.py +++ b/firedrake/slate/slac/compiler.py @@ -40,7 +40,7 @@ from petsc4py import PETSc -#__all__ = ['compile_expression'] +__all__ = ['compile_expression'] GREEN = "\033[1;37;32m%s\033[0m" diff --git a/firedrake/slate/slate.py b/firedrake/slate/slate.py index 8bd667a81a..03ba45aa7b 100644 --- a/firedrake/slate/slate.py +++ b/firedrake/slate/slate.py @@ -41,10 +41,10 @@ from tsfc.ufl_utils import extract_firedrake_constants -# __all__ = ['AssembledVector', 'Block', 'Factorization', 'Tensor', -# 'Inverse', 'Transpose', 'Negative', -# 'Add', 'Mul', 'Solve', 'BlockAssembledVector', 'DiagonalTensor', -# 'Reciprocal'] +__all__ = ['AssembledVector', 'Block', 'Factorization', 'Tensor', + 'Inverse', 'Transpose', 'Negative', + 'Add', 'Mul', 'Solve', 'BlockAssembledVector', 'DiagonalTensor', + 'Reciprocal'] # BlockFunction description type BlockFunction = namedtuple('BlockFunction', ['split_function', 'indices', 'orig_function']) diff --git a/firedrake/slate/static_condensation/hybridization.py b/firedrake/slate/static_condensation/hybridization.py index d82ae536e8..2bfc075b19 100644 --- a/firedrake/slate/static_condensation/hybridization.py +++ b/firedrake/slate/static_condensation/hybridization.py @@ -12,7 +12,7 @@ from firedrake.slate.static_condensation.la_utils import SchurComplementBuilder from firedrake.ufl_expr import adjoint -#__all__ = ['SchurComplementBuilder'] +__all__ = ['SchurComplementBuilder'] class HybridizationPC(SCBase): diff --git a/firedrake/slope_limiter/limiter.py b/firedrake/slope_limiter/limiter.py index b3a9d44257..f4904136a8 100644 --- a/firedrake/slope_limiter/limiter.py +++ b/firedrake/slope_limiter/limiter.py @@ -1,6 +1,6 @@ from abc import ABCMeta, abstractmethod -#__all__ = ("Limiter",) +__all__ = ("Limiter",) class Limiter(object, metaclass=ABCMeta): diff --git a/firedrake/slope_limiter/vertex_based_limiter.py b/firedrake/slope_limiter/vertex_based_limiter.py index d48152b3ba..e06682ee26 100644 --- a/firedrake/slope_limiter/vertex_based_limiter.py +++ b/firedrake/slope_limiter/vertex_based_limiter.py @@ -7,7 +7,7 @@ from firedrake.slope_limiter.limiter import Limiter from firedrake import utils from ufl import inner -#__all__ = ("VertexBasedLimiter",) +__all__ = ("VertexBasedLimiter",) class VertexBasedLimiter(Limiter): diff --git a/firedrake/supermeshing.py b/firedrake/supermeshing.py index c6c4c305b1..6d2638e3a3 100644 --- a/firedrake/supermeshing.py +++ b/firedrake/supermeshing.py @@ -25,7 +25,7 @@ from loopy import generate_code_v2 -#__all__ = ["assemble_mixed_mass_matrix", "intersection_finder"] +__all__ = ["assemble_mixed_mass_matrix", "intersection_finder"] # TODO replace with KAIJ (we require petsc4py wrappers) diff --git a/firedrake/ufl_expr.py b/firedrake/ufl_expr.py index 5ec6e785ce..93406c6fb4 100644 --- a/firedrake/ufl_expr.py +++ b/firedrake/ufl_expr.py @@ -12,10 +12,10 @@ from functools import cached_property -# __all__ = ['Argument', 'Coargument', 'TestFunction', 'TrialFunction', -# 'TestFunctions', 'TrialFunctions', -# 'derivative', 'adjoint', -# 'action', 'CellSize', 'FacetNormal'] +__all__ = ['Argument', 'Coargument', 'TestFunction', 'TrialFunction', + 'TestFunctions', 'TrialFunctions', + 'derivative', 'adjoint', + 'action', 'CellSize', 'FacetNormal'] class Argument(ufl.argument.Argument): diff --git a/firedrake/utility_meshes.py b/firedrake/utility_meshes.py index 6627228e12..f2795bcf2b 100644 --- a/firedrake/utility_meshes.py +++ b/firedrake/utility_meshes.py @@ -34,36 +34,36 @@ from pyadjoint.tape import no_annotations -# __all__ = [ -# "UnitIntervalMesh", -# "PeriodicUnitIntervalMesh", -# "UnitTriangleMesh", -# "TensorRectangleMesh", -# "SquareMesh", -# "UnitSquareMesh", -# "PeriodicRectangleMesh", -# "PeriodicSquareMesh", -# "PeriodicUnitSquareMesh", -# "CircleManifoldMesh", -# "UnitDiskMesh", -# "UnitBallMesh", -# "UnitTetrahedronMesh", -# "TensorBoxMesh", -# "CubeMesh", -# "UnitCubeMesh", -# "PeriodicBoxMesh", -# "PeriodicUnitCubeMesh", -# "IcosahedralSphereMesh", -# "UnitIcosahedralSphereMesh", -# "OctahedralSphereMesh", -# "UnitOctahedralSphereMesh", -# "CubedSphereMesh", -# "UnitCubedSphereMesh", -# "TorusMesh", -# "AnnulusMesh", -# "SolidTorusMesh", -# "CylinderMesh", -# ] +__all__ = [ + "UnitIntervalMesh", + "PeriodicUnitIntervalMesh", + "UnitTriangleMesh", + "TensorRectangleMesh", + "SquareMesh", + "UnitSquareMesh", + "PeriodicRectangleMesh", + "PeriodicSquareMesh", + "PeriodicUnitSquareMesh", + "CircleManifoldMesh", + "UnitDiskMesh", + "UnitBallMesh", + "UnitTetrahedronMesh", + "TensorBoxMesh", + "CubeMesh", + "UnitCubeMesh", + "PeriodicBoxMesh", + "PeriodicUnitCubeMesh", + "IcosahedralSphereMesh", + "UnitIcosahedralSphereMesh", + "OctahedralSphereMesh", + "UnitOctahedralSphereMesh", + "CubedSphereMesh", + "UnitCubedSphereMesh", + "TorusMesh", + "AnnulusMesh", + "SolidTorusMesh", + "CylinderMesh", +] distribution_parameters_no_overlap = {"partition": True, diff --git a/firedrake/variational_solver.py b/firedrake/variational_solver.py index 62af9e5a1e..906742ce73 100644 --- a/firedrake/variational_solver.py +++ b/firedrake/variational_solver.py @@ -18,7 +18,7 @@ from functools import cached_property from collections.abc import Callable -#__all__ = ["LinearVariationalProblem"] +__all__ = ["LinearVariationalProblem"] def check_pde_args(F, J, Jp, E=None): From 73849c3640c334839506d7db21bcd5794c5791f1 Mon Sep 17 00:00:00 2001 From: nwng04 Date: Mon, 7 Sep 2026 12:08:48 +0100 Subject: [PATCH 28/28] Edit randomfunctiongen in __init__.py and specify refs. --- docs/source/ensemble_parallelism.rst | 54 +++++++++---------- docs/source/matrix-free.rst | 12 ++--- docs/source/modules.rst | 9 ++++ docs/source/parallelism.rst | 6 +-- firedrake/__init__.py | 7 ++- .../test_point_eval_immersed_manifold.py | 1 - 6 files changed, 48 insertions(+), 41 deletions(-) create mode 100644 docs/source/modules.rst diff --git a/docs/source/ensemble_parallelism.rst b/docs/source/ensemble_parallelism.rst index 00042c422f..7b6de9e288 100644 --- a/docs/source/ensemble_parallelism.rst +++ b/docs/source/ensemble_parallelism.rst @@ -35,10 +35,10 @@ Cartesian product over the original global communicator. The additional functionality required to support ensemble parallelism is the ability to send instances of :class:`function ` from one -ensemble to another. This is handled by the :class:`~.Ensemble` class. +ensemble to another. This is handled by the :class:`Ensemble ` class. Each ensemble member must have the same spatial parallel domain decomposition, so -instantiating an :class:`~.Ensemble` requires a communicator to split +instantiating an :class:`Ensemble ` requires a communicator to split (usually, but not necessarily, ``MPI_COMM_WORLD``) plus the number of MPI processes to be used in each member of the ensemble (5 in the figure above, and 2 in the example code below). The number of ensemble @@ -56,9 +56,9 @@ raised if this is not the case. :end-before: [test_ensemble_manual_example 1 <] Then, the spatial sub-communicator ``Ensemble.comm`` must be passed -to :func:`~.mesh.Mesh` (possibly via inbuilt mesh generators in +to :func:`~.Mesh` (possibly via inbuilt mesh generators in :mod:`~.utility_meshes`), so that it will then be used by any -:func:`function space ` and :class:`function ` derived from the mesh. +:func:`FunctionSpace ` and :class:`function ` derived from the mesh. .. literalinclude:: ../../tests/firedrake/ensemble/test_ensemble_manual.py :language: python3 @@ -78,7 +78,7 @@ The ensemble sub-communicator is then available through the attribute MPI communications across the spatial sub-communicator (i.e., within an ensemble member) are handled automatically by Firedrake, whilst MPI communications across the ensemble sub-communicator (i.e., between ensemble -members) are handled through methods of :class:`~.Ensemble`. Currently +members) are handled through methods of :class:`Ensemble `. Currently send/recv, reductions and broadcasts are supported, as well as their non-blocking variants. The rank of the the ensemble member (``my_ensemble.ensemble_comm.rank``) @@ -115,26 +115,26 @@ timeseries, and each timestep may live on a separate ensemble member. In this case we want to treat the entire timeseries as a single object. -Firedrake implements this using :class:`~.EnsembleFunctionSpace` -and :class:`~.EnsembleFunction` (along with the dual objects -:class:`~.EnsembleDualSpace` and :class:`~.EnsembleCofunction`). -The :class:`~.EnsembleFunctionSpace` can be thought of as a mixed +Firedrake implements this using :class:`EnsembleFunctionSpace ` +and :class:`EnsembleFunction ` (along with the dual objects +:class:`EnsembleDualSpace ` and :class:`EnsembleCofunction `). +The :class:`EnsembleFunctionSpace ` can be thought of as a mixed function space which is parallelised across the `components`, as opposed to just being parallelised in `space`, as would usually be the -case with :func:`function space `. Each component of an -:class:`~.EnsembleFunctionSpace` is a Firedrake :func:`function space ` +case with :func:`FunctionSpace `. Each component of an +:class:`EnsembleFunctionSpace ` is a Firedrake :func:`FunctionSpace ` on a single spatial communicator. -To create an :class:`~.EnsembleFunctionSpace` you must provide an -:class:`~.Ensemble` and, on each spatial communicator, a list of -:func:`function space ` instances for the components on the local +To create an :class:`EnsembleFunctionSpace ` you must provide an +:class:`Ensemble ` and, on each spatial communicator, a list of +:func:`FunctionSpace ` instances for the components on the local ``Ensemble.comm``. There can be a different number of local -:func:`function space ` on each ``Ensemble.comm``. In the example -below we create an :class:`~.EnsembleFunctionSpace` with two +:func:`FunctionSpace ` on each ``Ensemble.comm``. In the example +below we create an :class:`EnsembleFunctionSpace ` with two components on the first ensemble member, and three components on every other ensemble member. Note that, unlike a -:func:`function space `, a component of an -:class:`~.EnsembleFunctionSpace` may itself be a +:func:`FunctionSpace `, a component of an +:class:`EnsembleFunctionSpace ` may itself be a :func:`MixedFunctionSpace `. .. literalinclude:: ../../tests/firedrake/ensemble/test_ensemble_manual.py @@ -144,15 +144,15 @@ every other ensemble member. Note that, unlike a :end-before: [test_ensemble_manual_example 5 <] Analogously to accessing the components of a :func:`MixedFunctionSpace ` -using ``subspaces``, the :func:`function space ` for each local component -of an :class:`~.EnsembleFunctionSpace` can be accessed via +using ``subspaces``, the :func:`FunctionSpace ` for each local component +of an :class:`EnsembleFunctionSpace ` can be accessed via ``EnsembleFunctionSpace.local_spaces``. Various other methods and -properties such as ``dual`` (to create an :class:`~.EnsembleDualSpace`) +properties such as ``dual`` (to create an :class:`EnsembleDualSpace `) and ``nglobal_spaces`` (total number of components across all ranks) are also available. -An :class:`~.EnsembleFunction` and :class:`~.EnsembleCofunction` can be -created from the :class:`~.EnsembleFunctionSpace`. These have a ``subfunctions`` +An :class:`EnsembleFunction ` and :class:`EnsembleCofunction ` can be +created from the :class:`EnsembleFunctionSpace `. These have a ``subfunctions`` property that can be used to access the components on the local ensemble member. Each element in ``EnsembleFunction.subfunctions`` is itself just a normal Firedrake :class:`function `. If a component of the @@ -166,7 +166,7 @@ that ``MixedFunctionSpace``. :start-after: [test_ensemble_manual_example 6 >] :end-before: [test_ensemble_manual_example 6 <] -:class:`~.EnsembleFunction` and :class:`~.EnsembleCofunction` have +:class:`EnsembleFunction ` and :class:`EnsembleCofunction ` have a range of methods equivalent to those of :class:`function ` and :class:`Cofunction `, such as ``assign``, ``zero``, ``riesz_representation``, arithmetic operators e.g. ``+``, ``+=``, @@ -177,9 +177,9 @@ Because the components in ``EnsembleFunction.subfunctions`` (:class:`Cofunction `) instances, they can be used directly with variational forms and solvers. In the example code below, We create a :class:`linear variational solver ` where the right -hand side is a component of an :class:`~.EnsembleCofunction`, +hand side is a component of an :class:`EnsembleCofunction `, and the solution is written into a component of an -:class:`~.EnsembleFunction`. Using the ``subfunctions`` +:class:`EnsembleFunction `. Using the ``subfunctions`` directly like this can simplify ensemble code and reduce unnecessary copies. Note that the ``options_prefix`` is set using both the local ensemble @@ -201,7 +201,7 @@ on each ensemble member. ``EnsembleCofunction`` themselves do not carry any symbolic information so cannot be used in UFL expressions. -Internally, the :class:`~.EnsembleFunction` creates a ``PETSc.Vec`` +Internally, the :class:`EnsembleFunction ` creates a ``PETSc.Vec`` on the ``Ensemble.global_comm`` which contains the data for all local components on all ensemble members. This ``Vec`` can be accessed with a context manager, similarly to the ``Function.dat.vec`` context diff --git a/docs/source/matrix-free.rst b/docs/source/matrix-free.rst index ba2e4cc5a6..b31ddee55b 100644 --- a/docs/source/matrix-free.rst +++ b/docs/source/matrix-free.rst @@ -9,7 +9,7 @@ In addition to supporting computation with the workhorse of sparse linear algebra, an assembled sparse matrix, Firedrake also supports computing "matrix-free". In this case, the matrix returned from -:func:`.assemble` implements matrix-vector multiplication by the +:func:`assemble ` implements matrix-vector multiplication by the assembly of a 1-form subject to boundary conditions rather than direct construction of a sparse matrix ("aij" format) followed by traditional CSR algorithms. This functionality is documented in more detail in @@ -17,10 +17,10 @@ CSR algorithms. This functionality is documented in more detail in There are two ways of accessing this functionality. One can either request a matrix-free operator by passing ``mat_type="matfree"`` to -:func:`.assemble`. In this case, the returned object is an -:class:`.ImplicitMatrix`. This object can be used in the normal way -with a :class:`.LinearSolver`. Alternately, when solving a -variational problem, an :class:`.ImplicitMatrix` is requested through +:func:`assemble `. In this case, the returned object is an +:class:`ImplicitMatrix `. This object can be used in the normal way +with a :class:`LinearSolver `. Alternately, when solving a +variational problem, an :class:`ImplicitMatrix ` is requested through the ``solver_parameters`` dict, by setting the option ``mat_type`` to ``matfree``. The type of the preconditioning matrix can be controlled separately by setting ``pmat_type``. @@ -58,7 +58,7 @@ As well as providing symbolic field splitting, the preconditioners. Since it contains a complete UFL description of the bilinear form, preconditioners can query or manipulate it as desired. As a particularly simple example, the class -:class:`AssembledPC ` simply passes the UFL into :func:`.assemble` +:class:`AssembledPC ` simply passes the UFL into :func:`assemble ` to produce an explicit matrix during set up. It also sets up a new PETSc PC context acting on this assembled matrix so that the user can configure it at run-time via the options database. This allows the diff --git a/docs/source/modules.rst b/docs/source/modules.rst new file mode 100644 index 0000000000..4faa9e4b1a --- /dev/null +++ b/docs/source/modules.rst @@ -0,0 +1,9 @@ +:orphan: + +firedrake +========= + +.. toctree:: + :maxdepth: 4 + + firedrake diff --git a/docs/source/parallelism.rst b/docs/source/parallelism.rst index 370ed381df..834654347a 100644 --- a/docs/source/parallelism.rst +++ b/docs/source/parallelism.rst @@ -62,7 +62,7 @@ want to perform a simulation in which different subsets of processes perform different computations (perhaps solving the same PDE for multiple different initial conditions), this can be achieved by using sub-communicators. The mechanism to do so is to provide a -communicator when building the :func:`~.mesh.Mesh` you will perform the +communicator when building the :func:`~.Mesh` you will perform the simulation on, using the optional ``comm`` keyword argument. All subsequent operations using that mesh are then only collective over the supplied communicator, rather than ``MPI_COMM_WORLD``. For @@ -87,10 +87,10 @@ different simulations on the two halves we would write. .. note:: If you need to create Firedrake meshes on different communicators, - then usually the best approach is to use the :class:`~.Ensemble`, + then usually the best approach is to use the :class:`Ensemble `, which manages splitting MPI communicators and communicating :class:`function ` objects between the split communicators. More - information on using the :class:`~.Ensemble` can be found + information on using the :class:`Ensemble ` can be found :doc:`here `. To access the communicator a mesh was created on, we can use the diff --git a/firedrake/__init__.py b/firedrake/__init__.py index a026e76657..5c2a72c073 100644 --- a/firedrake/__init__.py +++ b/firedrake/__init__.py @@ -271,11 +271,10 @@ def init_petsc(): "EnsembleBJacobiPC", "EnsembleBlockDiagonalMat", ] -# randomfunctiongen generates __all__ dynamically, so we cannot enumerate -# things here import firedrake.randomfunctiongen as _randomfunctiongen -from firedrake.randomfunctiongen import * -__all__ += list(_randomfunctiongen.__all__) +__all__ += _randomfunctiongen.__all__ +globals().update({name: getattr(_randomfunctiongen, name) + for name in _randomfunctiongen.__all__}) del _randomfunctiongen from firedrake.external_operators import ( diff --git a/tests/firedrake/vertexonly/test_point_eval_immersed_manifold.py b/tests/firedrake/vertexonly/test_point_eval_immersed_manifold.py index 9b25f7eb0e..51316c274a 100644 --- a/tests/firedrake/vertexonly/test_point_eval_immersed_manifold.py +++ b/tests/firedrake/vertexonly/test_point_eval_immersed_manifold.py @@ -1,5 +1,4 @@ from firedrake import * -from firedrake import function import numpy as np