API Reference

This section exposes the public Python API with Sphinx autodoc.

The directives below include documented and undocumented members so every class and function in each module appears in the generated docs.

Core Package

class pvade.IO.Parameters.SimParams(input_file_path=None)

Bases: object

Manages and validates all simulation parameters

SimParams provides a set of methods to obtain user-input values from both input files and the command line. It also provides input validation via a yaml schema file. All parameters can later be access from PVade objects like params.parent_group.option for example, params.solver.dt.

comm

An MPI communicator that will be shared by all PVade objects.

Type:

MPI Communicator

flat_schema_dict

A flattened dictionary version of the yaml schema file used to set default values and provide valid command-line options.

Type:

dict

input_dict

The aggregated input dictionary containing all command-line updated values and input-file values.

Type:

dict

input_file_dict

The dictionary representing the input file.

Type:

dict

num_procs

The total number of processors being used to solve the problem

Type:

int

rank

A unique ID for each process in the range [0, 1, …, num_procs-1]

Type:

int

schema_dict

The unflattened (nested) representation of the yaml schema dictionary.

Type:

dict

Create a SimParams object

This method begins by reading both the schema file and the user-specified file into dictionaries. It overrides entries in the user-specified dictionary with command-line inputs and finally validates the complete dictionary against the schema file.

Parameters:

input_file_path (str, optional) – The complete path to the input yaml file defining the problem.

Input/output utilities for PVade simulations.

This module provides:

  • start_print_and_log() – redirect stdout and stderr to a log

    file while still echoing output to the terminal.

  • DataStream – manages XDMF solution files, writing initial and

    per-timestep snapshots of velocity, pressure, displacement, stress, and optional temperature fields.

class pvade.IO.DataStream.DataStream(domain, flow, structure=None, params=None)

Bases: object

Input/Output and file writing class

This class manages the generation and updating of the saved xdmf files from each run along with command line outputs and log files.

comm

An MPI communicator used by all PVade objects

Type:

MPI Communicator

ndim

The number of dimensions in the problem

Type:

int

num_procs

The total number of processors being used to solve the problem

Type:

int

rank

A unique ID for each process in the range [0, 1, …, num_procs-1]

Type:

int

results_filename_fluid

The full path to the directory in which all saved files will be written.

Type:

str

Initialize the DataStream object

This initializes an object that manages the I/O for all of PVade.

Parameters:

  • domain (pvade.geometry.MeshManager.Domain) – A Domain object

  • flow (pvade.fluid.FlowManager.Flow) – A Flow object

  • params (pvade.Parameters.SimParams) – A SimParams object

save_XDMF_files(fsi_object, domain, tt)

Write additional timestep to XDMF file

This function appends the state of the flow at time tt to an existing XDMF file.

Parameters:
pvade.IO.DataStream.start_print_and_log(rank, logfile_name)

Redirect stdout and stderr to a timestamped log file.

Replaces the process sys.stdout and sys.stderr with PrintAndLog instances that tee output to both the terminal and the file logfile_name. The log file is initialised as an empty file before redirection begins.

Parameters:

  • rank (int) – MPI rank of the calling process.

  • logfile_name (str) – Full path to the log file that will be created (or overwritten if it already exists).

Command-line and profiling utility functions for PVade.

This module contains lightweight helpers for parsing the input-file path from the command line (get_input_file()) and for extracting solver timing metrics from a profiling output file (write_metrics()).

pvade.IO.Utilities.get_input_file()

Parse the path to the PVade input YAML file from the command line.

Reads the --input_file argument from sys.argv and verifies that a value was supplied. Raises a ValueError when no input file is specified.

Returns:

The full path to the input YAML file as provided on the command line.

Return type:

str

Raises:

ValueError – If --input_file is not provided or is None.

pvade.IO.Utilities.write_metrics(flow, prof_filename='profiling.txt')

Print solver timing metrics extracted from a profiling output file.

Reads the profiling file produced by cProfile or a similar tool and searches for lines matching known solver-step identifiers. Prints the total time, per-call time, and call count for the main solve step as well as individual IPCS sub-steps and mesh I/O operations.

Parameters:

  • flow (pvade.fluid.FlowManager.Flow) – The Flow object; metrics are only printed when flow.fluid_analysis is True.

  • prof_filename (str, optional) – Path to the profiling output file. Defaults to "profiling.txt".

Incompressible Navier–Stokes fluid solver (fractional-step / IPCS method).

This module provides the Flow class, which assembles and solves the incompressible Navier–Stokes equations on an ALE (Arbitrary Lagrangian–Eulerian) mesh using the three-step Incremental Pressure Correction Scheme (IPCS). An optional energy equation (advection–diffusion with SUPG stabilisation) handles buoyancy-driven or thermally-stratified flows.

class pvade.fluid.FlowManager.Flow(domain, params)

Bases: object

Incompressible Navier–Stokes fluid solver.

