Deprecate push!(dh, ...) in favor of add!(dh, ...)

This patch deprecates `push!(dh::DofHandler, ...)` in favor of `add!(dh,...)`. This is to make it consistent with how constraints are added to the constraint handler, and using `Base.push!` for this was a bit of a pun anyway.
Ferrite-FEM · Jan 9, 2023 · 638b9d8 · 638b9d8
1 parent 9c34e96
commit 638b9d8
Show file tree

Hide file tree

Showing 32 changed files with 150 additions and 144 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -14,7 +14,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
    [#549][github-549])
  - New function `apply_analytical!` for setting the values of the degrees of freedom for a 
    specific field according to a spatial function `f(x)`. ([#532][github-532])
-
+### Deprecated
+ - Adding fields to a DoF handler with `push!(dh, ...)` has been deprecated in favor of
+   `add!(dh, ...)`. This is to make it consistent with how constraints are added to a
+   constraint handler. ([#578][github-578])
 
 ## [0.3.10] - 2022-12-11
 ### Added
@@ -229,6 +232,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 [github-547]: https://github.com/Ferrite-FEM/Ferrite.jl/pull/547
 [github-549]: https://github.com/Ferrite-FEM/Ferrite.jl/pull/549
 [github-550]: https://github.com/Ferrite-FEM/Ferrite.jl/pull/550
+[github-578]: https://github.com/Ferrite-FEM/Ferrite.jl/pull/578
 
 [Unreleased]: https://github.com/Ferrite-FEM/Ferrite.jl/compare/v0.3.10...HEAD
 [0.3.10]: https://github.com/Ferrite-FEM/Ferrite.jl/compare/v0.3.9...v0.3.10

diff --git a/docs/src/literate/computational_homogenization.jl b/docs/src/literate/computational_homogenization.jl
@@ -218,7 +218,7 @@ cellvalues = CellVectorValues(qr, ip);
 
 # We define a dof handler with a displacement field `:u`:
 dh = DofHandler(grid)
-push!(dh, :u, 2)
+add!(dh, :u, 2)
 close!(dh);
 
 # Now we need to define boundary conditions. As discussed earlier we will solve the problem

diff --git a/docs/src/literate/heat_equation.jl b/docs/src/literate/heat_equation.jl
@@ -68,7 +68,7 @@ cellvalues = CellScalarValues(qr, ip);
 # Lastly we `close!` the `DofHandler`, it is now that the dofs are distributed
 # for all the elements.
 dh = DofHandler(grid)
-push!(dh, :u, 1)
+add!(dh, :u, 1)
 close!(dh);
 
 # Now that we have distributed all our dofs we can create our tangent matrix,

diff --git a/docs/src/literate/helmholtz.jl b/docs/src/literate/helmholtz.jl
@@ -61,7 +61,7 @@ cellvalues = CellScalarValues(qr, ip);
 facevalues = FaceScalarValues(qr_face, ip);
 
 dh = DofHandler(grid)
-push!(dh, :u, 1)
+add!(dh, :u, 1)
 close!(dh)
 
 # We will set things up, so that a known analytic solution is approximately reproduced.

diff --git a/docs/src/literate/hyperelasticity.jl b/docs/src/literate/hyperelasticity.jl
@@ -323,7 +323,7 @@ function solve()
 
     ## DofHandler
     dh = DofHandler(grid)
-    push!(dh, :u, 3) # Add a displacement field
+    add!(dh, :u, 3) # Add a displacement field
     close!(dh)
 
     function rotation(X, t, θ = deg2rad(60.0))

diff --git a/docs/src/literate/incompressible_elasticity.jl b/docs/src/literate/incompressible_elasticity.jl
@@ -62,8 +62,8 @@ end;
 # with possibly different interpolations
 function create_dofhandler(grid, ipu, ipp)
     dh = DofHandler(grid)
-    push!(dh, :u, 2, ipu) # displacement
-    push!(dh, :p, 1, ipp) # pressure
+    add!(dh, :u, 2, ipu) # displacement
+    add!(dh, :p, 1, ipp) # pressure
     close!(dh)
     return dh
 end;

diff --git a/docs/src/literate/landau.jl b/docs/src/literate/landau.jl
@@ -90,7 +90,7 @@ function LandauModel(α, G, gridsize, left::Vec{DIM, T}, right::Vec{DIM, T}, elp
     cvP = CellVectorValues(qr, Lagrange{DIM, RefTetrahedron, 1}())
 
     dofhandler = DofHandler(grid)
-    push!(dofhandler, :P, 3)
+    add!(dofhandler, :P, 3)
     close!(dofhandler)
 
     dofvector = zeros(ndofs(dofhandler))

diff --git a/docs/src/literate/linear_shell.jl b/docs/src/literate/linear_shell.jl
@@ -34,8 +34,8 @@ cv = CellScalarValues(qr_inplane, ip)
 # Next we distribute displacement dofs,`:u = (x,y,z)` and rotational dofs, `:θ = (θ₁,  θ₂)`.
 #+
 dh = DofHandler(grid)
-push!(dh, :u, 3, ip)
-push!(dh, :θ, 2, ip)
+add!(dh, :u, 3, ip)
+add!(dh, :θ, 2, ip)
 close!(dh)
 
 # In order to apply our boundary conditions, we first need to create some edge- and vertex-sets. This 

diff --git a/docs/src/literate/ns_vs_diffeq.jl b/docs/src/literate/ns_vs_diffeq.jl
@@ -167,8 +167,8 @@ ip_p = Lagrange{dim, RefCube, 1}()
 cellvalues_p = CellScalarValues(qr, ip_p, ip_geom);
 
 dh = DofHandler(grid)
-push!(dh, :v, dim, ip_v)
-push!(dh, :p, 1, ip_p)
+add!(dh, :v, dim, ip_v)
+add!(dh, :p, 1, ip_p)
 close!(dh);
 
 # ### Boundary Conditions

diff --git a/docs/src/literate/plasticity.jl b/docs/src/literate/plasticity.jl
@@ -155,7 +155,7 @@ end;
 function create_dofhandler(grid, interpolation)
     dh = DofHandler(grid)
     dim = 3
-    push!(dh, :u, dim, interpolation) # add a displacement field with 3 components
+    add!(dh, :u, dim, interpolation) # add a displacement field with 3 components
     close!(dh)
     return dh
 end

diff --git a/docs/src/literate/quasi_incompressible_hyperelasticity.jl b/docs/src/literate/quasi_incompressible_hyperelasticity.jl
@@ -137,8 +137,8 @@ end;
 
 function create_dofhandler(grid, ipu, ipp)
     dh = DofHandler(grid)
-    push!(dh, :u, 3, ipu) # displacement dim = 3
-    push!(dh, :p, 1, ipp) # pressure dim = 1
+    add!(dh, :u, 3, ipu) # displacement dim = 3
+    add!(dh, :p, 1, ipp) # pressure dim = 1
     close!(dh)
     return dh
 end;

diff --git a/docs/src/literate/stokes-flow.jl b/docs/src/literate/stokes-flow.jl
@@ -241,8 +241,8 @@ end
 
 function setup_dofs(grid, ipu, ipp)
     dh = DofHandler(grid)
-    push!(dh, :u, 2, ipu)
-    push!(dh, :p, 1, ipp)
+    add!(dh, :u, 2, ipu)
+    add!(dh, :p, 1, ipp)
     close!(dh)
     return dh
 end

diff --git a/docs/src/literate/threaded_assembly.jl b/docs/src/literate/threaded_assembly.jl
@@ -53,7 +53,7 @@ end;
 # #### DofHandler
 function create_dofhandler(grid::Grid{dim}) where {dim}
     dh = DofHandler(grid)
-    push!(dh, :u, dim) # Add a displacement field
+    add!(dh, :u, dim) # Add a displacement field
     close!(dh)
 end;
 

diff --git a/docs/src/literate/topology_optimization.jl b/docs/src/literate/topology_optimization.jl
@@ -103,7 +103,7 @@ end
 
 function create_dofhandler(grid)
     dh = DofHandler(grid)
-    push!(dh, :u, 2, Lagrange{2,RefCube,1}()) ## displacement
+    add!(dh, :u, 2, Lagrange{2,RefCube,1}()) ## displacement
     close!(dh)
     return dh
 end

diff --git a/docs/src/literate/transient_heat_equation.jl b/docs/src/literate/transient_heat_equation.jl
@@ -72,7 +72,7 @@ cellvalues = CellScalarValues(qr, ip);
 # ### Degrees of freedom
 # After this, we can define the `DofHandler` and distribute the DOFs of the problem.
 dh = DofHandler(grid)
-push!(dh, :u, 1)
+add!(dh, :u, 1)
 close!(dh);
 
 # By means of the `DofHandler` we can allocate the needed `SparseMatrixCSC`.

diff --git a/docs/src/manual/boundary_conditions.md b/docs/src/manual/boundary_conditions.md
@@ -267,7 +267,7 @@ For example, specify the initial pressure as a function of the y-coordinate
 ```julia
 ρ = 1000; g = 9.81    # density [kg/m³] and gravity [N/kg]
 grid = generate_grid(Quadrilateral, (10,10))
-dh = DofHandler(grid); push!(dh, :u, 2); push!(dh, :p, 1); close!(dh)
+dh = DofHandler(grid); add!(dh, :u, 2); add!(dh, :p, 1); close!(dh)
 u = zeros(ndofs(dh))
 apply_analytical!(u, dh, :p, x -> ρ * g * x[2])
 ```

diff --git a/docs/src/manual/degrees_of_freedom.md b/docs/src/manual/degrees_of_freedom.md
@@ -25,8 +25,8 @@ need to specify number of components for the field. Here we add a vector field `
 (2 components for a 2D problem) and a scalar field `:p`.
 
 ```@example dofs
-push!(dh, :u, 2)
-push!(dh, :p, 1)
+add!(dh, :u, 2)
+add!(dh, :p, 1)
 # hide
 ```
 
@@ -53,8 +53,8 @@ quadratic interpolation, and our `:p` field with a linear approximation.
 
 ```@example dofs
 dh = DofHandler(grid) # hide
-push!(dh, :u, 2, Lagrange{2,RefTetrahedron,2}())
-push!(dh, :p, 1, Lagrange{2,RefTetrahedron,1}())
+add!(dh, :u, 2, Lagrange{2,RefTetrahedron,2}())
+add!(dh, :p, 1, Lagrange{2,RefTetrahedron,1}())
 # hide
 ```
 

diff --git a/docs/src/manual/export.md b/docs/src/manual/export.md
@@ -1,7 +1,7 @@
 ```@setup export
 using Ferrite
 grid = generate_grid(Triangle, (2, 2))
-dh = DofHandler(grid); push!(dh, :u, 1); close!(dh)
+dh = DofHandler(grid); add!(dh, :u, 1); close!(dh)
 u = rand(ndofs(dh)); σ = rand(getncells(grid))
 ```
 

diff --git a/docs/src/reference/dofhandler.md b/docs/src/reference/dofhandler.md
@@ -11,8 +11,8 @@ MixedDofHandler
 
 ## Adding fields to the DofHandlers
 ```@docs
-push!(::DofHandler, ::Symbol, ::Int, ::Interpolation)
-push!(::MixedDofHandler, ::FieldHandler)
+add!(::DofHandler, ::Symbol, ::Int, ::Interpolation)
+add!(::MixedDofHandler, ::FieldHandler)
 Field
 FieldHandler
 close!(::MixedDofHandler)

diff --git a/src/Dofs/DofHandler.jl b/src/Dofs/DofHandler.jl
@@ -87,7 +87,7 @@ Return the local dof range for `field_name`. Example:
 julia> grid = generate_grid(Triangle, (3, 3))
 Grid{2, Triangle, Float64} with 18 Triangle cells and 16 nodes
 
-julia> dh = DofHandler(grid); push!(dh, :u, 3); push!(dh, :p, 1); close!(dh);
+julia> dh = DofHandler(grid); add!(dh, :u, 3); add!(dh, :p, 1); close!(dh);
 
 julia> dof_range(dh, :u)
 1:9
@@ -104,15 +104,15 @@ function dof_range(dh::DofHandler, field_name::Symbol)
 end
 
 """
-    push!(dh::AbstractDofHandler, name::Symbol, dim::Int[, ip::Interpolation])
+    add!(dh::AbstractDofHandler, name::Symbol, dim::Int[, ip::Interpolation])
 
 Add a `dim`-dimensional `Field` called `name` which is approximated by `ip` to `dh`.
 
 The field is added to all cells of the underlying grid. In case no interpolation `ip` is given,
 the default interpolation of the grid's celltype is used. 
-If the grid uses several celltypes, [`push!(dh::MixedDofHandler, fh::FieldHandler)`](@ref) must be used instead.
+If the grid uses several celltypes, [`add!(dh::MixedDofHandler, fh::FieldHandler)`](@ref) must be used instead.
 """
-function Base.push!(dh::DofHandler, name::Symbol, dim::Int, ip::Interpolation=default_interpolation(getcelltype(dh.grid)))
+function add!(dh::DofHandler, name::Symbol, dim::Int, ip::Interpolation=default_interpolation(getcelltype(dh.grid)))
     @assert !isclosed(dh)
     @assert !in(name, dh.field_names)
     push!(dh.field_names, name)

diff --git a/src/Dofs/MixedDofHandler.jl b/src/Dofs/MixedDofHandler.jl
@@ -133,11 +133,11 @@ Returns the number of unique fields defined.
 nfields(dh::MixedDofHandler) = length(getfieldnames(dh))
 
 """
-    push!(dh::MixedDofHandler, fh::FieldHandler)
+    add!(dh::MixedDofHandler, fh::FieldHandler)
 
 Add all fields of the [`FieldHandler`](@ref) `fh` to `dh`.
 """
-function Base.push!(dh::MixedDofHandler, fh::FieldHandler)
+function add!(dh::MixedDofHandler, fh::FieldHandler)
     @assert !isclosed(dh)
     _check_same_celltype(dh.grid, collect(fh.cellset))
     _check_cellset_intersections(dh, fh)
@@ -160,13 +160,13 @@ function _check_cellset_intersections(dh::MixedDofHandler, fh::FieldHandler)
     end
 end
 
-function Base.push!(dh::MixedDofHandler, name::Symbol, dim::Int)
+function add!(dh::MixedDofHandler, name::Symbol, dim::Int)
     celltype = getcelltype(dh.grid)
-    isconcretetype(celltype) || error("If you have more than one celltype in Grid, you must use push!(dh::MixedDofHandler, fh::FieldHandler)")
-    push!(dh, name, dim, default_interpolation(celltype))
+    isconcretetype(celltype) || error("If you have more than one celltype in Grid, you must use add!(dh::MixedDofHandler, fh::FieldHandler)")
+    add!(dh, name, dim, default_interpolation(celltype))
 end
 
-function Base.push!(dh::MixedDofHandler, name::Symbol, dim::Int, ip::Interpolation)
+function add!(dh::MixedDofHandler, name::Symbol, dim::Int, ip::Interpolation)
     @assert !isclosed(dh)
 
     celltype = getcelltype(dh.grid)

diff --git a/src/L2_projection.jl b/src/L2_projection.jl
@@ -24,7 +24,7 @@ function L2Projector(fe_values::Ferrite.Values, interp::Interpolation,
     dh = MixedDofHandler(grid)
     field = Field(:_, interp, 1)
     fh = FieldHandler([field], Set(set))
-    push!(dh, fh)
+    add!(dh, fh)
     _, vertex_dict, _, _ = __close!(dh)
 
     M = _assemble_L2_matrix(fe_values_mass, set, dh)  # the "mass" matrix
@@ -81,7 +81,7 @@ function L2Projector(
     dh = MixedDofHandler(grid)
     field = Field(:_, func_ip, 1) # we need to create the field, but the interpolation is not used here
     fh = FieldHandler([field], Set(set))
-    push!(dh, fh)
+    add!(dh, fh)
     _, vertex_dict, _, _ = __close!(dh)
 
     M = _assemble_L2_matrix(fe_values_mass, set, dh)  # the "mass" matrix

diff --git a/src/deprecations.jl b/src/deprecations.jl
@@ -1,2 +1,4 @@
 Base.@deprecate_binding DirichletBoundaryConditions ConstraintHandler
 Base.@deprecate_binding DirichletBoundaryCondition Dirichlet
+import Base: push!
+@deprecate push!(dh::AbstractDofHandler, args...) add!(dh, args...)
diff --git a/test/test_abstractgrid.jl b/test/test_abstractgrid.jl
@@ -63,7 +63,7 @@
     end
 
     for (dh,u) in zip(dhs,(u1,u2))
-        push!(dh, :u, 1)
+        add!(dh, :u, 1)
         close!(dh)
         ch = ConstraintHandler(dh)
         add!(ch, dbc)

diff --git a/test/test_apply_analytical.jl b/test/test_apply_analytical.jl
@@ -27,8 +27,8 @@
         dh = DofHandler(grid)
         default_ip = Ferrite.default_interpolation(CT)
         try
-            push!(dh, :u, dim, change_ip_order(default_ip, ip_order_u))
-            push!(dh, :p, 1, change_ip_order(default_ip, ip_order_p))                
+            add!(dh, :u, dim, change_ip_order(default_ip, ip_order_u))
+            add!(dh, :p, 1, change_ip_order(default_ip, ip_order_p))
         catch e
             isa(e, MethodError) && e.f == Ferrite.reference_coordinates && return nothing
             rethrow(e)
@@ -58,8 +58,8 @@
         ufield_A = Field(:u, change_ip_order(default_ip_A, ip_order_u), dim)
         pfield_A = Field(:p, change_ip_order(default_ip_A, ip_order_p), 1)
         ufield_B = Field(:u, change_ip_order(default_ip_B, ip_order_u), dim)
-        push!(mdh, FieldHandler([ufield_A, pfield_A], getcellset(grid,"A")))
-        push!(mdh, FieldHandler([ufield_B,], getcellset(grid, "B")))
+        add!(mdh, FieldHandler([ufield_A, pfield_A], getcellset(grid,"A")))
+        add!(mdh, FieldHandler([ufield_B,], getcellset(grid, "B")))
         close!(mdh)
         return mdh
     end

diff --git a/test/test_apply_rhs.jl b/test/test_apply_rhs.jl
@@ -6,7 +6,7 @@ function test_apply_rhs()
     cellvalues = CellScalarValues(qr, ip)
 
     dh = DofHandler(grid)
-    push!(dh, :u, 1)
+    add!(dh, :u, 1)
     close!(dh)
 
     K = create_sparsity_pattern(dh)

diff --git a/test/test_cellvalues.jl b/test/test_cellvalues.jl
@@ -97,7 +97,7 @@ end
     grid = generate_grid(Line, (2,))
     ip_fe = Lagrange{dim, RefCube, deg}()
     dh = DofHandler(grid)
-    push!(dh, :u, 1, ip_fe)
+    add!(dh, :u, 1, ip_fe)
     close!(dh);
     cell = first(CellIterator(dh))
     ip_geo = Lagrange{dim, RefCube, 2}()