|
| 1 | +# Boundary Conditions in fenicsx-pulse |
| 2 | + |
| 3 | +Defining appropriate boundary conditions is essential for setting up a well-posed |
| 4 | +mechanics problem. In `fenicsx-pulse`, boundary conditions are collected in a |
| 5 | +`pulse.BoundaryConditions` object and passed to the problem solver. |
| 6 | + |
| 7 | +The library supports several types of boundary conditions, ranging from standard |
| 8 | +Dirichlet and Neumann conditions to more complex Robin conditions and global |
| 9 | +cavity volume constraints. |
| 10 | + |
| 11 | +```python |
| 12 | +import dolfinx |
| 13 | +import pulse |
| 14 | +import ufl |
| 15 | +from mpi4py import MPI |
| 16 | +``` |
| 17 | + |
| 18 | +```python |
| 19 | +# (Mock setup for demonstration purposes) |
| 20 | +mesh = dolfinx.mesh.create_unit_cube(MPI.COMM_WORLD, 3, 3, 3) |
| 21 | +geo = pulse.Geometry(mesh=mesh) |
| 22 | +# Assume we have markers defined in geo.markers, e.g., "ENDO", "EPI", "BASE" |
| 23 | +``` |
| 24 | + |
| 25 | + |
| 26 | +## 1. Dirichlet Boundary Conditions |
| 27 | + |
| 28 | +Dirichlet boundary conditions constrain the value of the primary unknown |
| 29 | +(displacement) on a specific part of the domain. |
| 30 | + |
| 31 | +In `fenicsx-pulse`, Dirichlet BCs are defined as **functions** (callables). |
| 32 | +This is necessary because the underlying function space is created inside the |
| 33 | +`Problem` class, so the user cannot create the `dolfinx.fem.dirichletbc` object |
| 34 | +directly beforehand. Instead, you provide a function that takes the function |
| 35 | +space `V` as input and returns a list of Dirichlet BCs. |
| 36 | + |
| 37 | + |
| 38 | +```python |
| 39 | +def dirichlet_bc_example(V: dolfinx.fem.FunctionSpace) -> list[dolfinx.fem.DirichletBC]: |
| 40 | + """ |
| 41 | + Example function to fix the displacement on a specific boundary. |
| 42 | + """ |
| 43 | + # 1. Locate degrees of freedom on the boundary. |
| 44 | + # Assumes 'geo' is available in scope or passed in. |
| 45 | + # Here we assume marker ID 1 is the boundary to fix. |
| 46 | + marker_id = 1 |
| 47 | + facets = geo.facet_tags.find(marker_id) |
| 48 | + dofs = dolfinx.fem.locate_dofs_topological(V, geo.facet_dimension, facets) |
| 49 | + |
| 50 | + # 2. Define the fixed value (e.g., zero displacement). |
| 51 | + u_fixed = dolfinx.fem.Function(V) |
| 52 | + u_fixed.x.array[:] = 0.0 |
| 53 | + |
| 54 | + # 3. Create and return the BC object. |
| 55 | + return [dolfinx.fem.dirichletbc(u_fixed, dofs)] |
| 56 | +``` |
| 57 | + |
| 58 | +## 2. Neumann Boundary Conditions (Pressure) |
| 59 | + |
| 60 | +Neumann boundary conditions in this package primarily represent a |
| 61 | +**follower pressure load**. This means the force acts normal to the |
| 62 | +**deformed** surface area. |
| 63 | + |
| 64 | +The total force vector t on a surface element ds is given by: |
| 65 | + t = -p * J * inv(F).T * N |
| 66 | +where p is the scalar traction magnitude (pressure), and the term |
| 67 | +J * inv(F).T * N represents the area-weighted normal in the current configuration. |
| 68 | + |
| 69 | +```python |
| 70 | +# Define the pressure magnitude (can be a Constant or Function). |
| 71 | +# It is recommended to wrap it in `pulse.Variable` for unit handling. |
| 72 | +pressure = pulse.Variable(dolfinx.fem.Constant(mesh, 1.0), "kPa") |
| 73 | +``` |
| 74 | + |
| 75 | +```python |
| 76 | +# Define the BC on a specific surface marker (e.g., marker 2). |
| 77 | +neumann_bc = pulse.NeumannBC(traction=pressure, marker=2) |
| 78 | +``` |
| 79 | + |
| 80 | + |
| 81 | +## 3. Robin Boundary Conditions (Springs & Dashpots) |
| 82 | + |
| 83 | +Robin boundary conditions apply a force proportional to the displacement (spring) |
| 84 | +or velocity (dashpot/damping). These are often used to model the pericardium |
| 85 | +or surrounding tissue support in cardiac mechanics. |
| 86 | + |
| 87 | +The general form for a spring is: |
| 88 | + P * N + k * (u . n) * n = 0 |
| 89 | +where k is the stiffness and n is the normal vector. |
| 90 | + |
| 91 | +Configuration Options: |
| 92 | +- `damping`: If True, force is proportional to velocity (viscous damper). |
| 93 | +- `perpendicular`: If True, force acts in the tangential plane. |
| 94 | + If False (default), it acts in the normal direction. |
| 95 | + |
| 96 | +```python |
| 97 | +# Define stiffness |
| 98 | +stiffness = pulse.Variable(dolfinx.fem.Constant(mesh, 1e3), "Pa/m") |
| 99 | +``` |
| 100 | + |
| 101 | +```python |
| 102 | +# Create the Robin BC (e.g., on marker 3) |
| 103 | +robin_bc = pulse.RobinBC(value=stiffness, marker=3) |
| 104 | +``` |
| 105 | + |
| 106 | + |
| 107 | +## 4. Body Forces |
| 108 | + |
| 109 | +Volumetric forces, such as gravity, can be applied to the entire domain. |
| 110 | + |
| 111 | +```python |
| 112 | +gravity = dolfinx.fem.Constant(mesh, dolfinx.default_scalar_type((0, 0, -9.81))) |
| 113 | +``` |
| 114 | + |
| 115 | + |
| 116 | +## 5. The BoundaryConditions Container |
| 117 | + |
| 118 | +Finally, all defined conditions are collected into the container. |
| 119 | + |
| 120 | +```python |
| 121 | +bcs = pulse.BoundaryConditions( |
| 122 | + dirichlet=(dirichlet_bc_example,), |
| 123 | + neumann=(neumann_bc,), |
| 124 | + robin=(robin_bc,), |
| 125 | + body_force=(gravity,), |
| 126 | +) |
| 127 | +``` |
| 128 | + |
| 129 | + |
| 130 | +## 6. Cavity Volume Constraint |
| 131 | + |
| 132 | +Instead of specifying a known pressure (Neumann BC), you can enforce a specific |
| 133 | +**cavity volume**. The solver then treats the cavity pressure as a Lagrange |
| 134 | +multiplier (unknown) that adjusts to satisfy the volume constraint. |
| 135 | + |
| 136 | +This is technically a global constraint coupled with the boundary, but it is |
| 137 | +handled via the `cavities` argument in the problem solver. |
| 138 | + |
| 139 | +```python |
| 140 | +# Target volume |
| 141 | +target_vol = dolfinx.fem.Constant(mesh, 150.0) |
| 142 | +``` |
| 143 | + |
| 144 | +```python |
| 145 | +# Define the cavity constraint. 'marker' is the name of the boundary (e.g. "ENDO"). |
| 146 | +# Note: The geometry object must have this string marker mapped to an ID. |
| 147 | +cavity = pulse.problem.Cavity(marker="ENDO", volume=target_vol) |
| 148 | +``` |
| 149 | + |
| 150 | +Example usage in a problem (commented out): |
| 151 | +problem = pulse.StaticProblem(..., bcs=bcs, cavities=[cavity]) |
| 152 | + |
| 153 | +The solver will compute the pressure required to maintain `target_vol`. |
| 154 | +You can access this computed pressure via `problem.cavity_pressures`. |
| 155 | + |
| 156 | + |
| 157 | + |
| 158 | +## 7. Helper Parameters |
| 159 | + |
| 160 | +The `StaticProblem` and `DynamicProblem` classes accept a `parameters` dictionary |
| 161 | +that can activate predefined boundary behaviors. |
| 162 | + |
| 163 | + |
| 164 | +### The BaseBC Parameter |
| 165 | +For cardiac geometries, handling the basal plane is a common requirement. |
| 166 | + |
| 167 | +- `pulse.BaseBC.fixed`: Automatically applies a Dirichlet BC fixing all |
| 168 | + displacement components (u=0) on the boundary marked as "BASE". |
| 169 | +- `pulse.BaseBC.free`: Does not apply any automatic Dirichlet condition to the base. This is for example useful when you want to apply a pure Robin boundary condition. |
| 170 | + You are free to apply your own Dirichlet or Robin conditions manually. |
| 171 | + |
| 172 | + |
| 173 | +### Rigid Body Constraint |
| 174 | +If your problem does not have enough Dirichlet conditions to prevent rigid body |
| 175 | +motion (translation/rotation), the solver will fail to converge. |
| 176 | + |
| 177 | +- `rigid_body_constraint=True`: Adds Lagrange multipliers to constrain the |
| 178 | + 6 rigid body modes (3 translations, 3 rotations). This is useful for "floating" |
| 179 | + models where you want to study deformation without fixing a specific boundary. |
| 180 | + |
| 181 | +```python |
| 182 | +parameters = {"base_bc": pulse.BaseBC.fixed, "rigid_body_constraint": False} |
| 183 | +``` |
0 commit comments