Implements the IPCS fractional-step method on an ALE mesh. On each time step the solver computes a tentative velocity, a pressure correction (to enforce incompressibility), a corrected velocity, and optionally a temperature field. The class also computes integrated aerodynamic forces on immersed panels, CFL numbers, and pressure drops.

comm

MPI communicator shared by all PVade objects.

rank

Rank of this MPI process.

Type:

int

num_procs

Total number of MPI processes.

Type:

int

fluid_analysis

Flag indicating whether a fluid analysis is being performed.

Type:

bool

thermal_analysis

Flag indicating whether the energy equation is solved.

Type:

bool

name

Human-readable identifier (always "fluid").

Type:

str

Q

Scalar Lagrange P1 pressure space.

Type:

dolfinx.fem.FunctionSpace

V

Vector Lagrange P2 velocity space.

Type:

dolfinx.fem.FunctionSpace

T

Tensor Lagrange P2 stress space on the deformed fluid mesh.

Type:

dolfinx.fem.FunctionSpace

T_undeformed

Tensor Lagrange P2 stress space on the reference (undeformed) fluid mesh.

Type:

dolfinx.fem.FunctionSpace

S

Scalar Lagrange P1 temperature space (only when thermal_analysis is True).

Type:

dolfinx.fem.FunctionSpace

DG

Discontinuous Galerkin P0 space used for CFL field storage.

Type:

dolfinx.fem.FunctionSpace

first_call_to_solver

Flag indicating the first solver call (triggers one-time assembly).

Type:

bool

ndim

Spatial dimension of the fluid problem.

Type:

int

facet_dim

Facet dimension (ndim - 1).

Type:

int

hmin

Global minimum cell diameter across all MPI ranks.

Type:

float

num_Q_dofs

Global number of pressure DOFs.

Type:

int

num_V_dofs

Global number of velocity DOFs.

Type:

int

Initialize the fluid solver

This method initialize the Flow object, namely, it creates all the necessary function spaces on the mesh, initializes key counting and boolean variables and records certain characteristic quantities like the minimum cell size and the number of degrees of freedom attributed to both the pressure and velocity function spaces.

Parameters:

domain (pvade.geometry.MeshManager.Domain) – A Domain object

adjust_dpdx_for_constant_flux()

Adjust the forcing term, dpdx, to maintain flowrate

Here we calculate what the value of the dolfinx.fem.constant driving pressure/force, dpdx, should be adjusted to to maintain a dolfinx.fem.constant flux through the domain. This is a useful option if performing a periodic simulation in which the flux will slowly decay due to viscous dissipation. The amount of change in dpdx is calculated by comparing the current flux to the flux measured in the initial condition and then employing a PID controller to adjust the driving force to seek the target defined by the initial condition.

Parameters:

None

build_boundary_conditions(domain, params)

Build the boundary conditions

A method to manage the building of boundary conditions, including the steps of identifying entities on the boundary, marking those degrees of freedom either by the identified facets or a gmsh marker function, and finally assembling a list of Boundary objects that enforce the correct value.

Parameters:

  • domain (pvade.geometry.MeshManager.Domain) – A Domain object

  • params (pvade.Parameters.SimParams) – A SimParams object

build_forms(domain, params)

Builds all variational statements

This method creates all the functions, expressions, and variational forms that will be needed for the numerical solution of Navier Stokes using a fractional step method. This includes the calculation of a tentative velocity, the calculation of the change in pressure required to correct the tentative velocity to enforce continuity, and the update to the velocity field to reflect this change in pressure.

Parameters:

  • domain (pvade.geometry.MeshManager.Domain) – A Domain object

  • params (pvade.Parameters.SimParams) – A SimParams object

compute_cfl()

Solve for the CFL number

Using the velocity, timestep size, and cell sizes, we calculate a CFL number at every mesh cell. From that, we select the single highest value of CFL number and record it for the purposes of monitoring simulation stability.

Parameters:

None

compute_lift_and_drag(params, current_time)
compute_pressure_drop_between_points(domain, params)
solve(domain, params, current_time)

Solve for a single timestep advancement

Here we perform the three-step solution process (tentative velocity, pressure correction, velocity update) to advance the fluid simulation a single timestep. Additionally, we calculate the new CFL number associated with the latest velocity solution.

Parameters:

params (pvade.Parameters.SimParams) – A SimParams object

Boundary condition utilities for the incompressible Navier–Stokes solver.

This module provides functions and classes for building Dirichlet boundary conditions on velocity, pressure, and temperature fields. It also contains InflowVelocity, a callable class that evaluates user-selected inflow profiles (uniform, parabolic, log-law, or from a pre-computed HDF5 file) at any spatial position and simulation time.

class pvade.fluid.boundary_conditions.InflowVelocity(ndim, params, current_time)

Bases: object

Callable inflow velocity profile for use as a Dirichlet boundary condition.

