Metadata-Version: 2.4
Name: fenicsx-ldrb
Version: 0.2.0
Summary: Laplace-Dirichlet Rule-based algorithm for assigning myocardial fiber orientations.
Author-email: Henrik Finsberg <henriknf@simula.no>
License: MIT
Project-URL: Homepage, https://finsberg.github.io/fenicsx-ldrb
Project-URL: Documentation, https://finsberg.github.io/fenicsx-ldrb
Project-URL: Source, https://github.com/finsberg/fenicsx-ldrb
Project-URL: Tracker, https://github.com/finsberg/fenicsx-ldrb/issues
Keywords: cardiac,electrophysiology
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: numba
Requires-Dist: io4dolfinx
Requires-Dist: scipy
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Requires-Dist: cardiac-geometriesx; extra == "test"
Requires-Dist: scifem; extra == "test"
Requires-Dist: ukb-atlas; extra == "test"
Requires-Dist: pyvista; extra == "test"
Provides-Extra: dev
Requires-Dist: pdbpp; extra == "dev"
Requires-Dist: ipython; extra == "dev"
Requires-Dist: bump2version; extra == "dev"
Requires-Dist: pre-commit; extra == "dev"
Provides-Extra: pypi
Requires-Dist: twine; extra == "pypi"
Requires-Dist: build; extra == "pypi"
Provides-Extra: demos
Requires-Dist: cardiac-geometriesx; extra == "demos"
Provides-Extra: docs
Requires-Dist: jupyter-book<2.0; extra == "docs"
Requires-Dist: jupytext; extra == "docs"
Requires-Dist: pyvista[all]; extra == "docs"
Requires-Dist: fenicsx-ldrb[demos]; extra == "docs"
Provides-Extra: all
Requires-Dist: fenicsx-ldrb[test]; extra == "all"
Requires-Dist: fenicsx-ldrb[docs]; extra == "all"
Requires-Dist: fenicsx-ldrb[pypi]; extra == "all"
Requires-Dist: fenicsx-ldrb[dev]; extra == "all"
Requires-Dist: fenicsx-ldrb[demos]; extra == "all"
Dynamic: license-file

![_](https://raw.githubusercontent.com/finsberg/fenicsx-ldrb/main/docs/_static/fenicsx-ldrb-logo.png)

[![Create and publish a Docker image](https://github.com/finsberg/fenicsx-ldrb/actions/workflows/docker-image.yml/badge.svg)](https://github.com/finsberg/fenicsx-ldrb/actions/workflows/docker-image.yml)
[![pre-commit](https://github.com/finsberg/fenicsx-ldrb/actions/workflows/pre-commit.yml/badge.svg)](https://github.com/finsberg/fenicsx-ldrb/actions/workflows/pre-commit.yml)
[![Test package](https://github.com/finsberg/fenicsx-ldrb/actions/workflows/main.yml/badge.svg)](https://github.com/finsberg/fenicsx-ldrb/actions/workflows/main.yml)
[![PyPI version](https://badge.fury.io/py/fenicsx-ldrb.svg)](https://badge.fury.io/py/fenicsx-ldrb)
![GitHub License](https://img.shields.io/github/license/finsberg/fenicsx-ldrb)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)

# Laplace-Dirichlet Rule-Based (LDRB) algorithm for assigning myocardial fiber orientations


A software for assigning myocardial fiber orientations based on the Laplace Dirichlet Ruled-Based algorithm based on FEniCSx.

> Bayer, J.D., Blake, R.C., Plank, G. and Trayanova, N.A., 2012.
> A novel rule-based algorithm for assigning myocardial fiber orientation
>to computational heart models. Annals of biomedical engineering, 40(10),
pp.2243-2254.(https://www.ncbi.nlm.nih.gov/pmc/articles/PMC3518842/)


## Getting started
For example if you have a bi-ventricular geometry (e.g from [`cardiac-geometries`](https://github.com/ComputationalPhysiology/cardiac-geometriesx)), you can generate fibers as follows
```python
import cardiac_geometries
import ldrb
import dolfinx

# Generate an idealized BiV geometry
geo = cardiac_geometries.mesh.biv_ellipsoid(outdir=geodir)
# Generate fibers with 60/-60 fibers angles on the endo- and epicardium
system = ldrb.dolfinx_ldrb(
    mesh=geo.mesh,
    ffun=geo.ffun,
    markers=geo.markers,
    alpha_endo_lv=60,
    alpha_epi_lv=-60,
    beta_endo_lv=0,
    beta_epi_lv=0,
    fiber_space="P_2",
)
# Visualize fibers in Paraview
with dolfinx.io.VTXWriter(
    geo.mesh.comm,
    outdir / f"microstructure-viz.bp",
    [system.f0, system.s0, system.n0],
    engine="BP4",
) as vtx:
    vtx.write(0.0)
```
If you now open the file `microstructure-viz.bp` in Paraview (using the ADIOS2VTXReader), select Glyph and choose `f0` as orientation array you can see the fiber orientations similar to the following figure (here I have also added a Calculator to compute the fiber angle)
![_](docs/_static/idealized_biv.png)

Note that you can achieve the the same results using the command line interface
```
ldrb mesh.xdmf --markers-file markers.json --fiber-space P_2 --alpha-endo-lv 60 --alpha-epi-lv -60 --beta-endo-lv 0 --beta-epi-lv 0
```
Note that if you don't specify a different angle for the RV or Septum, then the same angle as the LV will be used.

### Geometries with outflow tracts
For biventricular geometries that include the outflow tracts and the four valves, such as the [UK Biobank atlas](https://github.com/ComputationalPhysiology/ukb-atlas), you can use the rule-based method of [Doste et al. (2019)](https://doi.org/10.1002/cnm.3185). It defines the longitudinal direction in each ventricle as a blend of the directions from the apex to the inflow and to the outflow valve, and uses separate angles in the LV, RV and outflow tracts
```python
system = ldrb.dolfinx_doste(
    mesh=geo.mesh,
    ffun=geo.ffun,
    markers={"lv": 1, "rv": 2, "epi": 3, "mv": 4, "av": 5, "tv": 6, "pv": 7},
    fiber_space="P_2",
)
```
The apex of each ventricle is the point on its endocardium farthest from the inflow valve, unless you pass its coordinates with `apex_lv` and `apex_rv`. The default angles are the ones from the paper, see `ldrb.doste` for the convention.

## Installation
## pip
Note that you can install the package with `pip`, but then you need to install FEniCSx separatly, see [download](https://fenicsproject.org/download/)
```
python3 -m pip install fenicsx-ldrb
```

## conda
The package can also be installed with conda, i.e
```
conda install -c conda-forge fenicsx-ldrb
```

## Docker
To pull the latest docker image you can do
```
docker pull ghcr.io/finsberg/fenicsx-ldrb:main
```
or choose a specific version e.g
```
docker pull ghcr.io/finsberg/fenicsx-ldrb:v0.1.4
```
Note that you can also run the cli directly using docker e.g
```
docker run --rm -v $PWD:/home/shared -w /home/shared -it ghcr.io/finsberg/fenicsx-ldrb ldrb --help
```

# Documentation
See https://finsberg.github.io/fenicsx-ldrb


# License
MIT

# Contributors
Henrik Finsberg (henriknf@simula.no)
