API documentation

API documentation#

cli#

calculus#

cardiac_geometries.calculus.estimate_focal_point(mesh, axis=0)[source]#

Copmute the focal point based on approximating the endocardial surfaces as a ellipsoidal cap.

\[focal = \sqrt{ l^2 - s^2}\]
Parameters:

mesh (dolfin.mesh) – The mesh

Returns:

focal_point – The focal point

Return type:

float

cardiac_geometries.calculus.get_strain_regions(nsectors=(6, 6, 4, 1))[source]#

Mark the cells in the mesh.

For instance if you want to mark this mesh accoring to the AHA 17-segment model, then nsector = [6,6,4,1], i.e 6 basal, 6 mid, 4 apical and one apex

cardiac_geometries.calculus.strain_region_number(T, regions)[source]#

For a given point in prolate coordinates, return the region it belongs to.

Parameters:

  • regions (numpy.array) – Array of all coordinates for the strain regions taken from the strain mesh.

  • T (numpy.array) – Some value i prolate coordinates

Resturn the region number that T belongs to

gmsh#

cardiac_geometries.gmsh.lv_ellipsoid(mesh_name: str | Path = '', r_short_endo=0.025, r_short_epi=0.035, r_long_endo=0.09, r_long_epi=0.097, psize_ref=0.005, mu_apex_endo=-3.141592653589793, mu_base_endo=-1.2722641256100204, mu_apex_epi=-3.141592653589793, mu_base_epi=-1.318116071652818, verbose=False) → Path#

Create general LV ellipsoid