Supports the following profile types, selected via params.fluid.velocity_profile_type:

  • "uniform" – constant streamwise velocity equal to u_ref.

  • "parabolic" – parabolic Poiseuille-like profile.

  • "loglaw" – atmospheric surface-layer log-law profile.

  • "specified_from_file" – time-varying 3-D inflow field read from an HDF5 file and interpolated to the current mesh and time.

An optional cosine ramp (params.fluid.ramp_window) smoothly increases the inflow speed from zero to u_ref during the early simulation phase.

ndim

Number of spatial dimensions of the mesh.

Type:

int

params

Simulation parameters.

Type:

pvade.IO.Parameters.SimParams

current_time

Current simulation time used when interpolating time-varying inflow data.

Type:

float

u_ref

Effective reference velocity computed from the inflow file (only set when velocity_profile_type is "specified_from_file").

Type:

float

inflow_t_final

The last time instant available in the inflow HDF5 file.

Type:

float

Inflow velocity object

Parameters:

  • geom_dim (int) – The geometric dimension (as opposed to the topological dimension, usually this is 3)

  • params (pvade.Parameters.SimParams) – A SimParams object

calculate_u_ref(params)

Compute time-averaged inflow profile from file

Outputs:

u_ref : effective u_ref computed from input inflow file - velocity at panel elevation u_inf : streamwise velocity in freestream (at highest elevation in domain) z0

pvade.fluid.boundary_conditions.build_pressure_boundary_conditions(domain, params, functionspace)

Build all boundary conditions on pressure

This method builds all the boundary conditions associated with pressure and stores in a list, bcp.

Parameters:

  • domain (pvade.geometry.MeshManager.Domain) – A Domain object

  • params (pvade.Parameters.SimParams) – A SimParams object

pvade.fluid.boundary_conditions.build_temperature_boundary_conditions(domain, params, functionspace)

Build all boundary conditions on temperature

This method builds all the boundary conditions associated with temperature and stores in a list, bcT.

Parameters:

  • domain (pvade.geometry.MeshManager.Domain) – A Domain object

  • params (pvade.Parameters.SimParams) – A SimParams object

pvade.fluid.boundary_conditions.build_vel_bc_by_type(bc_type, domain, functionspace, bc_location)

Build a dirichlet bc

Parameters:

  • bc_type (str) – The type of simple boundary condition to apply, “slip” or “noslip”

  • domain (pvade.geometry.MeshManager.Domain) – A Domain object

  • functionspace (dolfinx.fem.FunctionSpace) – The dolfinx function space on which the boundary condition will be applied

  • bc_location (str, int) – A string identifier of the boundary condition location, e.g., “x_min” or the equivalent integer tag, e.g., 1

Returns:

A dolfinx dirichlet boundary condition

Return type:

dolfinx.fem.dirichletbc

pvade.fluid.boundary_conditions.build_velocity_boundary_conditions(domain, params, functionspace, current_time)

Build all boundary conditions on velocity

This method builds all the boundary conditions associated with velocity and stores in a list, bcu.

Parameters:

  • domain (pvade.geometry.MeshManager.Domain) – A Domain object

  • params (pvade.Parameters.SimParams) – A SimParams object

pvade.fluid.boundary_conditions.get_facet_dofs_by_gmsh_tag(domain, functionspace, location)

Associate degrees of freedom with marker functions

This function uses the marker information in the gmsh specification to find the corresponding degrees of freedom for use in the actual boundary condition specification. Note that this method does not require access to the facet information computed with _locate_boundary_entities.

Parameters:

  • domain (pvade.geometry.MeshManager.Domain) – A Domain object

  • functionspace (dolfinx.fem.FunctionSpace) – The dolfinx function space on which the boundary condition will be applied

  • location (str, int) – A string identifier of the boundary condition location, e.g., “x_min” or the equivalent integer tag, e.g., 1

Returns:

A list of the degrees of freedom associated with this tag and functionspace

Return type:

list

pvade.fluid.boundary_conditions.get_inflow_profile_function(domain, params, functionspace, current_time)

Build a DOLFINx function object containing the inflow velocity field.

Constructs a dolfinx.fem.Function on functionspace and populates it with the inflow velocity profile prescribed by params.fluid.velocity_profile_type. For the log-law profile, the velocity is set to zero below the surface-layer height (d0 + z0) to avoid logarithm singularities.

Parameters:

  • domain (pvade.geometry.MeshManager.FSIDomain) – The domain object, used to access the fluid mesh and MPI communicator.

  • params (pvade.IO.Parameters.SimParams) – A SimParams object.

  • functionspace (dolfinx.fem.FunctionSpace) – The velocity function space on which the inflow profile is interpolated.

  • current_time (float) – The simulation time at which the inflow profile is evaluated (relevant for "specified_from_file").

Returns:

  • inflow_function (dolfinx.fem.Function): The interpolated inflow velocity field.

  • inflow_velocity (InflowVelocity): The callable object used for interpolation.

  • upper_cells (np.ndarray or None): Mesh cell indices above the surface-layer roughness height (only non-None for the log-law profile).

Return type:

tuple

Top-level structural mechanics manager.

