matrix_builder¶

Matrix builders for assembling the sparse linear systems used to solve for pressures and flows. Two construction styles are provided:

A full node/edge matrix builder (create_matrices()) that assembles
a mixed system coupling nodal mass-conservation equations with edge pressure-drop equations. This produces a (n+m) x (n+m) sparse system where n is the number of nodes and m the number of edges.
A reduced (small) matrix builder (create_small_matrices())
that uses network incidence matrices and a weighted Laplacian-style construction to produce a smaller r x r system. This is used for faster solves in typical tree-like topologies.

Important functions¶

create_matrices(G, n, m, bcs): Build the (n + m) sparse linear system A and vector b. Performs validation of boundary conditions and constructs rows for: - mass conservation at nodes - pressure drop along edges (Ohm’s law: p_u - p_v = R q)
create_small_matrices(G, bcs, branching_angles=False, non_linear_rheology=False): Build a reduced sparse system using network incidence matrices and a diagonal resistance weighting. Returns (A, b, bc_export, iter_options) where bc_export summarises boundary indices and iter_options contains auxiliary matrices for iterative updates (branching-angle corrections etc.).

Notes¶

Boundary conditions for inlet/outlet must be created using
FetoFlow.bc_utils.generate_boundary_conditions().
The reduced builder supports both pressure and flow inlet types and
sets up the linear system accordingly.

API reference¶

Function arguments¶

create_matrices

Gnetworkx.DiGraph: Graph representing the vascular network. Edges must contain a resistance attribute and edge_id values.
nint: Number of nodes in the graph (expected to equal G.number_of_nodes()).
mint: Number of edges in the graph (expected to equal G.number_of_edges()).
bcsdict: Boundary condition dictionary created by FetoFlow.bc_utils.generate_boundary_conditions().

Ascipy.sparse.csr_matrix

The assembled sparse system matrix of shape (n+m, n+m).

bnumpy.ndarray

Right-hand side vector of length (n+m).

The function validates that the provided n and m match the
graph size and will raise AssertionError if they differ.
Use FetoFlow.bc_utils.generate_boundary_conditions() to
prepare the bcs argument.

>>> A, b = create_matrices(G, n=G.number_of_nodes(), m=G.number_of_edges(), bcs=bcs)

create_small_matrices

Gnetworkx.DiGraph: Graph representing the vascular network.
bcsdict: Normalised boundary condition dict.
branching_anglesbool, optional: Include extra matrices to account for branching-angle pressure losses when returning iteration options.
non_linear_rheologybool, optional: Reserved for future use; currently not fully implemented.

Ascipy.sparse matrix: Reduced system matrix.
bnumpy.ndarray: Right-hand side vector for the reduced system.
bc_exporttuple: Tuple summarising boundary condition structure for the small system.
iter_optionsdict or None: Auxiliary matrices and metadata needed for iterative updates (branching-angle matrices etc.) or None.

Examples¶

# Full matrix
A, b = create_matrices(G, n=G.number_of_nodes(), m=G.number_of_edges(), bcs=bcs)

# Reduced small matrices
A_s, b_s, bc_export, iter_opts = create_small_matrices(G, bcs)

Cross references¶

The reduced matrices are consumed by FetoFlow.solve_utils.solve_small_system().

>>> A, b, bc_export, iter_options = create_small_matrices(G, bcs, branching_angles=True)
>>> # iterative solvers use iter_options to update A during non-linear solves
FetoFlow.solve_utils.solve_small_system(), FetoFlow.solve_utils.iterative_solve_small()