<div align="center">
# Snek5000
[](https://pypi.org/project/snek5000/)
[](https://github.com/snek5000/snek5000/actions)
[](https://results.pre-commit.ci/latest/github/snek5000/snek5000/main)
[](https://snek5000.readthedocs.io/en/latest/?badge=latest)
[](https://sonarcloud.io/dashboard?id=snek5000_snek5000)
[](https://codecov.io/gh/snek5000/snek5000)
[](https://doi.org/10.5281/zenodo.7399621)
<!-- badges -->
Python framework for Nek5000
</div>
**Documentation**: <https://snek5000.readthedocs.io/>
Snek5000 is a Python package which allows one to write [Fluidsim] solvers based
for the simulations on the Fortran [CFD] code [Nek5000]. There are open-source
solvers (in particular [snek5000-phill], [snek5000-cbox] and [snek5000-tgv])
and it's not difficult to write your own solver based on your Nek5000 cases (as
shown in [this
tutorial](https://snek5000.readthedocs.io/en/latest/packaging.html)).
With a Snek5000-Fluidsim solver, it becomes very easy to
- launch/restart simulations with Python scripts and terminal commands,
- load simulations, read the associated parameters/data and produce nice
figures/movies.
Snek5000 can be seen as a workflow manager for Nek5000 or a Python wrapper
around Nek5000. It uses Nek5000 on the background and is thus NOT a rewrite of
Nek5000!
Snek5000 is powered by nice Python packages such as [Snakemake], [Fluidsim],
[Pymech], Matplotlib, Jinja, Pytest, Xarray, etc.
## Quick start
Install it as follows:
```sh
export NEK_SOURCE_ROOT="/path/to/Nek5000"
pip install snek5000
```
See here for [detailed installation instructions](https://snek5000.readthedocs.io/en/latest/install.html).
### Why Snek5000?
The [`snek5000` Python
API](https://snek5000.readthedocs.io/en/latest/_generated/snek5000.html) allows
you to launch/restart/load simulations. For example, the [periodic hill Nek5000
example](https://nek5000.github.io/NekDoc/tutorials/perhill.html) can be
launched with our [snek5000-phill] solver (installable with `pip install snek5000-phill`) as follow:
```python
from phill.solver import Simul
params = Simul.create_default_params()
# modify parameters as needed, for example
params.output.sub_directory = "examples_snek_phill"
params.short_name_type_run = "readme"
params.oper.nx = 12
params.oper.ny = 10
params.oper.nz = 8
params.nek.general.num_steps = 10
...
# instantiate the object representing the simulation
sim = Simul(params)
# compile and launch the simulation (blocking)
sim.make.exec("run_fg")
```
A simulation directory is created automatically (with this example, something
like
`~/Sim_data/examples_snek_phill/phill_readme_12x10x8_V1.x1.x1._2022-10-27_15-21-58`).
Then, the simulation object can be recreated from this directory. An easy way
would be to go into this directory, start IPython with the `snek-ipy-load`
command, and run:
```python
# get/print the simulation parameters from the object
sim.params
# few examples of various read and plots
sim.output.print_stdout.plot_dt()
sim.output.print_stdout.plot_nb_iterations()
sim.output.history_points.plot()
sim.output.history_points.coords
data = sim.output.history_points.load_1point(2)
sim.output.phys_fields.plot_hexa()
sim.output.phys_fields.animate("pressure", interactive=True)
sim.output.phys_fields.animate(
"pressure", dt_frame_in_sec=0.1, equation="y=0.5", save_file="my_great_movie.gif"
)
```
For example, this movie has been produced by a `sim.output.phys_fields.animate`
call from a [snek5000-cbox]
[simulation](https://github.com/snek5000/snek5000/blob/main/docs/examples/scripts/simul_cbox_movie.py):
https://user-images.githubusercontent.com/8842662/202872147-4ea3c749-dc63-4a73-98a0-6c787edb9cd3.mp4
Check out the
[tutorials](https://snek5000.readthedocs.io/en/latest/tutorials.html) to learn
how to use Snek5000.
<details>
<summary>
<b>
Need more reasons to use snek5000?
</b>
</summary>
#### Advantages
##### Parameters, get started without studying the whole documentation
- Saves you from the trouble in setting up multiple source files (`.box`, `.par`, `SIZE`)
- Uses sensible names and defaults for the parameters
- Avoids typos and human errors thanks to a nice [parameter container object]
- Records metadata related to the simulation into human and machine readable files (`params_simul.xml`, `config_simul.yml`)
- Checks for consistency of parameters
- Automatically sets some parameters as Python properties
##### Workflow
- Out of source build (per run), which can be inspected or executed using the
conventional `makenek` for debugging
- Reproducible workflows, not susceptible to changes in environment variables by default
- Scriptable simulation execution allowing parametric studies
- Easy to load simulation for performing offline post-processing and restarting the simulation
- Better than Bash scripting like:
```sh
# Build case
cd src/phill/
CASE="phill"
echo "$CASE.box" | genbox
mv -f box.re2 phill.re2
echo "$CASE\n0.01" | genmap
FFLAGS="-mcmodel=medium -march=native" CFLAGS="-mcmodel=medium -march=native" makenek
cd -
# Run case
cd src/phill/
nekmpi $CASE <nb_procs> # foreground
nekbmpi $CASE <nb_procs> # background
cd -
# Clean
makenek clean
```
- Use of [Snakemake](https://snakemake.readthedocs.io/en/stable/) which is
similar to GNU Make, but allows one to blend Bash and Python scripting and uses
simple YAML files for managing custom configurations of compilers and flags for
different computers.
##### Coding
- User friendly, modular, object oriented API
- Reuse of code (inheritance)
- Tested with a good code coverage (>90%)
#### Disadvantages
- Yet another layer... with the possible associated bugs :-)
- Requires some basic knowledge of Python to use (*not really a big issue, to
be honest*).
- Deep modification of solvers requires learning how
[Snakemake](https://snakemake.readthedocs.io/en/stable/) functions and [how
to write Jinja
templates](https://jinja.palletsprojects.com/en/2.11.x/templates/) (which are
[not so hard](https://snek5000.readthedocs.io/en/latest/how-to/templates.html), btw)
</details>
## Contributing
Contributions are welcome! You can help by testing out the code, filing issues
and submitting patches. See [contributing guidelines](CONTRIBUTING.md).
[cfd]: https://en.wikipedia.org/wiki/Computational_fluid_dynamics
[fluidsim]: https://fluidsim.readthedocs.io
[nek5000]: https://nek5000.mcs.anl.gov/
[parameter container object]: https://fluiddyn.readthedocs.io/en/latest/generated/fluiddyn.util.paramcontainer.html
[pymech]: https://github.com/eX-Mech/pymech
[snakemake]: https://snakemake.readthedocs.io
[snek5000-cbox]: https://github.com/snek5000/snek5000-cbox
[snek5000-phill]: https://github.com/snek5000/snek5000-phill
[snek5000-tgv]: https://github.com/snek5000/snek5000/tree/main/docs/examples/snek5000-tgv
Raw data
{
"_id": null,
"home_page": "https://github.com/snek5000/snek5000",
"name": "snek5000",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "",
"author": "Ashwin Vishnu Mohanan",
"author_email": "ashwinvis+gh@protonmail.com",
"download_url": "https://files.pythonhosted.org/packages/c5/b9/2a4ab4455980ffaff37cda491712dfb005cc0a6fec62b57171677d956d8f/snek5000-0.9.0.tar.gz",
"platform": null,
"description": "<div align=\"center\">\n\n# Snek5000\n\n[](https://pypi.org/project/snek5000/)\n[](https://github.com/snek5000/snek5000/actions)\n[](https://results.pre-commit.ci/latest/github/snek5000/snek5000/main)\n[](https://snek5000.readthedocs.io/en/latest/?badge=latest)\n[](https://sonarcloud.io/dashboard?id=snek5000_snek5000)\n[](https://codecov.io/gh/snek5000/snek5000)\n[](https://doi.org/10.5281/zenodo.7399621)\n\n<!-- badges -->\n\nPython framework for Nek5000\n\n</div>\n\n**Documentation**: <https://snek5000.readthedocs.io/>\n\nSnek5000 is a Python package which allows one to write [Fluidsim] solvers based\nfor the simulations on the Fortran [CFD] code [Nek5000]. There are open-source\nsolvers (in particular [snek5000-phill], [snek5000-cbox] and [snek5000-tgv])\nand it's not difficult to write your own solver based on your Nek5000 cases (as\nshown in [this\ntutorial](https://snek5000.readthedocs.io/en/latest/packaging.html)).\n\nWith a Snek5000-Fluidsim solver, it becomes very easy to\n\n- launch/restart simulations with Python scripts and terminal commands,\n- load simulations, read the associated parameters/data and produce nice\n figures/movies.\n\nSnek5000 can be seen as a workflow manager for Nek5000 or a Python wrapper\naround Nek5000. It uses Nek5000 on the background and is thus NOT a rewrite of\nNek5000!\n\nSnek5000 is powered by nice Python packages such as [Snakemake], [Fluidsim],\n[Pymech], Matplotlib, Jinja, Pytest, Xarray, etc.\n\n## Quick start\n\nInstall it as follows:\n\n```sh\nexport NEK_SOURCE_ROOT=\"/path/to/Nek5000\"\n\npip install snek5000\n```\n\nSee here for [detailed installation instructions](https://snek5000.readthedocs.io/en/latest/install.html).\n\n### Why Snek5000?\n\nThe [`snek5000` Python\nAPI](https://snek5000.readthedocs.io/en/latest/_generated/snek5000.html) allows\nyou to launch/restart/load simulations. For example, the [periodic hill Nek5000\nexample](https://nek5000.github.io/NekDoc/tutorials/perhill.html) can be\nlaunched with our [snek5000-phill] solver (installable with `pip install snek5000-phill`) as follow:\n\n```python\nfrom phill.solver import Simul\n\nparams = Simul.create_default_params()\n\n# modify parameters as needed, for example\nparams.output.sub_directory = \"examples_snek_phill\"\nparams.short_name_type_run = \"readme\"\n\nparams.oper.nx = 12\nparams.oper.ny = 10\nparams.oper.nz = 8\n\nparams.nek.general.num_steps = 10\n\n...\n\n# instantiate the object representing the simulation\nsim = Simul(params)\n\n# compile and launch the simulation (blocking)\nsim.make.exec(\"run_fg\")\n```\n\nA simulation directory is created automatically (with this example, something\nlike\n`~/Sim_data/examples_snek_phill/phill_readme_12x10x8_V1.x1.x1._2022-10-27_15-21-58`).\nThen, the simulation object can be recreated from this directory. An easy way\nwould be to go into this directory, start IPython with the `snek-ipy-load`\ncommand, and run:\n\n```python\n# get/print the simulation parameters from the object\nsim.params\n\n# few examples of various read and plots\nsim.output.print_stdout.plot_dt()\nsim.output.print_stdout.plot_nb_iterations()\n\nsim.output.history_points.plot()\nsim.output.history_points.coords\ndata = sim.output.history_points.load_1point(2)\n\nsim.output.phys_fields.plot_hexa()\nsim.output.phys_fields.animate(\"pressure\", interactive=True)\nsim.output.phys_fields.animate(\n \"pressure\", dt_frame_in_sec=0.1, equation=\"y=0.5\", save_file=\"my_great_movie.gif\"\n)\n```\n\nFor example, this movie has been produced by a `sim.output.phys_fields.animate`\ncall from a [snek5000-cbox]\n[simulation](https://github.com/snek5000/snek5000/blob/main/docs/examples/scripts/simul_cbox_movie.py):\n\nhttps://user-images.githubusercontent.com/8842662/202872147-4ea3c749-dc63-4a73-98a0-6c787edb9cd3.mp4\n\nCheck out the\n[tutorials](https://snek5000.readthedocs.io/en/latest/tutorials.html) to learn\nhow to use Snek5000.\n\n<details>\n<summary>\n<b>\nNeed more reasons to use snek5000?\n</b>\n</summary>\n\n#### Advantages\n\n##### Parameters, get started without studying the whole documentation\n\n- Saves you from the trouble in setting up multiple source files (`.box`, `.par`, `SIZE`)\n- Uses sensible names and defaults for the parameters\n- Avoids typos and human errors thanks to a nice [parameter container object]\n- Records metadata related to the simulation into human and machine readable files (`params_simul.xml`, `config_simul.yml`)\n- Checks for consistency of parameters\n- Automatically sets some parameters as Python properties\n\n##### Workflow\n\n- Out of source build (per run), which can be inspected or executed using the\n conventional `makenek` for debugging\n\n- Reproducible workflows, not susceptible to changes in environment variables by default\n\n- Scriptable simulation execution allowing parametric studies\n\n- Easy to load simulation for performing offline post-processing and restarting the simulation\n\n- Better than Bash scripting like:\n\n ```sh\n # Build case\n cd src/phill/\n CASE=\"phill\"\n echo \"$CASE.box\" | genbox\n mv -f box.re2 phill.re2\n echo \"$CASE\\n0.01\" | genmap\n FFLAGS=\"-mcmodel=medium -march=native\" CFLAGS=\"-mcmodel=medium -march=native\" makenek\n cd -\n\n # Run case\n cd src/phill/\n nekmpi $CASE <nb_procs> # foreground\n nekbmpi $CASE <nb_procs> # background\n cd -\n\n # Clean\n makenek clean\n ```\n\n- Use of [Snakemake](https://snakemake.readthedocs.io/en/stable/) which is\n similar to GNU Make, but allows one to blend Bash and Python scripting and uses\n simple YAML files for managing custom configurations of compilers and flags for\n different computers.\n\n##### Coding\n\n- User friendly, modular, object oriented API\n- Reuse of code (inheritance)\n- Tested with a good code coverage (>90%)\n\n#### Disadvantages\n\n- Yet another layer... with the possible associated bugs :-)\n- Requires some basic knowledge of Python to use (*not really a big issue, to\n be honest*).\n- Deep modification of solvers requires learning how\n [Snakemake](https://snakemake.readthedocs.io/en/stable/) functions and [how\n to write Jinja\n templates](https://jinja.palletsprojects.com/en/2.11.x/templates/) (which are\n [not so hard](https://snek5000.readthedocs.io/en/latest/how-to/templates.html), btw)\n\n</details>\n\n## Contributing\n\nContributions are welcome! You can help by testing out the code, filing issues\nand submitting patches. See [contributing guidelines](CONTRIBUTING.md).\n\n[cfd]: https://en.wikipedia.org/wiki/Computational_fluid_dynamics\n[fluidsim]: https://fluidsim.readthedocs.io\n[nek5000]: https://nek5000.mcs.anl.gov/\n[parameter container object]: https://fluiddyn.readthedocs.io/en/latest/generated/fluiddyn.util.paramcontainer.html\n[pymech]: https://github.com/eX-Mech/pymech\n[snakemake]: https://snakemake.readthedocs.io\n[snek5000-cbox]: https://github.com/snek5000/snek5000-cbox\n[snek5000-phill]: https://github.com/snek5000/snek5000-phill\n[snek5000-tgv]: https://github.com/snek5000/snek5000/tree/main/docs/examples/snek5000-tgv\n",
"bugtrack_url": null,
"license": "BSD-3-Clause",
"summary": "Python framework for Nek5000",
"version": "0.9.0",
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "10ccbd27be3412cd440216a759a41944d2861a057b233933fbc9c59636b71f8f",
"md5": "10eab61151365ae0c8e3fa82c87cab2c",
"sha256": "4bbe35bde14583cda45ae0eae50bcfecf5583775da0cb6cfe6dc2686b3d201fb"
},
"downloads": -1,
"filename": "snek5000-0.9.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "10eab61151365ae0c8e3fa82c87cab2c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 75103,
"upload_time": "2023-01-11T13:34:56",
"upload_time_iso_8601": "2023-01-11T13:34:56.180311Z",
"url": "https://files.pythonhosted.org/packages/10/cc/bd27be3412cd440216a759a41944d2861a057b233933fbc9c59636b71f8f/snek5000-0.9.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c5b92a4ab4455980ffaff37cda491712dfb005cc0a6fec62b57171677d956d8f",
"md5": "921dd2b43b2559551823cbc1ec901322",
"sha256": "2ef80515542123e32e96b8a67262f98106e1be685bb02ebabcb48e32c315c1e0"
},
"downloads": -1,
"filename": "snek5000-0.9.0.tar.gz",
"has_sig": false,
"md5_digest": "921dd2b43b2559551823cbc1ec901322",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 234484,
"upload_time": "2023-01-11T13:34:58",
"upload_time_iso_8601": "2023-01-11T13:34:58.028385Z",
"url": "https://files.pythonhosted.org/packages/c5/b9/2a4ab4455980ffaff37cda491712dfb005cc0a6fec62b57171677d956d8f/snek5000-0.9.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-01-11 13:34:58",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "snek5000",
"github_project": "snek5000",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "snek5000"
}
JSON