This module provides the Structure class, which acts as a facade that coordinates the structural analysis pipeline: it owns the Elasticity physics object, sets up function spaces and boundary conditions, delegates variational form assembly, and exposes a single Structure.solve() entry point used by the FSI coupling loop.

class pvade.structure.StructureMain.Structure(domain, params)

Bases: object

Top-level structural mechanics coordinator.

Structure wraps the lower-level Elasticity solver and adds mesh-topology bookkeeping (minimum cell size, dimension information) and material property storage. It is the object that the FSI loop interacts with directly.

comm

MPI communicator shared by all PVade objects.

rank

Rank of this MPI process.

Type:

int

num_procs

Total number of MPI processes.

Type:

int

structural_analysis

Flag indicating whether a structural analysis is being performed (read from params).

Type:

bool

name

Human-readable identifier (always "structure").

Type:

str

elasticity

The underlying nonlinear elasticity physics object.

Type:

pvade.structure.ElasticityAnalysis.Elasticity

ndim

Topological dimension of the structure mesh.

Type:

int

facet_dim

Facet dimension (ndim - 1).

Type:

int

hmin

Global minimum cell diameter across all MPI ranks.

Type:

float

num_V_dofs

Global number of displacement DOFs (delegated from elasticity).

Type:

int

rho

Mass density \(\rho\).

Type:

dolfinx.fem.Constant

E

Young’s modulus.

Type:

float

poissons_ratio

Poisson’s ratio.

Type:

float

lame_mu

Lamé shear modulus \(\mu\).

Type:

float

lame_lambda

Lamé first parameter \(\lambda\).

Type:

float

north_east_corner_dofs

DOF indices for the probe point at the north-east corner of the first panel.

Type:

np.ndarray

Initialize the fluid solver

This method initialize the Flow object, namely, it creates all the necessary function spaces on the mesh, initializes key counting and boolean variables and records certain characteristic quantities like the minimum cell size and the number of degrees of freedom attributed to both the pressure and velocity function spaces.

Parameters:

domain (pvade.geometry.MeshManager.Domain) – A Domain object

avg(x_old, x_new, alpha)

Return the generalized-alpha weighted average of two fields.

Parameters:

  • x_old – Field value at the previous time step.

  • x_new – Field value at the current time step.

  • alpha – Weighting parameter.

Returns:

Weighted average of x_old and x_new.

build_boundary_conditions(domain, params)

Build the boundary conditions

A method to manage the building of boundary conditions, including the steps of identifying entities on the boundary, marking those degrees of freedom either by the identified facets or a gmsh marker function, and finally assembling a list of Boundary objects that enforce the correct value.

Parameters:

  • domain (pvade.geometry.MeshManager.Domain) – A Domain object

  • params (pvade.Parameters.SimParams) – A SimParams object

build_forms(domain, params)

Builds all variational statements

This method creates all the functions, expressions, and variational forms that will be needed for the numerical solution of Navier Stokes using a fractional step method. This includes the calculation of a tentative velocity, the calculation of the change in pressure required to correct the tentative velocity to enforce continuity, and the update to the velocity field to reflect this change in pressure.

Parameters:

  • domain (pvade.geometry.MeshManager.Domain) – A Domain object

  • params (pvade.Parameters.SimParams) – A SimParams object

build_nullspace(V)

Build PETSc nullspace for 3D elasticity

solve(params, dataIO)

Advance the structural solution by one time step.

Delegates to pvade.structure.ElasticityAnalysis.Elasticity.solve().

Parameters:
update_a(u, u_old, v_old, a_old, dt, beta, ufl=True)

Compute the new acceleration using the Newmark update formula.

Delegates to pvade.structure.ElasticityAnalysis.Elasticity.update_a().

Parameters:

  • u – Current displacement field (UFL expression or NumPy array).

  • u_old – Displacement at the previous time step.

  • v_old – Velocity at the previous time step.

  • a_old – Acceleration at the previous time step.

  • dt – Time step size (UFL constant or Python float).

  • beta – Newmark \(\beta\) parameter.

  • ufl (bool) – True for UFL objects, False for plain floats.

Returns:

Updated acceleration field.

update_fields(u, u_old, v_old, a_old, dt, beta, gamma)

Update fields at the end of each time step.

update_v(a, u_old, v_old, a_old, dt, gamma, ufl=True)

Compute the new velocity using the Newmark update formula.

Delegates to pvade.structure.ElasticityAnalysis.Elasticity.update_v().

Parameters:

  • a – Current acceleration field (UFL expression or NumPy array).

  • u_old – Displacement at the previous time step (unused, kept for API consistency).

  • v_old – Velocity at the previous time step.

  • a_old – Acceleration at the previous time step.

  • dt – Time step size (UFL constant or Python float).

  • gamma – Newmark \(\gamma\) parameter.

  • ufl (bool) – True for UFL objects, False for plain floats.

Returns:

Updated velocity field.

