{ "info": { "author": "Gabriel S. Gerlero", "author_email": "", "bugtrack_url": null, "classifiers": [ "Development Status :: 4 - Beta", "Intended Audience :: Science/Research", "License :: OSI Approved :: BSD License", "Operating System :: OS Independent", "Programming Language :: Python", "Programming Language :: Python :: 2.7", "Programming Language :: Python :: 3", "Programming Language :: Python :: 3.5", "Programming Language :: Python :: 3.6", "Programming Language :: Python :: 3.7", "Topic :: Scientific/Engineering :: Physics", "Topic :: Software Development :: Libraries" ], "description": "# \"Fronts\"\n\nFronts is a Python numerical library for solving one-dimensional transient nonlinear diffusion problems in semi-infinite domains.\n\nFronts finds solutions to initial-boundary value problems of the form:\n\n> **General problem**\n> \n> Given a scalar-valued positive function _D_, scalars _Si_, _Sb_ and _ob_, and coordinate unit vector **\u0213**, find a function _S_ of _r_ and _t_ such that:\n> \n> \"General\n\nFronts works by transforming the governing nonlinear partial differential equation (PDE) into a more manageable (but still nonlinear) ordinary differential equation (ODE), using a technique known as the [Boltzmann transformation](https://en.wikipedia.org/wiki/Boltzmann\u2013Matano_analysis), which it then solves with a combination of numerical ODE solvers and specialized logic.\n\nFor this class of problems, you will find that Fronts can be easier to use, faster, and more robust than the classical numerical PDE solvers you would otherwise have to use.\n\nIn some instances, Fronts can also solve the inverse problem of finding _D_ when _S_ is given. And, if you need something a little different, Fronts gives you easy access to the underlying ODE so that you can use your own solving algorithm or boundary condition (which you are then welcome to contribute to the project!).\n\nFronts is open source and works great with [NumPy](https://numpy.org) and [SciPy](https://www.scipy.org/scipylib/index.html). \n\n\n## Common problem\n\nIf the general problem supported by Fronts looks too complicated, note that in the common case where **\u0213** is a Cartesian unit vector and the boundary is fixed at _r_=0, the problem can be reduced to what we call the common problem:\n\n> **Common problem**\n> \n> Given a scalar-valued positive function _D_, and scalars _Si_ and _Sb_, find a function _S_ of _r_ and _t_ such that:\n>\n> \"Common\n\n\nThe main solver function ``solve()`` will assume that you want to work with this common problem unless you explicitly provide the optional `radial` and `ob` parameters. \n\n\n## Uses\n\nProblems supported by Fronts appear in many areas of physics. For instance, if we take _S_ as the saturation or moisture content and _D_ as the moisture diffusivity, the above PDE translates into what is known as the moisture diffusivity equation, which is a special case of the [Richards equation](https://en.wikipedia.org/wiki/Richards_equation) that models fluid flow in unsaturated porous media.\n\nOf particular interest to the creators of Fronts is the fact that the moisture diffusivity equation as supported by Fronts can directly describe the phenomenon known as lateral flow in the field of paper-based microfluidics. In fact, the name \"Fronts\" is a reference to the wetting fronts that appear under these conditions, the study of which motivated the creation of this library.\n\nOther problems of this class appear in the study of diffusion of solutions in polymer matrices as well as diffusion problems in solids (e.g. annealing problems in metallurgy). \n\nAs mentioned before, if your problem is supported, you can expect Fronts to be easier to use, faster, and more robust than other tools. Try it out!\n\n## Installation\n\n### Prerequisites\n\n* **Python**. Fronts works with all current (as of 2019) versions of Python: it runs on Python 3.5 and later as well as on the older Python 2.7. It has been tested on versions 3.7.4, 3.6.6, 3.5.7, and 2.7.16.\n\n* **pip**. Installation of Fronts requires the Python package manager [pip](https://pip.pypa.io/en/stable/) to be installed on your system.\n\n### Installation\n\nInstall Fronts by running the following command:\n\n```\n$ pip install fronts\n```\n\nThis will install the [most recent version of Fronts available on PyPI](https://pypi.org/project/fronts/).\n\n##### Optional: Matplotlib\n\nRunning the bundled examples requires the visualization library [Matplotlib](https://matplotlib.org). This library is not installed automatically with Fronts, so if you don't already have it, you may want to install it manually by running:\n\n```\n$ pip install matplotlib\n```\n\n\n## Documentation and features\n\nThe following is a complete list of the functions and classes that Fronts provides, with a short description of each. You will find the full details on each object in the [API documentation](https://fronts.readthedocs.io).\n\n### Solvers and solutions\n\n* [**```fronts.solve()```**](https://fronts.readthedocs.io/en/latest/stubs/fronts.solve.html) \u2014 meshless solver\n\n\t```solve``` solves any instance of the general problem.\tReturns a ```SemiInfiniteSolution```.\n\t\n* [**```fronts.solve_from_guess()```**](https://fronts.readthedocs.io/en/latest/stubs/fronts.solve_from_guess.html) \u2014 mesh-based solver\n\t\n\t```solve_from_guess``` works like ``solve`` but it uses a different procedure that starts from a guess of the solution on an initial mesh. It supports the same kind of problems than ```solve```. Although usually faster, ```solve_from_guess``` is significantly less robust than `solve`\u2014whether it converges will usually depend heavily on the problem, the initial mesh and the guess of the solution. It also returns a ```SemiInfiniteSolution``` on success.\n\n\n* [**```fronts.Solution```**](https://fronts.readthedocs.io/en/latest/stubs/fronts.Solution.html), [**```fronts.SemiInfiniteSolution```**](https://fronts.readthedocs.io/en/latest/stubs/fronts.SemiInfiniteSolution.html) \u2014 continuous solutions\n\n\t```Solution``` objects provide the continuous functions ```S```, ```dS_dr```, ```dS_dt``` and ```flux``` that build up the solution to a problem. The solvers in Fronts return a ```SemiInfiniteSolution``` (a subclass of ```Solution```) as part of their results. If you called ```ode``` and solved the ODE yourself, you can create a ```Solution``` or ```SemiInfiniteSolution``` by passing the solution to the ODE to the appropiate constructor.\n\t\n\tRecall that when solving the moisture diffusivity/horizonal Richards equation, the diffusive flux (which you can obtain by calling ```flux```) is equivalent to the wetting fluid's velocity. Accordingly, this enables the coupling of the results you get from Fronts (in terms of advective velocity) with more complex problems of solute transport.\n\n\n* [**```fronts.inverse()```**](https://fronts.readthedocs.io/en/latest/stubs/fronts.inverse.html) \u2014 solve the inverse problem\n\t\n\t```inverse``` solves the inverse problem of finding _D_ when _S_ is known. For instance, ```inverse``` can extract _D_ from experimental results. The returned _D_ function can be used in Fronts to solve other problems.\n\t\n\n### Boltzmann transformation and ODE\n\n* [**```fronts.o()```**](https://fronts.readthedocs.io/en/latest/stubs/fronts.o.html), [**```fronts.do_dr()```**](https://fronts.readthedocs.io/en/latest/stubs/fronts.do_dr.html), [**```fronts.do_dt()```**](https://fronts.readthedocs.io/en/latest/stubs/fronts.do_dt.html), [**```fronts.r()```**](https://fronts.readthedocs.io/en/latest/stubs/fronts.r.html), [**```fronts.t()```**](https://fronts.readthedocs.io/en/latest/stubs/fronts.t.html), [**```fronts.as_o()```**](https://fronts.readthedocs.io/en/latest/stubs/fronts.as_o.html) \u2014 Boltzmann transformation\n\n\tThese are convenience functions for working with the Boltzmann transformation.\n\n* [**```fronts.ode()```**](https://fronts.readthedocs.io/en/latest/stubs/fronts.ode.html) \u2014 access the ODE\n\n\tThe ```ode``` function transforms the PDE into its corresponding ODE using the Boltzmann transformation. ```ode``` returns _fun_ and _jac_ callables that are directly compatible with SciPy's solvers (i.e., those in the [```scipy.integrate```](https://docs.scipy.org/doc/scipy/reference/integrate.html) module). The solvers in Fronts actually use this function internally. You may call this function if you want to solve the ODE yourself instead of using Fronts' solvers, for example if you need to deal with a different boundary condition or want to use your own solving algorithm.\n\n### _D_ functions and ```fronts.D```\n\nMany of the functions in Fronts either take or return _D_ functions to work. _D_ functions have to be defined as follows:\n\n> ``D`` : _callable_\n> \n> Twice-differentiable function that maps the range of _S_ to positive values. It can be called as ``D(S)`` to evaluate it at `S`. It can also be called as ``D(S, derivatives)`` with `derivatives` equal to 1 or 2, in which case the first `derivatives` derivatives of the function evaluated at the same `S` are included (in order) as additional return values. While mathematically a scalar function, `D` operates in a vectorized fashion with the same semantics when `S` is a `numpy.ndarray`.\n \n\nWith the above definition you can easily write any functions you need to solve your particular problems. \n\nFronts also comes with a submodule ```fronts.D``` that lets you access some predefined functions:\n\n* [**```fronts.D.constant()```**](https://fronts.readthedocs.io/en/latest/stubs/fronts.D.constant.html) \u2014\u00a0create a constant function:\n\n\t\n\n* [**```fronts.D.power_law()```**](https://fronts.readthedocs.io/en/latest/stubs/fronts.D.power_law.html) \u2014 create a function of the form:\n\n\t\n\n* [**```fronts.D.van_genuchten()```**](https://fronts.readthedocs.io/en/latest/stubs/fronts.D.van_genuchten.html) \u2014 create a [Van Genuchten](https://doi.org/10.2136/sssaj1980.03615995004400050002x) moisture diffusivity function:\n\n\t\n\t\n\twhere _S_ is the saturation and _Se_ is defined as:\n\t\n\t\n\n\n* [**```fronts.D.richards()```**](https://fronts.readthedocs.io/en/latest/stubs/fronts.D.richards.html) \u2014\u00a0make a moisture diffusivity function from the hydraulic conductivity function _K_ and the capillary capacity function _C_ using the definition: \n\t\n\t\n\n\t\n## Examples\n\n### Introductory example\n\n_Plotting the solution in this example requires_ [Matplotlib](https://matplotlib.org)_._\n\nLet us solve the following initial-boundary value problem defined in a semi-infinite domain:\n\n> **Example problem**\n>\n> Find _S_ such that:\n>\n> \"Example\n\nBy comparing the example problem with the common problem introduced above, we see that the parameters are:\n\n\"Parameters\"\n\nIn this case it is not necessary to write the function `D` it ourselves. The function we need can be obtained from the ``fronts.D`` module:\n\n```python\nfrom fronts.D import power_law\nD = power_law(k=4)\n```\n\nWe are now ready to solve the problem with ``fronts.solve``. We simply pass it the parameters ``D``, ``Si`` and ``Sb``.\n\n```python\nfrom fronts import solve\nsolution = solve(D, Si=0.1, Sb=1)\n```\n\nThe call to ```fronts.solve``` completes within a second and we get back a ```SemiInfiniteSolution``` object, which holds the functions ```S```, ```dS_dr```, ```dS_dt```and ```flux```.\n\nWe can now plot _S_ for arbitrary _r_ and _t_. For example, with _r_ between 0 and 10 and _t_=60:\n\n```python\nimport matplotlib.pyplot as plt\nr = np.linspace(0, 10, 200)\nplt.plot(r, solution.S(r, t=60))\nplt.xlabel(\"r\")\nplt.ylabel(\"S\")\nplt.show()\n```\n\nThe plot will look like this:\n\n\"S\n\nFinally, let us plot the flux at _t_=60:\n\n```python\nplt.plot(r, solution.flux(r, t=60))\nplt.xlabel(\"r\")\nplt.ylabel(\"flux\")\nplt.show()\n```\n\n\"flux\n\n### More examples\n\nThe included examples can be found in the ``examples`` directory of this project. The directory contains the following files:\n\n\n* subdirectory **``powerlaw/``** \u2014 cases based on the introductory example presented above\n\t* **``solve.py``**: solve the case with `fronts.solve()`.\n\t* **``radial.py``**: solve a radial case (with a moving boundary) using `fronts.solve()`.\n\t* **``inverse.py``**: more examples of usage of `fronts.solve()` and of`fronts.inverse()`.\n\n* subdirectory **``1INFILTR/``** \u2014 the _1INFILTR_ test case from [Hydrus-1D](https://www.pc-progress.com/en/Default.aspx?hydrus-1d), in horizontal\n\t* **``solve.py``**: solve the case with `fronts.solve()`.\n\t* **``validation.py``**: results for the same case obtained using Hydrus for comparison.\n* subdirectory **``HF135/``**\u2014 lateral flow case in an HF135 nitrocellulose membrane (data from the [PhD work of J.R. Buser](http://hdl.handle.net/1773/38064))\n\t* **``solve.py``**: solve the case with `fronts.solve()`.\n\t* **``refine.py``**: get a rough approximation of the solution using `fronts.solve()` with a high tolerance, and then refine it with both `fronts.solve()` and `fronts.solve_from_guess()`.\n\t* \ud83d\udc0c **``inverse1.py``**: use `fronts.inverse()` to extract _D_ from a solution. Here, the solution is obtained with \n`fronts.solve()`. The extracted _D_ is then used with `fronts.solve()` and the\nsame conditions to verify that an equivalent solution is obtained.\n\t* \ud83d\udc0c **``inverse2.py``**: use `fronts.inverse()` to obtain _D_ \nfrom the validation case and then use it to solve the same problem. \n\t* **``validation.py``**: results with the same case solved with [porousMultiphaseFoam](https://github.com/phorgue/porousMultiphaseFoam) for comparison.\n* subdirectory **``exact/``** \u2014 solve a case with a _D_ function proposed by [Philip](https://doi.org/10.1071/PH600001) that has an exact solution\n\t* **``solve.py``**: solve the case with `fronts.solve()` and compare with the exact solution.\n\t* **``fromguess.py``**: solve the case with `fronts.solve_from_guess()` and compare with the exact solution.\n\n\n**Note:** the examples marked with \ud83d\udc0c are significantly more computationally intensive and may take more than a minute to run to completion. All other cases should finish within a few seconds at the most.\n\n## Authors\n\n* **Gabriel S. Gerlero** [@gerlero](https://github.com/gerlero)\n* **Pablo A. Kler** [@pabloakler](https://github.com/pabloakler)\n* **Claudio L.A. Berli**\n\nFronts was conceived and is developed by members of the [Santa Fe Microfluidics Group (GSaM)](http://www.microfluidica.com.ar) at the [Research Center for Computational Methods (CIMEC, UNL-CONICET)](https://www.cimec.org.ar) and the [Institute of Technological Development for the Chemical Industry (INTEC, UNL-CONICET)](https://intec.conicet.gov.ar) in Santa Fe, Argentina.\n\n\n\n\"CIMEC   \"INTEC   \"GSaM\" \n\n \n\n\n## License\n\nFronts is open-source software available under the BSD 3-clause license.", "description_content_type": "text/markdown", "docs_url": null, "download_url": "", "downloads": { "last_day": -1, "last_month": -1, "last_week": -1 }, "home_page": "https://github.com/gerlero/fronts", "keywords": "", "license": "BSD", "maintainer": "", "maintainer_email": "", "name": "fronts", "package_url": "https://pypi.org/project/fronts/", "platform": "", "project_url": "https://pypi.org/project/fronts/", "project_urls": { "Bug Tracker": "https://github.com/gerlero/fronts/issues", "Documentation": "https://fronts.readthedocs.io", "Homepage": "https://github.com/gerlero/fronts", "Source Code": "https://github.com/gerlero/fronts" }, "release_url": "https://pypi.org/project/fronts/0.9.4/", "requires_dist": null, "requires_python": ">=2.7,!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*,!=3.4.*", "summary": "Numerical library for one-dimensional nonlinear diffusion problems in semi-infinite domains", "version": "0.9.4" }, "last_serial": 5950450, "releases": { "0.9.0": [ { "comment_text": "", "digests": { "md5": "40541476c74ad683c53036a53293866c", "sha256": "ef916bb472bdbce40bfd5014e5e8d8d5c3d0780003500d1da0513fa69db68102" }, "downloads": -1, "filename": "fronts-0.9.0.tar.gz", "has_sig": false, "md5_digest": "40541476c74ad683c53036a53293866c", "packagetype": "sdist", "python_version": "source", "requires_python": ">=2.7,!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*,!=3.4.*", "size": 23811, "upload_time": "2019-09-16T17:05:04", "url": "https://files.pythonhosted.org/packages/da/ca/c17e95767ea9a3a91b10d47930fce2627f6094917149a185bf32965ab7ae/fronts-0.9.0.tar.gz" } ], "0.9.1": [ { "comment_text": "", "digests": { "md5": "72edae36358d2f6ec496b6dfd96ed778", "sha256": "663c9d5218b07f1228501f5af6ebeb441521f0f450e03807342c9e2437ed2aff" }, "downloads": -1, "filename": "fronts-0.9.1.tar.gz", "has_sig": false, "md5_digest": "72edae36358d2f6ec496b6dfd96ed778", "packagetype": "sdist", "python_version": "source", "requires_python": ">=2.7,!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*,!=3.4.*", "size": 23797, "upload_time": "2019-09-16T18:09:56", "url": "https://files.pythonhosted.org/packages/25/d0/d62a3780942340f1021b121f5bbd21a52fa28a9417bcb17c6013baa3c7ba/fronts-0.9.1.tar.gz" } ], "0.9.2": [ { "comment_text": "", "digests": { "md5": "90811e105ad74d9a8eea4a3e2640129c", "sha256": "49fac93f654f8b23590c126e86edb1bc7ea58208db4c05c63068bdf706542d0c" }, "downloads": -1, "filename": "fronts-0.9.2.tar.gz", "has_sig": false, "md5_digest": "90811e105ad74d9a8eea4a3e2640129c", "packagetype": "sdist", "python_version": "source", "requires_python": ">=2.7,!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*,!=3.4.*", "size": 23826, "upload_time": "2019-09-16T18:15:17", "url": "https://files.pythonhosted.org/packages/07/ad/db8ffa0f14bd5b4e68065ee349f26e0e7b86a6d9b0f20820cbddaa9168d0/fronts-0.9.2.tar.gz" } ], "0.9.3": [ { "comment_text": "", "digests": { "md5": "622ca9ad3e4ae3e2bf61ae655617c4e7", "sha256": "fe58c0a79e2d5a21fb5b456c6608b6aec2bd552d76170769ab49df375308a7d8" }, "downloads": -1, "filename": "fronts-0.9.3.tar.gz", "has_sig": false, "md5_digest": "622ca9ad3e4ae3e2bf61ae655617c4e7", "packagetype": "sdist", "python_version": "source", "requires_python": ">=2.7,!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*,!=3.4.*", "size": 24215, "upload_time": "2019-09-27T17:53:20", "url": "https://files.pythonhosted.org/packages/d8/26/a4a927cd1c9ca491b91ae22b3a9e29be1b2d03b4acf6f212b64d1886831a/fronts-0.9.3.tar.gz" } ], "0.9.4": [ { "comment_text": "", "digests": { "md5": "7aef286391a202db34e153064321848f", "sha256": "2e937c54cd7abee1d1575c5f3fd36236d1ffc05b81125cab06d5808838133c7a" }, "downloads": -1, "filename": "fronts-0.9.4.tar.gz", "has_sig": false, "md5_digest": "7aef286391a202db34e153064321848f", "packagetype": "sdist", "python_version": "source", "requires_python": ">=2.7,!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*,!=3.4.*", "size": 24073, "upload_time": "2019-10-09T15:17:09", "url": "https://files.pythonhosted.org/packages/7c/4a/2cd33f70e72a38a66a71e708e6be826861c71337bc06a011efdd1472d5a3/fronts-0.9.4.tar.gz" } ] }, "urls": [ { "comment_text": "", "digests": { "md5": "7aef286391a202db34e153064321848f", "sha256": "2e937c54cd7abee1d1575c5f3fd36236d1ffc05b81125cab06d5808838133c7a" }, "downloads": -1, "filename": "fronts-0.9.4.tar.gz", "has_sig": false, "md5_digest": "7aef286391a202db34e153064321848f", "packagetype": "sdist", "python_version": "source", "requires_python": ">=2.7,!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*,!=3.4.*", "size": 24073, "upload_time": "2019-10-09T15:17:09", "url": "https://files.pythonhosted.org/packages/7c/4a/2cd33f70e72a38a66a71e708e6be826861c71337bc06a011efdd1472d5a3/fronts-0.9.4.tar.gz" } ] }