Parameters:

  • mesh_name (str, optional) – Name of the mesh, by default “”

  • r_short_endo (float, optional) – Shortest radius on the endocardium layer, by default 0.025

  • r_short_epi (float, optional) – Shortest radius on the epicardium layer, by default 0.035

  • r_long_endo (float, optional) – Longest radius on the endocardium layer, by default 0.09

  • r_long_epi (float, optional) – Longest radius on the epicardium layer, by default 0.097

  • psize_ref (float, optional) – The reference point size (smaller values yield as finer mesh, by default 0.005

  • mu_apex_endo (float, optional) – Angle for the endocardial apex, by default -math.pi

  • mu_base_endo (float, optional) – Angle for the endocardial base, by default -math.acos(5 / 17)

  • mu_apex_epi (float, optional) – Angle for the epicardial apex, by default -math.pi

  • mu_base_epi (float, optional) – Angle for the epicardial apex, by default -math.acos(5 / 20)

  • verbose (bool, optional) – If True, also display output from gmsh, by default False

Returns:

Path to the generated gmsh file

Return type:

Path

cardiac_geometries.gmsh.lv_ellipsoid_2D(mesh_name: str | Path = '', r_short_endo: float = 7.0, r_short_epi: float = 10.0, r_long_endo: float = 17.0, r_long_epi: float = 20.0, psize_ref=3.0, mu_apex_endo=-3.141592653589793, mu_base_endo=-1.2722641256100204, mu_apex_epi=-3.141592653589793, mu_base_epi=-1.318116071652818) → Path#

Create general LV ellipsoid

Parameters:

  • mesh_name (str, optional) – Name of the mesh, by default “”

  • r_short_endo (float, optional) – Shortest radius on the endocardium layer, by default 0.025

  • r_short_epi (float, optional) – Shortest radius on the epicardium layer, by default 0.035

  • r_long_endo (float, optional) – Longest radius on the endocardium layer, by default 0.09

  • r_long_epi (float, optional) – Longest radius on the epicardium layer, by default 0.097

  • psize_ref (float, optional) – The reference point size (smaller values yield as finer mesh, by default 0.005

  • mu_apex_endo (float, optional) – Angle for the endocardial apex, by default -math.pi

  • mu_base_endo (float, optional) – Angle for the endocardial base, by default -math.acos(5 / 17)

  • mu_apex_epi (float, optional) – Angle for the epicardial apex, by default -math.pi

  • mu_base_epi (float, optional) – Angle for the epicardial apex, by default -math.acos(5 / 20)

Returns:

Path to the generated gmsh file

Return type:

Path

cardiac_geometries.gmsh.lv_ellipsoid_flat_base(mesh_name: str | Path = '', r_short_endo: float = 7.0, r_short_epi: float = 10.0, r_long_endo: float = 17.0, r_long_epi: float = 20.0, quota_base: float = -5.0, psize: float = 3.0, ndiv: float = 1.0) → Path#

Create an LV ellipsoids with a flat base

Parameters:

  • mesh_name (str, optional) – Name of the mesh by default “”

  • r_short_endo (float, optional) – Shortest radius on the endocardium layer, by default 7.0

  • r_short_epi (float, optional) – Shortest radius on the epicardium layer, by default 10.0

  • r_long_endo (float, optional) – Longest radius on the endocardium layer, by default 17.0

  • r_long_epi (float, optional) – Longest radius on the epicardium layer, by default 20.0

  • quota_base (float, optional) – Position of the base relative to the x=0 plane, by default -5.0

  • psize (float, optional) – Point size, by default 3.0

  • ndiv (float, optional) – Number of divisions, by default 1.0

Returns:

Path to file

Return type:

Path

cardiac_geometries.gmsh.prolate_lv_ellipsoid(mesh_name: str | Path = '', a: float = 2.0, nu_epi: float = 0.8, nu_endo: float = 0.5, psize_ref=1.0, mu_apex_endo=-3.141592653589793, mu_base_endo=-1.2722641256100204, mu_apex_epi=-3.141592653589793, mu_base_epi=-1.318116071652818) → Path#

Create an LV ellipsoid in prolate spheroidal coordinates

Parameters:

  • mesh_name (str, optional) – _description_, by default “”

  • a (float, optional) – _description_, by default 2.0

  • nu_epi (float, optional) – _description_, by default 0.8

  • nu_endo (float, optional) – _description_, by default 0.5

  • psize_ref (float, optional) – _description_, by default 1.0

  • mu_apex_endo (_type_, optional) – _description_, by default -math.pi

  • mu_base_endo (_type_, optional) – _description_, by default -math.acos(5 / 17)

  • mu_apex_epi (_type_, optional) – _description_, by default -math.pi

  • mu_base_epi (_type_, optional) – _description_, by default -math.acos(5 / 20)

Returns:

Path to the generated gmsh file

Return type:

Path

cardiac_geometries.gmsh.prolate_lv_ellipsoid_flat_base(mesh_name: str | Path = '', a: float = 25.0, nu_epi: float = 0.8, nu_endo: float = 0.5, quota_base: float = -5.0, psize: float = 3.0, ndiv: float = 1.0) → Path#

Create an LV ellipsoid with flat base in prolate spheroidal coordinates

Parameters:

  • mesh_name (str, optional) – _description_, by default “”

  • a (float, optional) – _description_, by default 25.0

  • nu_epi (float, optional) – _description_, by default 0.8

  • nu_endo (float, optional) – _description_, by default 0.5

  • quota_base (float, optional) – _description_, by default -5.0

  • psize (float, optional) – _description_, by default 3.0

  • ndiv (float, optional) – _description_, by default 1.0

Returns:

Path to the generated gmsh file

Return type:

Path

cardiac_geometries.gmsh.slab(mesh_name: str | Path = '', lx=20.0, ly=7.0, lz=3.0, dx=1.0, verbose: bool = False) → Path#

Create a slab geometry

Parameters:

  • mesh_name (str | Path, optional) – Filename where to save the mesh, by default “”

  • lx (float, optional) – Length in x direction, by default 20.0

  • ly (float, optional) – Length in y direction, by default 7.0

  • lz (float, optional) – Length in z direction, by default 3.0

  • dx (float, optional) – Mesh resolution, by default 1.0

  • verbose (bool, optional) – If True, also display output from gmsh, by default False

Returns:

Path to the mesh file

Return type:

Path

cardiac_geometries.gmsh.slab_in_bath(mesh_name: str | Path = '', lx=1.0, ly=0.01, lz=0.5, bx=0.0, by=0.0, bz=0.1, dx=0.001, verbose: bool = False)#

Create slab inside a bath

Parameters:

  • mesh_name (str | Path, optional) – Filename where to save the mesh, by default “”

  • lx (float, optional) – Length in x direction, by default 20.0

  • ly (float, optional) – Length in y direction, by default 7.0

  • lz (float, optional) – Length in z direction, by default 3.0

  • dx (float, optional) – Mesh resolution, by default 1.0

  • verbose (bool, optional) – If True, also display output from gmsh, by default False

Returns:

Path to the mesh file

Return type:

Path

mesh#

cardiac_geometries._mesh.create_biv_ellipsoid(outdir: str | Path | None = None, char_length: float = 0.5, center_lv_x: float = 0.0, center_lv_y: float = 0.0, center_lv_z: float = 0.0, a_endo_lv: float = 2.5, b_endo_lv: float = 1.0, c_endo_lv: float = 1.0, a_epi_lv: float = 3.0, b_epi_lv: float = 1.5, c_epi_lv: float = 1.5, center_rv_x: float = 0.0, center_rv_y: float = 0.5, center_rv_z: float = 0.0, a_endo_rv: float = 3.0, b_endo_rv: float = 1.5, c_endo_rv: float = 1.5, a_epi_rv: float = 4.0, b_epi_rv: float = 2.5, c_epi_rv: float = 2.0, create_fibers: bool = False, fiber_angle_endo: float = -60, fiber_angle_epi: float = 60, fiber_space: str = 'P_1') → Geometry | None[source]#

Create BiV ellipsoidal geometry

Parameters:

  • outdir (Union[str, Path, None], optional) – Directory where to save the results. If not provided a temporary directory will be created, by default None, by default None

  • char_length (float, optional) – Characteristic length of mesh, by default 0.5

  • center_lv_y (float, optional) – X-coordinate for the center of the lv, by default 0.0

  • center_lv_y – Y-coordinate for the center of the lv, by default 0.0

  • center_lv_z (float, optional) – Z-coordinate for the center of the lv, by default 0.0

  • a_endo_lv (float, optional) – Dilation of lv endo ellipsoid in the x-direction, by default 2.5

  • b_endo_lv (float, optional) – Dilation of lv endo ellipsoid in the y-direction, by default 1.0

  • c_endo_lv (float, optional) – Dilation of lv endo ellipsoid in the z-direction, by default 1.0

  • a_epi_lv (float, optional) – Dilation of lv epi ellipsoid in the x-direction, by default 3.0

  • b_epi_lv (float, optional) – Dilation of lv epi ellipsoid in the y-direction, by default 1.5

  • c_epi_lv (float, optional) – Dilation of lv epi ellipsoid in the z-direction, by default 1.5

  • center_rv_x (float, optional) – X-coordinate for the center of the rv, by default 0.0

  • center_rv_y (float, optional) – Y-coordinate for the center of the rv, by default 0.5

  • center_rv_z (float, optional) – Z-coordinate for the center of the rv, by default 0.0

  • a_endo_rv (float, optional) – Dilation of rv endo ellipsoid in the x-direction, by default 3.0

  • b_endo_rv (float, optional) – Dilation of rv endo ellipsoid in the y-direction, by default 1.5

  • c_endo_rv (float, optional) – Dilation of rv endo ellipsoid in the z-direction, by default 1.5

  • a_epi_rv (float, optional) – Dilation of rv epi ellipsoid in the x-direction, by default 4.0

  • b_epi_rv (float, optional) – Dilation of rv epi ellipsoid in the y-direction, by default 2.5

  • c_epi_rv (float, optional) – Dilation of rv epi ellipsoid in the z-direction, by default 2.0

  • create_fibers (bool, optional) – If True create analytic fibers, by default False

  • fiber_angle_endo (float, optional) – Angle for the endocardium, by default -60

  • fiber_angle_epi (float, optional) – Angle for the epicardium, by default +60

  • fiber_space (str, optional) – Function space for fibers of the form family_degree, by default “P_1”

Returns:

A Geometry with the mesh, markers, markers functions and fibers. Returns None if dolfin is not installed.

Return type:

Optional[Geometry]

Raises:

ImportError – If gmsh is not installed

cardiac_geometries._mesh.create_biv_ellipsoid_torso(outdir: str | Path | None = None, char_length: float = 0.5, heart_as_surface: bool = False, torso_length: float = 20.0, torso_width: float = 20.0, torso_height: float = 20.0, rotation_angle: float = 0.5235987755982988, center_lv_x: float = 0.0, center_lv_y: float = 0.0, center_lv_z: float = 0.0, a_endo_lv: float = 2.5, b_endo_lv: float = 1.0, c_endo_lv: float = 1.0, a_epi_lv: float = 3.0, b_epi_lv: float = 1.5, c_epi_lv: float = 1.5, center_rv_x: float = 0.0, center_rv_y: float = 0.5, center_rv_z: float = 0.0, a_endo_rv: float = 3.0, b_endo_rv: float = 1.5, c_endo_rv: float = 1.5, a_epi_rv: float = 4.0, b_epi_rv: float = 2.5, c_epi_rv: float = 2.0, create_fibers: bool = False, fiber_angle_endo: float = -60, fiber_angle_epi: float = 60, fiber_space: str = 'P_1') → Geometry | None[source]#

Create BiV ellipsoidal geometry

Parameters:

  • outdir (Union[str, Path, None], optional) – Directory where to save the results. If not provided a temporary directory will be created, by default None, by default None

  • char_length (float, optional) – Characteristic length of mesh, by default 0.5

  • heart_as_surface (bool) – If true, create the heart as a a surface inside the torso, otherwise let the heart be a volume, by default True.

  • torso_length (float, optional) – Length of torso in the x-direction, by default 20.0

  • torso_width (float, optional) – Length of torso in the y-direction, by default 20.0

  • torso_height (float, optional) – Length of torso in the z-direction, by default 20.0

  • rotation_angle (float, optional) – Angle to rotate the torso in order to object realistic position of the heart in a torso, by default pi / 6

  • center_lv_x (float, optional) – X-coordinate for the center of the lv, by default 0.0

  • center_lv_y (float, optional) – Y-coordinate for the center of the lv, by default 0.0

  • center_lv_z (float, optional) – Z-coordinate for the center of the lv, by default 0.0

  • a_endo_lv (float, optional) – Dilation of lv endo ellipsoid in the x-direction, by default 2.5

  • b_endo_lv (float, optional) – Dilation of lv endo ellipsoid in the y-direction, by default 1.0

  • c_endo_lv (float, optional) – Dilation of lv endo ellipsoid in the z-direction, by default 1.0

  • a_epi_lv (float, optional) – Dilation of lv epi ellipsoid in the x-direction, by default 3.0

  • b_epi_lv (float, optional) – Dilation of lv epi ellipsoid in the y-direction, by default 1.5

  • c_epi_lv (float, optional) – Dilation of lv epi ellipsoid in the z-direction, by default 1.5

  • center_rv_x (float, optional) – X-coordinate for the center of the rv, by default 0.0

  • center_rv_y (float, optional) – Y-coordinate for the center of the rv, by default 0.5

  • center_rv_z (float, optional) – Z-coordinate for the center of the rv, by default 0.0

  • a_endo_rv (float, optional) – Dilation of rv endo ellipsoid in the x-direction, by default 3.0

  • b_endo_rv (float, optional) – Dilation of rv endo ellipsoid in the y-direction, by default 1.5

  • c_endo_rv (float, optional) – Dilation of rv endo ellipsoid in the z-direction, by default 1.5

  • a_epi_rv (float, optional) – Dilation of rv epi ellipsoid in the x-direction, by default 4.0

  • b_epi_rv (float, optional) – Dilation of rv epi ellipsoid in the y-direction, by default 2.5

  • c_epi_rv (float, optional) – Dilation of rv epi ellipsoid in the z-direction, by default 2.0

  • create_fibers (bool, optional) – If True create analytic fibers, by default False

  • fiber_angle_endo (float, optional) – Angle for the endocardium, by default -60

  • fiber_angle_epi (float, optional) – Angle for the epicardium, by default +60

  • fiber_space (str, optional) – Function space for fibers of the form family_degree, by default “P_1”

Returns:

A Geometry with the mesh, markers, markers functions and fibers. Returns None if dolfin is not installed.

Return type:

Optional[Geometry]

Raises:

ImportError – If gmsh is not installed

cardiac_geometries._mesh.create_lv_ellipsoid(outdir: str | Path | None = None, r_short_endo: float = 7.0, r_short_epi: float = 10.0, r_long_endo: float = 17.0, r_long_epi: float = 20.0, psize_ref: float = 3, mu_apex_endo: float = -3.141592653589793, mu_base_endo: float = -1.2722641256100204, mu_apex_epi: float = -3.141592653589793, mu_base_epi: float = -1.318116071652818, create_fibers: bool = False, fiber_angle_endo: float = -60, fiber_angle_epi: float = 60, fiber_space: str = 'P_1', aha: bool = False, axisymmetric: bool = False) → Geometry | None[source]#

Create an LV ellipsoidal geometry

Parameters:

  • outdir (Optional[Path], optional) – Directory where to save the results. If not provided a temporary directory will be created, by default None

  • r_short_endo (float, optional) – Shortest radius on the endocardium layer, by default 7.0

  • r_short_epi (float, optional) – Shortest radius on the epicardium layer, by default 10.0

  • r_long_endo (float, optional) – Longest radius on the endocardium layer, by default 17.0

  • r_long_epi (float, optional) – Longest radius on the epicardium layer, by default 20.0

  • psize_ref (float, optional) – The reference point size (smaller values yield as finer mesh, by default 3

  • mu_apex_endo (float, optional) – Angle for the endocardial apex, by default -math.pi

  • mu_base_endo (float, optional) – Angle for the endocardial base, by default -math.acos(5 / 17)

  • mu_apex_epi (float, optional) – Angle for the epicardial apex, by default -math.pi

  • mu_base_epi (float, optional) – Angle for the epicardial apex, by default -math.acos(5 / 20)

  • create_fibers (bool, optional) – If True create analytic fibers, by default False

  • fiber_angle_endo (float, optional) – Angle for the endocardium, by default -60

  • fiber_angle_epi (float, optional) – Angle for the epicardium, by default +60

  • fiber_space (str, optional) – Function space for fibers of the form family_degree, by default “P_1”

  • aha (bool, optional) – If True create 17-segment AHA regions

  • axisymmetric (bool, optional) – If True create a 2D axisymmetric mesh, by default False

Returns:

A Geometry with the mesh, markers, markers functions and fibers. Returns None if dolfin is not installed.

Return type:

Optional[Geometry]

Raises:

ImportError – If gmsh is not installed

cardiac_geometries._mesh.create_slab(outdir: str | Path | None = None, lx: float = 20.0, ly: float = 7.0, lz: float = 3.0, dx: float = 1.0, create_fibers: bool = True, fiber_angle_endo: float = -60, fiber_angle_epi: float = 60, fiber_space: str = 'P_1') → Geometry | None[source]#

Create slab geometry

Parameters:

  • outdir (Optional[Path], optional) – Directory where to save the results. If not provided a temporary directory will be created, by default None

  • lx (float, optional) – Length of slab the x-direction, by default 20.0

  • ly (float, optional) – Length of slab the x-direction, by default 7.0

  • lz (float, optional) – Length of slab the z-direction, by default 3.0

  • dx (float, optional) – Element size, by default 1.0

  • create_fibers (bool, optional) – If True create analytic fibers, by default True

  • fiber_angle_endo (float, optional) – Angle for the endocardium, by default -60

  • fiber_angle_epi (float, optional) – Angle for the epicardium, by default +60

  • fiber_space (str, optional) – Function space for fibers of the form family_degree, by default “P_1”

Returns:

A Geometry with the mesh, markers, markers functions and fibers. Returns None if dolfin is not installed.

Return type:

Optional[Geometry]

Raises:

ImportError – If gmsh is not installed

cardiac_geometries._mesh.create_slab_in_bath(outdir: str | Path | None = None, lx: float = 1.0, ly: float = 0.01, lz: float = 0.5, bx: float = 0.0, by: float = 0.0, bz: float = 0.1, dx: float = 0.001) → Geometry | None[source]#

Create slab geometry

Parameters:

  • outdir (Optional[Path], optional) – Directory where to save the results. If not provided a temporary directory will be created, by default None

  • lx (float, optional) – Length of slab the x-direction, by default 1.0

  • ly (float, optional) – Length of slab the x-direction, by default 0.5

  • lz (float, optional) – Length of slab the z-direction, by default 0.01

  • bx (float, optional) – Thickness of bath the x-direction, by default 0.0

  • by (float, optional) – Thickness of bath the x-direction, by default 0.0

  • bz (float, optional) – Thickness of bath the z-direction, by default 0.1

  • dx (float, optional) – Element size, by default 0.001

Returns:

A Geometry with the mesh, markers, markers functions and fibers. Returns None if dolfin is not installed.

Return type:

Optional[Geometry]

Raises:

ImportError – If gmsh is not installed

dolfin_utils#

class cardiac_geometries.dolfin_utils.Geometry(mesh, markers, marker_functions)[source]#
marker_functions: MarkerFunctions#

Alias for field number 2

markers: Dict[str, Tuple[int, int]]#

Alias for field number 1

mesh: Mesh#

Alias for field number 0

class cardiac_geometries.dolfin_utils.MarkerFunctions(vfun, efun, ffun, cfun)[source]#
cfun: MeshFunction#

Alias for field number 3

efun: MeshFunction#

Alias for field number 1

ffun: MeshFunction#

Alias for field number 2

vfun: MeshFunction#

Alias for field number 0

cardiac_geometries.dolfin_utils.mark_cell_function(fun, mesh, foc, regions)[source]#

Iterates over the mesh and stores the region number in a meshfunction

geometry#

class cardiac_geometries.geometry.FileNames(value)[source]#

An enumeration.

class cardiac_geometries.geometry.H5Path(h5group, fname, mesh_key, is_dolfin, is_mesh, is_meshfunction, is_function, dim)[source]#
dim: int#

Alias for field number 7

fname: str#

Alias for field number 1

h5group: str#

Alias for field number 0

is_dolfin: bool#

Alias for field number 3

is_function: bool#

Alias for field number 6

is_mesh: bool#

Alias for field number 4

is_meshfunction: bool#

Alias for field number 5

mesh_key: str#

Alias for field number 2

class cardiac_geometries.geometry.H5Paths(value)[source]#

An enumeration.

class cardiac_geometries.geometry.MeshTypes(value)[source]#

An enumeration.

class cardiac_geometries.geometry.Microstructure(f0, s0, n0)[source]#
f0: Function#

Alias for field number 0

n0: Function#

Alias for field number 2

s0: Function#

Alias for field number 1

utils#

viz#

cardiac_geometries.viz.dolfin_to_hd5(obj: Function, h5name, time='', name=None)[source]#

Save object to and HDF file.

Parameters:

  • obj (dolfin.Function) – The object you want to save

  • name (str) – Name of the object

  • h5group (str) – The folder you want to save the object withing the HDF file. Default: ‘’