Nonlinear elasticity solver using the Saint Venant–Kirchhoff material model.

This module implements the Elasticity class, which assembles and solves the structural mechanics problem using a generalized-alpha time integration scheme on a FEniCSx / DOLFINx mesh.

class pvade.structure.ElasticityAnalysis.Elasticity(domain, structural_analysis, params)

Bases: object

Nonlinear structural elasticity solver.

Assembles and solves the structural deformation problem using the Saint Venant–Kirchhoff constitutive model and the generalized-alpha time integration scheme. The class provides methods to build boundary conditions, assemble variational forms, and advance the solution in time.

comm

MPI communicator shared by all PVade objects.

rank

Rank of this MPI process.

Type:

int

num_procs

Total number of MPI processes.

Type:

int

V

Lagrange vector function space of degree 2 defined on the structure mesh.

Type:

dolfinx.fem.FunctionSpace

W

Discontinuous Lagrange scalar function space of degree 0 defined on the structure mesh.

Type:

dolfinx.fem.FunctionSpace

first_call_to_solver

Flag indicating whether the solver has been called for the first time.

Type:

bool

num_V_dofs

Global number of degrees of freedom in V.

Type:

int

eta_m

Rayleigh mass-proportional damping coefficient.

Type:

dolfinx.fem.Constant

eta_k

Rayleigh stiffness-proportional damping coefficient.

Type:

dolfinx.fem.Constant

alpha_m

Generalized-alpha parameter \(\alpha_m\).

Type:

dolfinx.fem.Constant

alpha_f

Generalized-alpha parameter \(\alpha_f\).

Type:

dolfinx.fem.Constant

gamma

Generalized-alpha parameter \(\gamma\).

Type:

float

beta

Generalized-alpha parameter \(\beta\).

Type:

float

dt_st

Structural time step size.

Type:

dolfinx.fem.Constant

Initialize the Elasticity class.

Sets up the FEniCSx function spaces, Rayleigh damping constants, and generalized-alpha time integration parameters on the structure submesh.

Parameters:

  • domain (pvade.geometry.MeshManager.FSIDomain) – A Domain object that holds the fluid and structure submeshes.

  • structural_analysis (bool) – Flag indicating whether a structural analysis is being performed.

  • params (pvade.IO.Parameters.SimParams) – A SimParams object containing all user-specified simulation parameters.

avg(x_old, x_new, alpha)

Return the generalized-alpha weighted average of two fields.

\[x_{\alpha} = \alpha \, x_{\text{old}} + (1 - \alpha) \, x_{\text{new}}\]
Parameters:

  • x_old – Field value at the previous time step.

  • x_new – Field value at the current time step.

  • alpha – Weighting parameter (typically alpha_m or alpha_f).

Returns:

Weighted average of x_old and x_new.

build_boundary_conditions(domain, params)

Build the boundary conditions

A method to manage the building of boundary conditions, including the steps of identifying entities on the boundary, marking those degrees of freedom either by the identified facets or a gmsh marker function, and finally assembling a list of Boundary objects that enforce the correct value.

Parameters:

  • domain (pvade.geometry.MeshManager.Domain) – A Domain object

  • params (pvade.Parameters.SimParams) – A SimParams object

build_forms(domain, params, structure)

Builds all variational statements

This method creates all the functions, expressions, and variational forms that will be needed for the numerical solution of Navier Stokes using a fractional step method. This includes the calculation of a tentative velocity, the calculation of the change in pressure required to correct the tentative velocity to enforce continuity, and the update to the velocity field to reflect this change in pressure.

Parameters:

  • domain (pvade.geometry.MeshManager.Domain) – A Domain object

  • params (pvade.Parameters.SimParams) – A SimParams object

build_nullspace(V)

Build the PETSc rigid-body nullspace for 3-D elasticity.

Constructs six orthonormal vectors corresponding to the three translational and three rotational rigid-body modes and assembles them into a PETSc NullSpace object. This nullspace is required by certain iterative solvers (e.g., AMG) to avoid near-singular behaviour.

Parameters:

V (dolfinx.fem.FunctionSpace) – The vector function space for which the nullspace is constructed. Must have exactly three sub-spaces (x, y, z displacement components).

Returns:

A PETSc nullspace object containing the six rigid-body modes.

Return type:

petsc4py.PETSc.NullSpace

solve(params, dataIO, structure)

Advance the structural solution by one time step.

On the first call this method assembles the nonlinear problem and creates the Newton solver with LU factorisation. On every call it solves the nonlinear system, scatters the solution, computes the displacement increment u_delta, updates the old fields, and appends the corner displacement to accel_pos.csv.

Parameters:
update_a(u, u_old, v_old, a_old, dt, beta, ufl=True)

Compute the new acceleration using the Newmark update formula.

