|License| |Stars| |Pyversions| |Version| |Downloads| |Code style: black| |Codacy Badge| |Codecov| |Build| |Docs| |DOI| |JOSS|
TOUGH <https://tough.lbl.gov/>__ (Transport Of Unsaturated Groundwater and Heat) is a general purpose numerical simulation software designed for fluid and heat flows of multiphase, multicomponent fluid mixtures in porous and fractured media developed at Lawrence Berkeley National Laboratory. It solves mass and energy balance equations that describe fluid and heat flow in multiphase and multicomponent systems. TOUGH handles all types of multiphase and multicomponent flow systems since the governing equations for fluid and heat flow have the same mathematical form. The nature and properties of fluid mixtures are described by thermophysical variables (e.g., density, viscosity, enthalpy) which are provided by an equation-of-state (EOS) module.
toughio is an open-source library that provides tools to facilitate pre- and post-processing for TOUGH using the latest Python standards. It aims to make setting up of a TOUGH simulation user-friendly by relying on existing well-established Python packages:
numpy <https://numpy.org/>__: vectorized calculation of N-dimensional arrays,meshio <https://github.com/nschloe/meshio>__: input/output for many mesh formats,pyvista <https://github.com/pyvista/pyvista>__: 3D plotting and mesh analysis through a streamlined interface for the Visualization Toolkit (VTK).Note that the results of a TOUGH simulation are sensitive to the quality of the mesh (ideally, it should satisfy the orthogonality condition). A mesh that contains too many ill-shaped cells can potentially lead to unexpected results although the simulation converged successfully. toughio does not verify the quality of the mesh which is left to the discretion of the user.
.. figure:: https://raw.githubusercontent.com/keurfonluu/toughio/master/.github/sample.gif :alt: sample-co2 :width: 50% :align: center
Simulation of CO\ :sub:2\ leakage along a fault. Mesh generated with Gmsh and animation exported by PyVista.
Meshing:
Abaqus <https://www.3ds.com/products-services/simulia/products/abaqus/>, FLAC3D <https://www.itascacg.com/software/flac3d>, Gmsh <http://gmsh.info/>, LaGriT <https://meshing.lanl.gov/>),conformity <https://www.quora.com/What-is-non-conformal-mesh-in-CFD>__ (and optionally write initial condition file INCON).Pre-processing:
toughio.Mesh,JSON <http://json.org/>__\ able dictionary,Post-processing:
pyvista <https://github.com/pyvista/pyvista>__ or export the results to another format supported by meshio <https://github.com/nschloe/meshio>__ (e.g., VTK, Tecplot...),The recommended way to install toughio and all its dependencies is through the Python Package Index:
.. code:: bash
pip install toughio[full] --user
Otherwise, clone and extract the package, then run from the package location:
.. code:: bash
pip install .[full] --user
To test the integrity of the installed package, check out this repository and run:
.. code:: bash
git lfs pull pytest
Refer to the online documentation <https://keurfonluu.github.io/toughio//>__ for detailed description of the API and examples.
Alternatively, the documentation can be built using Sphinx <https://www.sphinx-doc.org/en/master/>__:
.. code:: bash
pip install -r doc/requirements.txt sphinx-build -b html doc/source doc/build
Note that some sample files are stored with LFS, so you may have to run the following command beforehand:
.. code:: bash
git lfs pull
In Python, to read a mesh and write the corresponding TOUGH MESH file (without any pre-processing), simply do
.. code:: python
import toughio
mesh = toughio.read_mesh( filename, file_format="flac3d", # Optional, inferred from file extension otherwise ) mesh.write_tough() # Write MESH file
Parameters of a TOUGH simulation can be defined as a dictionary with specific keywords following the JSON standard, for instance
.. code:: python
parameters = { "title": "Sample title", "eos": "eco2n", "isothermal": False, "default": { # Default rock properties "density": 2600.0, "porosity": 0.1, # "permeability", "conductivity", "specific_heat"... }, "rocks": { "shale": { # To overwrite default rock properties "capillarity": { "id": 1, "parameters": [0.0, 0.0, 1.0], }, # same keywords as in "default" }, # other materials }, "options": { "n_cycle": 100, "t_max": 3.0 * 365.25 * 24.0 * 3600.0, # "t_ini", "t_steps", "t_step_max", "gravity", "eps1", "eps2"... }, # "extra_options", "selections", "solver", "generators"... } toughio.write_input("INFILE", parameters)
TOUGH simulation output can also be imported into Python as a list of namedtuple (type, format, time, labels, data)
.. code:: python
output = toughio.read_output(filename)
toughio is mainly intended to be used as a Python scripting library for TOUGH. Nevertheless, several utility command line scripts are available for users who are not familiar with Python. From a console or terminal, the user can execute the following scripts:
toughio-co2tab: copy file CO2TAB to the target directory,toughio-export: export TOUGH simulation results to a file for visualization (VTK, VTU, Tecplot or XDMF),toughio-extract: extract results from TOUGH main output file and reformat as a TOUGH3 element or connection output file (mostly useful for TOUGH2 output before calling toughio-export),toughio-merge: merge input file, GENER and/or MESH and/or INCON into a single file,toughio-save2incon: convert a SAVE file to an INCON file (mostly useful to automatically restart a simulation and reset the counters).Please refer to the Contributing Guidelines <https://github.com/keurfonluu/toughio/blob/master/CONTRIBUTING.rst>__ to see how you can help. This project is released with a Code of Conduct <https://github.com/keurfonluu/toughio/blob/master/CODE_OF_CONDUCT.rst>__ which you agree to abide by when contributing.
toughio Copyright (c) 2022, The Regents of the University of California, through Lawrence Berkeley National Laboratory (subject to receipt of any required approvals from the U.S. Dept. of Energy). All rights reserved.
If you have questions about your rights to use or distribute this software, please contact Berkeley Lab's Intellectual Property Office at IPO@lbl.gov <mailto:IPO@lbl.gov>__.
This Software was developed under funding from the U.S. Department of Energy and the U.S. Government consequently retains certain rights. As such, the U.S. Government has been granted for itself and others acting on its behalf a paid-up, nonexclusive, irrevocable, worldwide license in the Software to reproduce, distribute copies to the public, prepare derivative works, and perform publicly and display publicly, and to permit others to do so.
.. |License| image:: https://img.shields.io/badge/license-BSD--3--Clause-green :target: https://github.com/keurfonluu/toughio/blob/master/LICENSE
.. |Stars| image:: https://img.shields.io/github/stars/keurfonluu/toughio?style=flat&logo=github :target: https://github.com/keurfonluu/toughio
.. |Pyversions| image:: https://img.shields.io/pypi/pyversions/toughio.svg?style=flat :target: https://pypi.org/pypi/toughio/
.. |Version| image:: https://img.shields.io/pypi/v/toughio.svg?style=flat :target: https://pypi.org/project/toughio
.. |Downloads| image:: https://pepy.tech/badge/toughio :target: https://pepy.tech/project/toughio
.. |Code style: black| image:: https://img.shields.io/badge/code%20style-black-000000.svg?style=flat :target: https://github.com/psf/black
.. |Codacy Badge| image:: https://img.shields.io/codacy/grade/037f16f4e7544afbb1b99bf0d66df4a6.svg?style=flat :target: https://www.codacy.com/manual/keurfonluu/toughio?utm_source=github.com&utm_medium=referral&utm_content=keurfonluu/toughio&utm_campaign=Badge_Grade
.. |Codecov| image:: https://img.shields.io/codecov/c/github/keurfonluu/toughio.svg?style=flat :target: https://codecov.io/gh/keurfonluu/toughio
.. |DOI| image:: https://zenodo.org/badge/DOI/10.5281/zenodo.3961278.svg?style=flat :target: https://doi.org/10.5281/zenodo.3961278
.. |Build| image:: https://img.shields.io/github/actions/workflow/status/keurfonluu/toughio/ci.yml :target: https://github.com/keurfonluu/toughio
.. |Docs| image:: https://img.shields.io/github/actions/workflow/status/keurfonluu/toughio/doc.yml?label=docs :target: https://keurfonluu.github.io/toughio/
.. |JOSS| image:: https://joss.theoj.org/papers/10.21105/joss.02412/status.svg :target: https://doi.org/10.21105/joss.02412
FAQs
Pre- and post-processing Python library for TOUGH
We found that toughio demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
PyPI confirms no security flaws were exploited in the Ultralytics supply chain attack and highlights improvements for safer package publishing.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.