{"id":16911473,"url":"https://github.com/gerlero/porousmicrotransport","last_synced_at":"2025-10-19T03:40:22.711Z","repository":{"id":61984237,"uuid":"504245333","full_name":"gerlero/porousMicroTransport","owner":"gerlero","description":"OpenFOAM solvers for flow and transport in porous media in paper-based microfluidics","archived":false,"fork":false,"pushed_at":"2025-01-12T22:18:50.000Z","size":4699,"stargazers_count":18,"open_issues_count":2,"forks_count":2,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-03-18T10:38:04.854Z","etag":null,"topics":["lab-on-a-chip","microfluidics","openfoam","paper-based","porous-media"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gerlero.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-06-16T17:24:02.000Z","updated_at":"2025-01-17T12:39:43.000Z","dependencies_parsed_at":"2023-12-30T16:26:56.369Z","dependency_job_id":"d25ffef7-a12b-49ee-a78d-9a494c6156a7","html_url":"https://github.com/gerlero/porousMicroTransport","commit_stats":{"total_commits":248,"total_committers":4,"mean_commits":62.0,"dds":"0.11290322580645162","last_synced_commit":"0271feb58dc2df9c9bf7e800ec30a4be85f245b2"},"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gerlero%2FporousMicroTransport","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gerlero%2FporousMicroTransport/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gerlero%2FporousMicroTransport/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gerlero%2FporousMicroTransport/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gerlero","download_url":"https://codeload.github.com/gerlero/porousMicroTransport/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244943993,"owners_count":20536290,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["lab-on-a-chip","microfluidics","openfoam","paper-based","porous-media"],"created_at":"2024-10-13T19:06:08.234Z","updated_at":"2025-10-19T03:40:22.705Z","avatar_url":"https://github.com/gerlero.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# [\u003cimg alt=\"porousMicroTransport logo\" src=\"https://raw.githubusercontent.com/gerlero/porousMicroTransport/main/logo.png\" width=300\u003e\u003c/img\u003e](https://github.com/gerlero/porousMicroTransport)\n\n[![CI](https://github.com/gerlero/porousMicroTransport/actions/workflows/ci.yml/badge.svg)](https://github.com/gerlero/porousMicroTransport/actions/workflows/ci.yml)\n[![OpenFOAM versions](https://img.shields.io/badge/openfoam-v2112%20%7C%20v2206%20%7C%20v2212%20%7C%20v2306%20%7C%20v2312%20%7C%20v2406%20%7C%20v2412%20%7C%20v2506-informational)](https://www.openfoam.com)\n[![Docker](https://github.com/gerlero/porousMicroTransport/actions/workflows/docker.yml/badge.svg)](https://github.com/gerlero/porousMicroTransport/actions/workflows/docker.yml)\n[![Docker image](https://img.shields.io/badge/docker%20image-microfluidica%2Fporousmicrotransport-0085a0)](https://hub.docker.com/r/microfluidica/porousmicrotransport/)\n[![Docker Pulls](https://img.shields.io/docker/pulls/microfluidica/porousmicrotransport)](https://hub.docker.com/r/microfluidica/porousmicrotransport/)\n\n**porousMicroTransport**[^porousMicroTransport] is a set of additional solvers and related libraries for OpenFOAM developed for the purposes of simulating flow and transport in porous media, with an emphasis on paper-based microfluidics\n\n\n## Installation\n\n**porousMicroTransport** requires [OpenFOAM](https://www.openfoam.com), as distributed by OpenCFD (openfoam.com). Compatible OpenFOAM versions are v2112, v2206, v2212, v2306, v2312, v2406, v2412 and v2506.\n\n_Versions produced by the OpenFOAM Foundation (openfoam.org) (e.g. OpenFOAM 11, OpenFOAM 12) are not compatible. macOS users may want to consider [OpenFOAM.app](https://github.com/gerlero/openfoam-app)._\n\n### With [`styro`](https://github.com/gerlero/styro)\n\n**porousMicroTransport** can be installed with the [`styro`](https://github.com/gerlero/styro) package manager:\n\n```sh\nstyro install porousmicrotransport\n```\n\n### Install from source\n\n#### Optional: [`reagency`](https://github.com/gerlero/reagency)\n\n**porousMicroTransport** can be used with the optional [`reagency`](https://github.com/gerlero/reagency) library for reaction modeling. To install **porousMicroTransport** with `reagency`, clone the `reagency` repository alongside `porousMicroTransport`, and install the former first:\n\n```sh\ngit clone https://github.com/gerlero/reagency.git\nreagency/Allwmake -j\n```\n\n#### Download\n\n[Download the source code](https://github.com/gerlero/porousMicroTransport/archive/refs/heads/main.zip) of **porousMicroTransport**, or clone this repository with Git:\n\n```sh\ngit clone https://github.com/gerlero/porousMicroTransport.git\n```\n\n#### Compile and install\n\nTo build and install **porousMicroTransport**, just invoke the top-level `Allwmake` script:\n\n```sh\ncd porousMicroTransport\n./Allwmake -j\n```\n\n_If necessary, activate/source the correct OpenFOAM environment before running `Allwmake`._\n\n#### Test\n\nOptionally, you can verify the installation of **porousMicroTransport** by running the included test suite (requires Python 3.7 or later):\n\n```sh\ntests/Alltest\n```\n\n### Docker image\n\nAlternatively, **porousMicroTransport** is also [available in the form of Docker images](https://hub.docker.com/r/microfluidica/porousmicrotransport/). These images include **porousMicroTransport** precompiled and ready to use. Assuming [Docker](https://www.docker.com) is installed, the following command will run the latest image and mount the current directory so that you can access the files inside:\n\n```sh\ndocker run --rm -it -v $PWD:/root -w /root microfluidica/porousmicrotransport\n```\n\nOr, if you use OpenFOAM's [`openfoam-docker` script](https://develop.openfoam.com/Development/openfoam/-/wikis/precompiled/docker) (which takes care of making the working directory available inside the container):\n\n```sh\nopenfoam-docker -image=microfluidica/porousmicrotransport\n```\n\nA slimmer image variant that does not include source code, development tools or tutorial cases is available as `microfluidica/porousmicrotransport:slim`.\n\nDocker images can also be used with other compatible containerization software, such as Podman and Singularity/Apptainer.\n\n\n## Solvers\n\n### `moistureDiffusivityFoam`\n\n**(Unsaturated) capillarity-driven flow in a porous medium**, governed by the moisture diffusivity equation[^Bear]:\n\n$$\\frac{\\partial\\theta}{\\partial t} - \\nabla\\cdot\\left[D\\nabla\\theta\\right] = 0$$\n\nwhere $\\theta$ is the moisture content and $D$ is a saturation-dependent diffusivity as defined by an unsaturated flow model.\n\n### `porousMicroTransportFoam`\n\n**Transport by steady flow of any number of species in a porous medium, with optional reactions between the species**. For each species (concentration $C$), the governing equation is:\n\n$$\\frac{\\partial R_d \\theta C}{\\partial t} + \\nabla\\cdot\\left[UC\\right] - \\nabla\\cdot\\left[\\theta D_{eff}\\nabla C\\right] = \\theta F$$\n\nwhere $F$ is a reaction term (see below), $R_d$ is defined as:\n\n$$R_d = 1 + \\frac{\\rho_s\\left(1 - \\varepsilon_\\textrm{tot}\\right)K_d}{\\theta}$$\n\nand $D_{eff}$ is defined as: \n\n$$D_{eff} = \\left(\\frac{D_M}{\\tau} + \\alpha_T|V|\\right)I + \\left(\\alpha_L - \\alpha_T\\right)\\frac{VV}{|V|}$$\n\nwith $I$ the identity tensor and $V$ the true velocity of the fluid ($=U/\\theta$).\n\n### `moistureDiffusivityTransportFoam`\n\n**Capillary flow + reactive transport in a porous medium**, coupling the moisture diffusivity equation for flow with the previous transport equation.\n\n\n## Case layout\n\nThe layout of **porousMicroTransport** cases follows many conventions of [**porousMultiphaseFoam**](https://github.com/phorgue/porousMultiphaseFoam), especially in field names and entries in the `transportProperties` dictionary. This allows for easy conversion of cases from **porousMultiphaseFoam** to **porousMicroTransport** (and to some extent, vice versa).\n\n### Common fields\n\nThese variable fields are defined in the time directories:\n\n* `theta`: moisture content (scalar). _Optional for `porousMicroTransportFoam`_\n\n* `U`: Darcy velocity (vector). _Optional for flow solvers_\n\n### Common porous medium properties\n\nDefined as scalar fields in `constant` or as dictionary entries in `transportProperties`:\n\n* `eps` or `thetamax`: effective porosity ($\\varepsilon$)\n\n* `K`: intrinsic permeability. _Flow solvers only_\n\n* `rs`: particle density ($\\rho_s$). _Transport solvers only_\n\n* `epsTotal`: total porosity ($\\varepsilon_\\textrm{tot}$). _Transport solvers only_\n\n* `tau`: diffusive tortuosity ($\\tau$). _Transport solvers only_\n\n* `alphaT`: transverse dispersion coefficient ($\\alpha_T$). _Transport solvers only_\n\n* `alphaL`: longitudinal dispersion coefficient ($\\alpha_L$). _Transport solvers only_\n\n### Phase properties\n\n_Flow solvers only._\n\nSet these in a `phase.theta` subdictionary in `transportProperties`:\n\n* `rho`: density\n\n* `mu`: dynamic viscosity\n\n### Moisture content options\n\n_Flow solvers only._\n\nDefined as scalar fields in `constant` or as dictionary entries in `transportProperties`:\n\n* `thetamin`: minimum (a.k.a. residual) moisture content\n\n* `thetamax`: maximum moisture content (usually equal to the porosity)\n\n### Unsaturated flow models\n\n_Flow solvers only._\n\nSupported models of unsaturated flow are:\n\n* `BrooksAndCorey`: Brooks and Corey[^BrooksAndCorey] model\n\n    * In coefficient dictionary `BrooksAndCoreyCoeffs`: `pc0`, `alpha`, `n`, `l` (optional)\n\n* `VanGenuchten`: Van Genuchten[^VanGenuchten] model\n\n    * In coefficient dictionary `VanGenuchtenCoeffs`: `pc0`, `m` or `n`, `l` (optional)\n\n* `LETxs`: LETx + LETs model[^LET]\n\n    * In coefficient dictionary `LETCoeffs`: `pc0`, `Lw`, `Ew`, `Tw`, `Ls`, `Es`, `Ts`\n\n* `LETd`: LETd[^Validity] model\n\n    * In coefficient dictionary `LETCoeffs`: `pc0`, `L`, `E`, `T`\n\nTo choose a model for your simulation, set the `unsaturatedFlowModel` entry in `transportProperties`. Then set the model-specific parameters in the corresponding coefficient subdictionary.\n\n### Special boundary conditions for flow\n\n_Flow solvers only._\n\nBesides the standard OpenFOAM boundary conditions (e.g. `zeroGradient`, `fixedValue`), the solvers support these additional boundary conditions for `theta`:\n\n* `darcyGradPressure`: follow the boundary condition set for velocity (same as [`darcyGradPressure` in **porousMultiphaseFoam**](https://porousmultiphasefoam.readthedocs.io/en/latest/darcyGradPressure.html)).\n\n* `exhaustible`: models an inlet reservoir with a fixed volume of fluid that is gradually depleted as fluid flows into the domain. A `remaining` entry is required (volume remaining in the reservoir).\n\n### Transported species\n\n_Transport solvers only._\n\nA `species` list in `transportProperties` contains the names of all transported species.\n\nEach species must also define its own scalar concentration field (named the same as the species).\n\nFor each species, the following entries can be set in `transportProperties`:\n\n* `Dm`: molecular diffusivity ($D_M$)\n\n* `Kd`: partitioning coefficient ($K_d$)\n\n### Reactions\n\n_Transport solvers only._\n\nReactions are defined in a `reactions` subdictionary in `transportProperties`. The `reactions` dictionary contains a list of subdictionaries, each of which defines a single reaction. A reaction can have an arbitrary name and should contain the following entries:\n\n* `reaction`: reaction equation. E.g. `\"A^2 + B = 2C + D\"`, where `A`, `B`, `C` and `D` are names of defined species\n\n* `kf`: forward rate constant\n\n* `kr`: optional reverse rate constant (for reversible reactions)\n\n### Automatic timestep control\n\nTo enable automatic timestep adjustment, set `adjustTimeStep` to `yes` in `system/controlDict`. Then, configure it as follows:\n\n* For flow, set a `tolerance` value inside a `Picard` dictionary in `system/fvSolution`\n\n* For transport, add a `maxDeltaC` and/or `relMaxDeltaC` entry in `system/controlDict`\n\n\n## Tutorials\n\nSample cases are available in the [`tutorials` directory](tutorials).\n\n\n## Citation\n\nIf you use **porousMicroTransport** in your work, please cite our paper:\n\n\u003e Gerlero, G. S., Guerenstein, Z. I., Franck, N., Berli, C. L. A., \u0026 Kler, P. A. (2024). Comprehensive numerical prototyping of paper-based microfluidic devices using open-source tools. _Talanta Open_, _10_, 100350. https://doi.org/10.1016/j.talo.2024.100350\n\n\u003cdetails\u003e\n\u003csummary\u003e📋 BibTeX\u003c/summary\u003e\n\n```bibtex\n@article{porousMicroTransport,\n    author = {Gerlero, Gabriel S. and Guerenstein, Zahar I. and Franck, Nicolás and Berli, Claudio L. A. and Kler, Pablo A.},\n    doi = {10.1016/j.talo.2024.100350},\n    journal = {Talanta Open},\n    pages = {100350},\n    title = {Comprehensive numerical prototyping of paper-based microfluidic devices using open-source tools},\n    volume = {10},\n    year = {2024}\n}\n```\n\n\u003c/details\u003e\n\n\n## Related projects\n\n* [**porousMultiphaseFoam**](https://github.com/phorgue/porousMultiphaseFoam)[^porousMultiphaseFoam]: toolbox for OpenFOAM for modeling multiphase flow and transport. **porousMicroTransport** is mostly compatible with **porousMultiphaseFoam** in terms of case definitions, and can be installed alongside it.\n\n* [**electroMicroTransport**](https://gitlab.com/santiagomarquezd/electroMicroTransport)[^electroMicroTransport]: toolbox for OpenFOAM dedicated to electromigrative separations. It includes support for modeling separations in paper-based media, and can also be installed alongside **porousMicroTransport**.\n\n[^porousMicroTransport]: Gerlero, G. S., Guerenstein, Z. I., Franck, N., Berli, C. L. A., \u0026 Kler, P. A. (2024). Comprehensive numerical prototyping of paper-based microfluidic devices using open-source tools. _Talanta Open_, _10_, 100350. https://doi.org/10.1016/j.talo.2024.100350\n\n[^Bear]: Bear, J., \u0026 Cheng, A. H. D. (2010). _Modeling groundwater flow and contaminant transport_ (Vol. 23, p. 834). Dordrecht: Springer. https://doi.org/10.1007/978-1-4020-6682-5\n\n[^porousMultiphaseFoam]: Horgue, P., Renard, F., Gerlero, G. S., Guibert, R., \u0026 Debenest, G. (2022). porousMultiphaseFoam v2107: An open-source tool for modeling saturated/unsaturated water flows and solute transfers at watershed scale. _Computer Physics Communications_, _273_, 108278. https://doi.org/10.1016/j.cpc.2021.108278\n\n[^electroMicroTransport]: Gerlero, G. S., Damián, S. M., \u0026 Kler, P. A. (2021). electroMicroTransport v2107: Open-source toolbox for paper-based electromigrative separations. _Computer Physics Communications_, _269_, 108143. https://doi.org/10.1016/j.cpc.2021.108143\n\n[^BrooksAndCorey]: Brooks, R., \u0026 Corey, T. (1964). Hydraulic properties of porous media. _Hydrology Papers Colorado State University_. https://mountainscholar.org/bitstream/handle/10217/61288/HydrologyPapers_n3.pdf\n\n[^VanGenuchten]: Van Genuchten, M. T. (1980). A closed‐form equation for predicting the hydraulic conductivity of unsaturated soils. _Soil Science Society of America Journal_, _44_(5), 892-898. https://doi.org/10.2136/sssaj1980.03615995004400050002x\n\n[^LET]: Lomeland, F. (2018). Overview of the LET family of versatile correlations for flow functions. In: _Proceedings of the International Symposium of Core Analysts_, SCA2018-056 http://www.jgmaas.com/SCA/2018/SCA2018-056.pdf\n\n[^Validity]: Gerlero, G. S., Valdez, A. R., Urteaga, R., \u0026 Kler, P. A. (2022). Validity of capillary imbibition models in paper-based microfluidic applications. _Transport in Porous Media_, _141_(2), 359-378. https://doi.org/10.1007/s11242-021-01724-w\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgerlero%2Fporousmicrotransport","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgerlero%2Fporousmicrotransport","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgerlero%2Fporousmicrotransport/lists"}