\[a = \frac{u - u_0 - v_0 \, dt}{\beta \, dt^2} - \frac{1 - 2\beta}{2\beta} \, a_0\]
Parameters:

  • u – Current displacement field (UFL expression or NumPy array).

  • u_old – Displacement field at the previous time step.

  • v_old – Velocity field at the previous time step.

  • a_old – Acceleration field at the previous time step.

  • dt – Time step size (UFL constant or Python float).

  • beta – Newmark \(\beta\) parameter.

  • ufl (bool) – If True, operands are UFL objects; if False, Python floats are used for dt and beta.

Returns:

Updated acceleration field (UFL expression or NumPy array).

update_fields(u, u_old, v_old, a_old, dt, beta, gamma)

Update fields at the end of each time step.

update_v(a, u_old, v_old, a_old, dt, gamma, ufl=True)

Compute the new velocity using the Newmark update formula.

\[v = v_0 + dt \left[(1 - \gamma) \, a_0 + \gamma \, a \right]\]
Parameters:

  • a – Current acceleration field (UFL expression or NumPy array).

  • u_old – Displacement field at the previous time step (unused, kept for API consistency).

  • v_old – Velocity field at the previous time step.

  • a_old – Acceleration field at the previous time step.

  • dt – Time step size (UFL constant or Python float).

  • gamma – Newmark \(\gamma\) parameter.

  • ufl (bool) – If True, operands are UFL objects; if False, Python floats are used for dt and gamma.

Returns:

Updated velocity field (UFL expression or NumPy array).

Modal (eigenvalue) analysis for structural mechanics.

This module provides the ModalAnalysis class, which assembles the structural mass and stiffness matrices and solves the generalised eigenvalue problem to obtain natural frequencies and mode shapes. It shares the same time-integration infrastructure as Elasticity but is intended for free-vibration studies rather than time-domain forcing.

class pvade.structure.ModalAnalysis.ModalAnalysis(domain, structural_analysis, params)

Bases: object

Modal (eigenvalue) analysis solver.

Assembles the structural mass and stiffness matrices and solves the generalised eigenvalue problem to extract natural frequencies and mode shapes of the structure. The class also exposes the same update-formula helpers as Elasticity so that it can be used as a drop-in replacement when only the linear structural response is of interest.

comm

MPI communicator shared by all PVade objects.

rank

Rank of this MPI process.

Type:

int

num_procs

Total number of MPI processes.

Type:

int

structural_analysis

Flag passed through from params.

Type:

bool

name

Human-readable identifier (always "structure").

Type:

str

V

Lagrange vector function space of degree 2 on the structure mesh.

Type:

dolfinx.fem.FunctionSpace

first_call_to_solver

Flag indicating whether the solver has been called for the first time.

Type:

bool

num_V_dofs

Global number of degrees of freedom in V.

Type:

int

ndim

Topological dimension of the structure mesh.

Type:

int

facet_dim

Facet dimension (ndim - 1).

Type:

int

hmin

Global minimum cell diameter across all MPI ranks.

Type:

float

rho

Mass density \(\rho\).

Type:

dolfinx.fem.Constant

eta_m

Rayleigh mass-proportional damping coefficient.

Type:

dolfinx.fem.Constant

eta_k

Rayleigh stiffness-proportional damping coefficient.

Type:

dolfinx.fem.Constant

alpha_m

Generalized-alpha parameter \(\alpha_m\).

Type:

dolfinx.fem.Constant

alpha_f

Generalized-alpha parameter \(\alpha_f\).

Type:

dolfinx.fem.Constant

gamma

Generalized-alpha parameter \(\gamma\).

Type:

float

beta

Generalized-alpha parameter \(\beta\).

Type:

float

E

Young’s modulus.

Type:

float

poissons_ratio

Poisson’s ratio.

Type:

float

lame_mu

First Lamé parameter \(\mu\).

Type:

float

lame_lambda

Second Lamé parameter \(\lambda\).

Type:

float

dt_st

Structural time step size.

Type:

dolfinx.fem.Constant

north_east_corner_dofs

DOF indices for the probe point at the north-east corner of the structure.

Type:

np.ndarray

Initialize the fluid solver

This method initialize the Flow object, namely, it creates all the necessary function spaces on the mesh, initializes key counting and boolean variables and records certain characteristic quantities like the minimum cell size and the number of degrees of freedom attributed to both the pressure and velocity function spaces.

Parameters:

domain (pvade.geometry.MeshManager.Domain) – A Domain object

avg(x_old, x_new, alpha)

Return the generalized-alpha weighted average of two fields.

\[x_{\alpha} = \alpha \, x_{\text{old}} + (1 - \alpha) \, x_{\text{new}}\]
Parameters:

  • x_old – Field value at the previous time step.

  • x_new – Field value at the current time step.

  • alpha – Weighting parameter.

Returns:

Weighted average of x_old and x_new.

build_boundary_conditions(domain, params)

Build the boundary conditions

A method to manage the building of boundary conditions, including the steps of identifying entities on the boundary, marking those degrees of freedom either by the identified facets or a gmsh marker function, and finally assembling a list of Boundary objects that enforce the correct value.

