| Name | fridom JSON |
| Version |
0.0.5
JSON |
| download |
| home_page | None |
| Summary | Framework for Idealized Ocean Models |
| upload_time | 2025-01-31 13:13:53 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | MIT License
Copyright (c) 2023 Silvano Rosenau
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE. |
| keywords |
oceanography
idealized ocean models
modeling
numerical modeling
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
[](https://opensource.org/licenses/MIT)
[](https://fridom.readthedocs.io/en/latest/index.html)
[](https://codecov.io/github/Gordi42/fridom)
[](https://doi.org/10.5281/zenodo.14536978)
[](https://www.youtube.com/watch?v=Fotni4P2ZQs)
# Framework for Idealized Ocean Models (FRIDOM)
- **Purpose & Flexibility:** FRIDOM is a powerful and modular framework originally developed for running simulations of idealized ocean models. Thanks to its modular design, it can be used to simulate any model represented by a set of partial differential equations, such as $\partial_t \boldsymbol{z} = \boldsymbol{f}(\boldsymbol{z}, t)$.
- **Minimizing Boilerplate Code:** To streamline the development process, FRIDOM provides base classes for common components like grids, differential and interpolation operators, time-stepping schemes, netCDF output, animations, etc.
- **Easy Model Modifications:** Every component of a model in FRIDOM is fully exchangeable without changing the model's source code. This feature makes FRIDOM an excellent sandbox for testing new ideas and a useful tool for educational purposes.
- **Balancing Flexibility & Usability:** While modular frameworks often compromise user-friendliness for flexibility, FRIDOM strives to be both flexible and easy to use. It offers a high-level [API](https://fridom.readthedocs.io/en/latest/fridom_api.html), comprehensive tutorials, and numerous [examples](https://fridom.readthedocs.io/en/latest/auto_examples/index.html) available within the [documentation](https://fridom.readthedocs.io/en/latest/index.html).
- **Performance through Python & JAX:** Written in Python for ease of use, FRIDOM overcomes Python's performance limitations by leveraging the Just-In-Time (JIT) compiler from JAX. This approach allows FRIDOM to achieve speeds comparable to compiled languages like Fortran or C, and it can further accelerate simulations by running on GPUs.
**NOTE: FRIDOM is in en early development stage, and as such, it may undergo significant changes.**
## Documentation
Learn more about FRIDOM in its official [documentation](https://fridom.readthedocs.io/en/latest/index.html).
## Installation
To install FRIDOM from the source code repository, clone the repository in your desired directory and install the package using pip:
``` bash
git clone https://github.com/Gordi42/FRIDOM
cd FRIDOM
pip install -e '.[jax-cuda]'
```
see [here](https://fridom.readthedocs.io/en/latest/installation.html) for more information on the installation.
## Example
The following example showcases a simulation run in the shallow water model. The initial condition is a jet that is barotropic instable. The instabilities grow and form vortices.
``` python
import fridom.shallowwater as sw
# Create the grid and model settings
grid = sw.grid.cartesian.Grid(N=(256,256), L=(1,1), periodic_bounds=(True, True))
mset = sw.ModelSettings(grid=grid, f0=1, csqr=1)
mset.time_stepper.dt = 0.7e-3
mset.setup()
# Create the initial condition
z = sw.initial_conditions.Jet(mset, width=0.1, wavenum=2, waveamp=0.05)
# Create the model and run it
model = sw.Model(mset)
model.z = z # set the initial condition
model.run(runlen=2.5)
# Plot the final total energy (kinetic + potential)
model.z.etot.xr.plot(cmap="RdBu_r")
```
<img src="media/ShallowWater/shallow_water_example.png" />
## List of available models
- **[nonhydro:](https://fridom.readthedocs.io/en/latest/auto_api/fridom.nonhydro.html#module-fridom.nonhydro)** A 3D pseudo-spectral non-hydrostatic Boussinesq model adapted from [ps3d](https://github.com/ceden/ps3d).
- **[shallowwater]():** A 2D rotating shallow water model.
## Parallelization
Although the basic structure for parallelization is already prepared, FRIDOM does **not yet** support parallelization. We plan to parallelize the framework using [jaxDecomp](https://github.com/DifferentiableUniverseInitiative/jaxDecomp). Nevertheless, thanks to its compatibility with GPUs, simulations with grid sizes on the order of \(10^6\) grid points—such as \(512^3\) or \(8192^2\) grid points—can already be run in a reasonable amount of time.
## Alternatives
FRIDOM draws inspiration from several existing modeling frameworks and tools, which have influenced its design and capabilities. Some notable inspirations include:
- **[Oceananigans.jl](https://github.com/CliMA/Oceananigans.jl):** A very powerfull ocean model written in Julia with CPU and GPU support. Oceananigans is suitable for both idealized and realistic ocean setups.
- **[pyOM2](https://github.com/ceden/pyOM2):** An ocean model written in Fortran with many available parameterizations and closudes.
- **[Veros](https://github.com/team-ocean/veros):** A python implementation of `pyOM2` that runs on CPUs and GPUs using JAX.
- **[ps3D](https://github.com/ceden/ps3D):** A pseudo spectral non-hydrostatic incompressible flow solver written in Fortran.
- **[Shenfun](https://github.com/spectralDNS/shenfun):** A python framework for solving systems of partial differential equations using the spectral Galerkin method.
## Gallery
https://github.com/Gordi42/FRIDOM/assets/118457787/66cca07d-5893-4c1b-af13-901dc78bdd6b
## Roadmap
### Todos for version 0.1.0:
- [ ] parallelization using jaxDecomp
- [x] make mpi4py dependency optional
- [x] adapt shallowwater to new model structure
- [x] adapt optimal balance to new model structure
- [x] make NNMD work
- [ ] fix the CG pressure solver in nonhydro model
- [ ] increase test coverage to at least 90%
- [ ] adjust code to linting standards
### Long term Todos:
**Grid:**
- [ ] Add a rectilinear grid with variable $\Delta x(x)$
- [ ] Add a (pseudo) spherical grid
- [ ] Add unstructured grids.
**Models:**
- [ ] Add a hydrostatic primitive equations model (like pyOM2)
- [ ] Add a quasi-geostrophic model
- [ ] Add a compressible flow solver
**Time Steppers:**
- [ ] Adding implicit and semi implicit time steppers
**Advection Schemes:**
- [ ] Add higher order advection schemes like WENO
**Others:**
- [ ] Optimize parallelization for CPUs
- [ ] Add possibility to couple multiple fridom models
## How to cite
```
@software{Rosenau_fridom_2024,
author = {Rosenau, Silvano Gordian},
doi = {10.5281/zenodo.14536979},
month = dec,
title = {{Fridom: A framework for idealized ocean models.}},
url = {https://github.com/Gordi42/fridom},
version = {0.0.1},
year = {2024}
}
```
## Author
* Silvano Rosenau
## License
[MIT](LICENSE.txt)
Raw data
{
"_id": null,
"home_page": null,
"name": "fridom",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "oceanography, idealized ocean models, modeling, numerical modeling",
"author": null,
"author_email": "Silvano Rosenau <silvano.rosenau@uni-hamburg.de>",
"download_url": "https://files.pythonhosted.org/packages/c3/79/160dba3e70b7335aec5ac6b7fcdfd4445feb7ec3535c217a3eea42ba9798/fridom-0.0.5.tar.gz",
"platform": null,
"description": "[](https://opensource.org/licenses/MIT)\n[](https://fridom.readthedocs.io/en/latest/index.html)\n[](https://codecov.io/github/Gordi42/fridom)\n[](https://doi.org/10.5281/zenodo.14536978)\n\n[](https://www.youtube.com/watch?v=Fotni4P2ZQs)\n\n# Framework for Idealized Ocean Models (FRIDOM)\n\n- **Purpose & Flexibility:** FRIDOM is a powerful and modular framework originally developed for running simulations of idealized ocean models. Thanks to its modular design, it can be used to simulate any model represented by a set of partial differential equations, such as $\\partial_t \\boldsymbol{z} = \\boldsymbol{f}(\\boldsymbol{z}, t)$.\n\n- **Minimizing Boilerplate Code:** To streamline the development process, FRIDOM provides base classes for common components like grids, differential and interpolation operators, time-stepping schemes, netCDF output, animations, etc.\n\n- **Easy Model Modifications:** Every component of a model in FRIDOM is fully exchangeable without changing the model's source code. This feature makes FRIDOM an excellent sandbox for testing new ideas and a useful tool for educational purposes.\n\n- **Balancing Flexibility & Usability:** While modular frameworks often compromise user-friendliness for flexibility, FRIDOM strives to be both flexible and easy to use. It offers a high-level [API](https://fridom.readthedocs.io/en/latest/fridom_api.html), comprehensive tutorials, and numerous [examples](https://fridom.readthedocs.io/en/latest/auto_examples/index.html) available within the [documentation](https://fridom.readthedocs.io/en/latest/index.html).\n\n- **Performance through Python & JAX:** Written in Python for ease of use, FRIDOM overcomes Python's performance limitations by leveraging the Just-In-Time (JIT) compiler from JAX. This approach allows FRIDOM to achieve speeds comparable to compiled languages like Fortran or C, and it can further accelerate simulations by running on GPUs.\n\n**NOTE: FRIDOM is in en early development stage, and as such, it may undergo significant changes.**\n\n## Documentation\nLearn more about FRIDOM in its official [documentation](https://fridom.readthedocs.io/en/latest/index.html).\n\n## Installation\nTo install FRIDOM from the source code repository, clone the repository in your desired directory and install the package using pip:\n\n``` bash\ngit clone https://github.com/Gordi42/FRIDOM\ncd FRIDOM\npip install -e '.[jax-cuda]'\n```\nsee [here](https://fridom.readthedocs.io/en/latest/installation.html) for more information on the installation.\n\n## Example\nThe following example showcases a simulation run in the shallow water model. The initial condition is a jet that is barotropic instable. The instabilities grow and form vortices.\n\n``` python\nimport fridom.shallowwater as sw\n\n# Create the grid and model settings\ngrid = sw.grid.cartesian.Grid(N=(256,256), L=(1,1), periodic_bounds=(True, True))\nmset = sw.ModelSettings(grid=grid, f0=1, csqr=1)\nmset.time_stepper.dt = 0.7e-3\nmset.setup()\n\n# Create the initial condition\nz = sw.initial_conditions.Jet(mset, width=0.1, wavenum=2, waveamp=0.05)\n\n# Create the model and run it\nmodel = sw.Model(mset)\nmodel.z = z # set the initial condition\nmodel.run(runlen=2.5)\n\n# Plot the final total energy (kinetic + potential)\nmodel.z.etot.xr.plot(cmap=\"RdBu_r\")\n``` \n<img src=\"media/ShallowWater/shallow_water_example.png\" />\n\n## List of available models\n- **[nonhydro:](https://fridom.readthedocs.io/en/latest/auto_api/fridom.nonhydro.html#module-fridom.nonhydro)** A 3D pseudo-spectral non-hydrostatic Boussinesq model adapted from [ps3d](https://github.com/ceden/ps3d).\n- **[shallowwater]():** A 2D rotating shallow water model.\n\n## Parallelization\n\nAlthough the basic structure for parallelization is already prepared, FRIDOM does **not yet** support parallelization. We plan to parallelize the framework using [jaxDecomp](https://github.com/DifferentiableUniverseInitiative/jaxDecomp). Nevertheless, thanks to its compatibility with GPUs, simulations with grid sizes on the order of \\(10^6\\) grid points\u2014such as \\(512^3\\) or \\(8192^2\\) grid points\u2014can already be run in a reasonable amount of time.\n\n## Alternatives\n\nFRIDOM draws inspiration from several existing modeling frameworks and tools, which have influenced its design and capabilities. Some notable inspirations include:\n- **[Oceananigans.jl](https://github.com/CliMA/Oceananigans.jl):** A very powerfull ocean model written in Julia with CPU and GPU support. Oceananigans is suitable for both idealized and realistic ocean setups. \n\n- **[pyOM2](https://github.com/ceden/pyOM2):** An ocean model written in Fortran with many available parameterizations and closudes.\n\n- **[Veros](https://github.com/team-ocean/veros):** A python implementation of `pyOM2` that runs on CPUs and GPUs using JAX.\n- **[ps3D](https://github.com/ceden/ps3D):** A pseudo spectral non-hydrostatic incompressible flow solver written in Fortran.\n- **[Shenfun](https://github.com/spectralDNS/shenfun):** A python framework for solving systems of partial differential equations using the spectral Galerkin method.\n\n## Gallery\nhttps://github.com/Gordi42/FRIDOM/assets/118457787/66cca07d-5893-4c1b-af13-901dc78bdd6b\n\n## Roadmap\n### Todos for version 0.1.0:\n- [ ] parallelization using jaxDecomp\n- [x] make mpi4py dependency optional\n- [x] adapt shallowwater to new model structure\n- [x] adapt optimal balance to new model structure\n- [x] make NNMD work\n- [ ] fix the CG pressure solver in nonhydro model\n- [ ] increase test coverage to at least 90%\n- [ ] adjust code to linting standards\n\n### Long term Todos:\n**Grid:**\n- [ ] Add a rectilinear grid with variable $\\Delta x(x)$\n- [ ] Add a (pseudo) spherical grid\n- [ ] Add unstructured grids.\n\n**Models:**\n- [ ] Add a hydrostatic primitive equations model (like pyOM2)\n- [ ] Add a quasi-geostrophic model\n- [ ] Add a compressible flow solver\n\n**Time Steppers:**\n- [ ] Adding implicit and semi implicit time steppers\n\n**Advection Schemes:**\n- [ ] Add higher order advection schemes like WENO\n\n**Others:**\n- [ ] Optimize parallelization for CPUs\n- [ ] Add possibility to couple multiple fridom models\n\n## How to cite\n\n```\n@software{Rosenau_fridom_2024,\n author = {Rosenau, Silvano Gordian},\n doi = {10.5281/zenodo.14536979},\n month = dec,\n title = {{Fridom: A framework for idealized ocean models.}},\n url = {https://github.com/Gordi42/fridom},\n version = {0.0.1},\n year = {2024}\n}\n```\n\n## Author\n * Silvano Rosenau\n\n## License\n\n\n[MIT](LICENSE.txt)\n\n\n\n",
"bugtrack_url": null,
"license": "MIT License\n \n Copyright (c) 2023 Silvano Rosenau\n \n Permission is hereby granted, free of charge, to any person obtaining a copy\n of this software and associated documentation files (the \"Software\"), to deal\n in the Software without restriction, including without limitation the rights\n to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n copies of the Software, and to permit persons to whom the Software is\n furnished to do so, subject to the following conditions:\n \n The above copyright notice and this permission notice shall be included in all\n copies or substantial portions of the Software.\n \n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n SOFTWARE.",
"summary": "Framework for Idealized Ocean Models",
"version": "0.0.5",
"project_urls": {
"Repository": "https://github.com/Gordi42/FRIDOM"
},
"split_keywords": [
"oceanography",
" idealized ocean models",
" modeling",
" numerical modeling"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "cac6db2ca7d277ae59ed718d0371ca2629f4d186e17990b8d9f912d2b4e3e41e",
"md5": "dec044a7f4945e91ca98b58aa0b00533",
"sha256": "04a1ea990eb905e04924b44a0510854bdcf9cb7058b41a5a711b07e219598ea5"
},
"downloads": -1,
"filename": "fridom-0.0.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "dec044a7f4945e91ca98b58aa0b00533",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 208541,
"upload_time": "2025-01-31T13:13:52",
"upload_time_iso_8601": "2025-01-31T13:13:52.198370Z",
"url": "https://files.pythonhosted.org/packages/ca/c6/db2ca7d277ae59ed718d0371ca2629f4d186e17990b8d9f912d2b4e3e41e/fridom-0.0.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "c379160dba3e70b7335aec5ac6b7fcdfd4445feb7ec3535c217a3eea42ba9798",
"md5": "7a04f8dc2a541404811c36de317ed242",
"sha256": "c2a993fb076d84f4331e8ccc937561ac1ccab9c51747f7ad44525b8ab511fa78"
},
"downloads": -1,
"filename": "fridom-0.0.5.tar.gz",
"has_sig": false,
"md5_digest": "7a04f8dc2a541404811c36de317ed242",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 152518,
"upload_time": "2025-01-31T13:13:53",
"upload_time_iso_8601": "2025-01-31T13:13:53.786424Z",
"url": "https://files.pythonhosted.org/packages/c3/79/160dba3e70b7335aec5ac6b7fcdfd4445feb7ec3535c217a3eea42ba9798/fridom-0.0.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-31 13:13:53",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Gordi42",
"github_project": "FRIDOM",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "fridom"
}
