Welcome

Bvpy is a python library, based on FEniCS and GMSH, to easily implement and study numerically Boundary Value Problems (BVPs) as well as Initial Boundary Value Problems (IBVPs) through the Finite Element Method (FEM).

Initially built up in the context of developmental biology and morphomechanics, Bvpy proposes an intuitive API as close as possible to the formal definition of BVPs. Its purpose is to enable users to quickly and efficiently estimate the behavior of a wide variety of fields (scalars, vectors, tensors) on biologically relevant structures (Riemannian and non-Rieamannian manifolds), inspired by biophysical and biochemical processes (morphogene patterning, active matter mechanics, diffusion-reaction processes, active transports…).

Despite this biological motivation, the Bvpy library has been implemented in an agnostic manner that makes it suitable for many other scientific context.

Installation

You will need conda in order to install bvpy. If you don’t have conda installed, you can download it here.

To install bvpy using conda package manager, follow these steps:

Open a terminal or Conda environment prompt.

Choose one of the following installation methods:

Create a New Environment (recommended):

conda create -n bvpy -c mosaic -c conda-forge bvpy
conda activate bvpy

Install into an Existing Environment:

conda activate <your-environment-name>
conda install -c mosaic -c conda-forge bvpy

Verify the bvpy installation:

python -c "from bvpy.utils.examples import cantilever_beam; cantilever_beam()"

This should produce a Pyvista Plotter showing the displacement field of the cantilever beam. If you see the correctly rendered visualization, the installation and dependencies of bvpy are working as expected.

Note: Replace <your-environment-name> with the name of your existing environment.

To install bvpy using Docker, follow these steps:

Pull the Docker image:
```
docker pull registry.gitlab.inria.fr/mosaic/bvpy:<TAG>
```
Replace <TAG> with the desired version of bvpy. You can find all available versions on the repository.
Run the Docker container and launch Jupyter Notebook:
```
docker run -it -p 8888:8888 registry.gitlab.inria.fr/mosaic/bvpy:<TAG>
jupyter notebook --ip 0.0.0.0 --no-browser --allow-root --port 8888
```
Use the URL displayed in the terminal to open the Jupyter Notebook in your browser for running tutorials.

If you want to install bvpy from its source code (e.g., for development purposes or using the latest version), use the following steps:

Clone the Repository:

git clone https://gitlab.inria.fr/mosaic/bvpy.git
cd bvpy

Create a Development Environment:

Use the provided conda environment file to create a new development environment:

conda env create --file conda/env.yaml -n bvpy-dev
conda activate bvpy-dev

Install bvpy in Editable Mode:

Install the repository in editable mode (using pip) to allow changes to the source code to take effect immediately:

python -m pip install -e .

Verify the bvpy installation:

python -c "from bvpy.utils.examples import cantilever_beam; cantilever_beam()"

Optional: Run Tests

If you installed bvpy from sources, install pytest and pytest-cov inside your environment:
python -m pip install -e ".[test]"
Then, run the tests from the root of the project directory to ensure that everything works correctly:
pytest -v --cov=bvpy test/

Tutorials

We’ve prepared a series of Tutorials that will help you understand and use bvpy effectively:

Explore the tutorials online: Tutorials
Download all tutorials as a ZIP file with the associated data: tutorials.zip

Note: To replay the notebooks, ensure that you have the notebook` package installed in your <your-bvpy-env> environment. You can install it using the following command:

conda install -n <your-bvpy-env> notebook

Support

If you encounter an error or need help, please raise an issue.

Contributing

Bvpy is a is a collaborative project and contributions are welcome. If you want to contribute, please contact the coordinator prior to any merge request and check the gitlab merge request guidelines if needed.

Citation

If you are using Bvpy in a published work, please use this bibtex entry as reference:

@article{Gacon2021,
doi = {10.21105/joss.02831},
url = {https://doi.org/10.21105/joss.02831},
year = {2021},
publisher = {The Open Journal},
volume = {6},
number = {59},
pages = {2831},
author = {Florian Gacon and Christophe Godin and Olivier Ali},
title = {BVPy: A FEniCS-based Python package to ease the expression and study of boundary value problems in Biology.},
journal = {Journal of Open Source Software}}