Parameters:

  • domain (pvade.geometry.MeshManager.Domain) – A Domain object

  • params (pvade.Parameters.SimParams) – A SimParams object

build_forms(domain, params)

Builds all variational statements

This method creates all the functions, expressions, and variational forms that will be needed for the numerical solution of Navier Stokes using a fractional step method. This includes the calculation of a tentative velocity, the calculation of the change in pressure required to correct the tentative velocity to enforce continuity, and the update to the velocity field to reflect this change in pressure.

Parameters:

  • domain (pvade.geometry.MeshManager.Domain) – A Domain object

  • params (pvade.Parameters.SimParams) – A SimParams object

build_nullspace(V)

Build PETSc nullspace for 3D elasticity

solve(params, dataIO)
update_a(u, u_old, v_old, a_old, dt, beta, ufl=True)

Compute the new acceleration using the Newmark update formula.

\[a = \frac{u - u_0 - v_0 \, dt}{\beta \, dt^2} - \frac{1 - 2\beta}{2\beta} \, a_0\]
Parameters:

  • u – Current displacement field (UFL expression or NumPy array).

  • u_old – Displacement field at the previous time step.

  • v_old – Velocity field at the previous time step.

  • a_old – Acceleration field at the previous time step.

  • dt – Time step size (UFL constant or Python float).

  • beta – Newmark \(\beta\) parameter.

  • ufl (bool) – If True, operands are UFL objects; if False, Python floats are used for dt and beta.

Returns:

Updated acceleration field (UFL expression or NumPy array).

update_fields(u, u_old, v_old, a_old, dt, beta, gamma)

Update fields at the end of each time step.

update_v(a, u_old, v_old, a_old, dt, gamma, ufl=True)

Compute the new velocity using the Newmark update formula.

\[v = v_0 + dt \left[(1 - \gamma) \, a_0 + \gamma \, a \right]\]
Parameters:

  • a – Current acceleration field (UFL expression or NumPy array).

  • u_old – Displacement field at the previous time step (unused, kept for API consistency).

  • v_old – Velocity field at the previous time step.

  • a_old – Acceleration field at the previous time step.

  • dt – Time step size (UFL constant or Python float).

  • gamma – Newmark \(\gamma\) parameter.

  • ufl (bool) – If True, operands are UFL objects; if False, Python floats are used for dt and gamma.

Returns:

Updated velocity field (UFL expression or NumPy array).

Boundary condition utilities for the structural mechanics solver.

This module provides helper functions for identifying structural boundary entities and assembling Dirichlet boundary conditions on the structure mesh, including both surface-based BCs (fixed edges/faces) and line-based BCs (torque-tube and motor-mount connections along 1-D fixation lines).

class pvade.structure.boundary_conditions.InflowVelocity(geom_dim, params)

Bases: object

Inflow velocity object

Parameters:

  • geom_dim (int) – The geometric dimension (as opposed to the topological dimension, usually this is 3)

  • params (pvade.Parameters.SimParams) – A SimParams object

pvade.structure.boundary_conditions.build_pressure_boundary_conditions(domain, params, functionspace)

Build all boundary conditions on pressure

This method builds all the boundary conditions associated with pressure and stores in a list, bcp.

Parameters:

  • domain (pvade.geometry.MeshManager.Domain) – A Domain object

  • params (pvade.Parameters.SimParams) – A SimParams object

pvade.structure.boundary_conditions.build_structure_boundary_conditions(domain, params, functionspace)

Build all Dirichlet boundary conditions for the structure.

Applies zero-displacement constraints on all panel surface faces listed in params.structure.bc_list. Optionally pins nodes along the torque tube line (params.structure.tube_connection) and along motor-mount lines (params.structure.motor_connection) using a collinearity test.

Parameters:

  • domain (pvade.geometry.MeshManager.FSIDomain) – A Domain object that holds the structure submesh and facet tags.

  • params (pvade.IO.Parameters.SimParams) – A SimParams object containing boundary condition settings and panel geometry.

  • functionspace (dolfinx.fem.FunctionSpace) – The vector displacement function space on which boundary conditions are applied.

Returns:

A list of assembled Dirichlet boundary condition objects ready to be passed to the nonlinear solver.

Return type:

list[dolfinx.fem.DirichletBC]

pvade.structure.boundary_conditions.build_vel_bc_by_type(bc_type, domain, functionspace, bc_location)

Build a dirichlet bc

Parameters:

  • bc_type (str) – The type of simple boundary condition to apply, “slip” or “noslip”

  • domain (pvade.geometry.MeshManager.Domain) – A Domain object

  • functionspace (dolfinx.fem.FunctionSpace) – The dolfinx function space on which the boundary condition will be applied

  • bc_location (str, int) – A string identifier of the boundary condition location, e.g., “x_min” or the equivalent integer tag, e.g., 1

Returns:

A dolfinx dirichlet boundary condition

Return type:

dolfinx.fem.dirichletbc

pvade.structure.boundary_conditions.build_velocity_boundary_conditions(domain, params, functionspace)

Build all boundary conditions on velocity

This method builds all the boundary conditions associated with velocity and stores in a list, bcu.

Parameters:

  • domain (pvade.geometry.MeshManager.Domain) – A Domain object

  • params (pvade.Parameters.SimParams) – A SimParams object

pvade.structure.boundary_conditions.get_facet_dofs_by_gmsh_tag(domain, functionspace, location)

Associate degrees of freedom with marker functions

This function uses the marker information in the gmsh specification to find the corresponding degrees of freedom for use in the actual boundary condition specification. Note that this method does not require access to the facet information computed with _locate_boundary_entities.

Parameters:

  • domain (pvade.geometry.MeshManager.Domain) – A Domain object

  • functionspace (dolfinx.fem.FunctionSpace) – The dolfinx function space on which the boundary condition will be applied

  • location (str, int) – A string identifier of the boundary condition location, e.g., “x_min” or the equivalent integer tag, e.g., 1

Returns:

A list of the degrees of freedom associated with this tag and functionspace

Return type:

list

pvade.structure.boundary_conditions.get_inflow_profile_function(domain, params, functionspace)

Computational domain construction and mesh management.

This module provides the FSIDomain class, which orchestrates the entire geometry-to-mesh pipeline:

  1. Builds the CAD geometry by delegating to a problem-specific

    DomainCreation module selected at runtime.

  2. Marks fluid and structural surface/volume regions with integer tags.

  3. Generates the mesh with Gmsh.

  4. Distributes the mesh across MPI ranks via DOLFINx.

  5. Extracts fluid and structure submeshes from the parent mesh using cell tags.

  6. Transfers facet tags to each submesh for boundary-condition assignment.

class pvade.geometry.MeshManager.FSIDomain(params)

Bases: object

Fluid–structure interaction computational domain.

FSIDomain creates and manages the complete computational domain for PVade simulations, including both the fluid mesh and the structure mesh. It delegates geometry creation to a problem-specific DomainCreation module (e.g., pvade.geometry.panels3d.DomainCreation) and provides methods for mesh generation, submesh extraction, and I/O.

comm

MPI communicator shared by all PVade objects.

rank

Rank of this MPI process.

Type:

int

num_procs

Total number of MPI processes.

Type:

int

first_move_mesh

Flag used by the ALE mesh-motion routines.

Type:

bool

domain_markers

Dictionary mapping boundary/cell region names to their integer tag indices ("idx"), entity type ("facet" or "cell"), and Gmsh tag lists.

Type:

dict

numpy_pt_total_array

Array of shape (N_lines, 6) defining fixation line endpoints used to apply torque-tube and motor-mount BCs.

Type:

np.ndarray or None

ndim

Topological dimension of the mesh (set during build()).

Type:

int or None

The class is initialised here

Depending on the example we are solving, we import the corresponding DomainCrearion file We define markers which will be used for boundary tag asignment

Parameters:

params (input parameters) – input parameters available in the input file

build(params)

This function call builds the geometry, marks the boundaries and creates a mesh using Gmsh.

move_mesh(structure, params)
read_mesh_files(read_mesh_dir, params)

Read the mesh from an external file. The User can load an existing mesh file (mesh.xdmf) and use it to solve the CFD/CSD problem

test_mesh_functionspace()
test_submesh_transfer(params)
write_mesh_files(params)

Write the fluid and structure submesh files to disk.

Saves each active submesh as an XDMF file (with cell and facet tag arrays) and as a native Gmsh .msh file. Also writes the domain_markers dictionary to a YAML file and the fixation-point array to a CSV file.

Parameters:

params (pvade.IO.Parameters.SimParams) – A SimParams object providing the mesh output directory path.

Fluid-structure coupling utilities.

This module defines the FSI class used to transfer fluid traction loads to the structure solver. The main coupling operation is implemented in FSI.fluid_struct(), where panel stress fields computed by the fluid solver are relaxed and written into the structural solver state.

class pvade.fsi.FSI.FSI(domain, flow, structure, params)

Bases: object

Fluid-structure coupling manager.

Stores MPI metadata and provides a method to transfer fluid stresses to the structural solver with optional under-relaxation.

comm

An MPI communicator used by all PVade objects

Type:

MPI Communicator

ndim

The number of dimensions in the problem

Type:

int

num_procs

The total number of processors being used to solve the problem

Type:

int

rank

A unique ID for each process in the range [0, 1, …, num_procs-1]

Type:

int

Initialize the FSI coupling object.

Stores MPI communicator metadata and the problem dimensionality used during coupling operations.

Parameters:
fluid_struct(domain, flow, structure, params)

Transfer fluid stress to the structure and apply relaxation.

Performs one FSI coupling update:

  1. Copies the previous structural stress state to stress_old.

  2. Interpolates the current fluid panel stress field onto the structure stress function.

  3. Applies linear under-relaxation using params.structure.beta_relaxation and the predicted stress.

Parameters: