Skip to content

Commit

Permalink
Merge pull request #288 from snek5000/joss-paper-proofread
Browse files Browse the repository at this point in the history 
Joss paper proofread
  • Loading branch information
@paugier
paugier committed Apr 28, 2023
2 parents 3b17bf3 + c89b167 commit 6060655
Show file tree
Hide file tree
Showing 5 changed files with 109 additions and 105 deletions.
2 changes: 1 addition & 1 deletion README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ 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)).
tutorial](https://snek5000.readthedocs.io/en/latest/tuto_packaging.html)).

With a Snek5000-Fluidsim solver, it becomes very easy to

Expand Down
2 changes: 1 addition & 1 deletion docs/joss_paper/codemeta.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@
"email": "ashwin.mohanan@smhi.se",
"givenName": "Ashwin Vishnu",
"familyName": "Mohanan",
"affiliation": "Swedish Meteorological and Hydrological Institute, Norrk{\"o}ping, Sweden"
"affiliation": "Swedish Meteorological and Hydrological Institute, Norrköping, Sweden"
},
{
"@id": "https://orcid.org/0000-0002-0295-5308",
Expand Down
10 changes: 5 additions & 5 deletions docs/joss_paper/generate_metadata.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,12 +5,12 @@
from pathlib import Path
from datetime import datetime

import ruamel.yaml
import yaml


here = Path.cwd()

with (here.parent / "codemeta.json").open() as fp:
with (here / "codemeta.json").open() as fp:
cm = load(fp)


Expand Down Expand Up @@ -62,12 +62,12 @@ def make_date(date):
# yaml.indent(sequence=4, offset=2, mapping=4)
def dump(data, dest):
# yaml.dump(data, dest)
ruamel.yaml.dump(
yaml.safe_dump(
data,
dest,
stream=dest,
explicit_start=True,
allow_unicode=True,
Dumper=ruamel.yaml.RoundTripDumper,
# Dumper=ruamel.yaml.RoundTripDumper,
)


Expand Down
11 changes: 0 additions & 11 deletions docs/joss_paper/paper.bib
View file
Original file line number Diff line number Diff line change
Expand Up @@ -137,17 +137,6 @@ @misc{neko
primaryClass={cs.MS}
}

@misc{nekpy,
title = {maxhutch/nekpy},
url = {https://github.com/maxhutch/nekpy},
copyright = {MIT},
urldate = {2020-04-20},
author = {Hutchinson, Max},
month = jun,
year = {2016},
note = {original-date: 2016-06-07T19:57:47Z},
}

@article{openfoam,
title={A tensorial approach to computational continuum mechanics using object-oriented techniques},
author={Weller, Henry G and Tabor, Gavin and Jasak, Hrvoje and Fureby, Christer},
Expand Down
189 changes: 102 additions & 87 deletions docs/joss_paper/paper.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -49,12 +49,64 @@ simulation data, and generating figures and movies. This paper introduces
Snek5000, discusses its design principles, and highlights its impact on the
scientific community.

# Snek5000: features and capabilities
# Statement of need

## State of the art

The CFD framework Nek5000 [@nek5000] is the culmination of several decades of
development.
Nek5000 solvers can produce high-fidelity simulations owing to spectral-element
method and can scale up to several thousands of cores [@nek5000_scaling].
Development of Nek5000 is primarily driven by performance optimization,
incorporating new numerical method whilst following a keep-it-simple approach
to ensure portability across various HPC machines.

Development of Nek5000 continues to this day with efforts underway to use GPUs
[@nek5000_openacc] and to rewrite it in C++ [@nekrs] and modern Fortran
[@neko].

To the best of the authors' knowledge no other actively maintained and reusable
approaches have been made to wrap Nek5000. A project called
[`nekpy`](https://github.com/maxhutch/nekpy)
was the only known prior work resembling Snek5000, where it uses template
source files to fill in parameters.

## Better user-experience with Snek5000

Snek5000 enhances the user-experience by addressing the following downsides of
using a typical Nek5000 solver:

1. Only a limited set of utilities come packaged with Nek5000 and those focus
on compilation and mesh-generation. As a result, usability of Nek5000 takes a
hit and a practitioner is left to construct a home-brewed solution to conduct
exploratory research and parametric studies. Snek5000 functions as a workflow
manager for assisting packaging, setup, compilation and post-processing aspects
of a simulation.

2. The simulation parameters are spread in at least three different files (
`*.box`, `*.par` and `SIZE`). Some parameters have short and cryptic names
(for example, `lx1`, `lxd`, etc.) and are dependent on each other. Snek5000
tries to provide good defaults, uses more legible parameter names when
necessary and [dynamically set some of these
parameters](https://snek5000.readthedocs.io/en/stable/_generated/snek5000.operators.html#snek5000.operators.Operators)
when possible. This allows a user to get started without the need to master the
whole manual.

# Snek5000: design principles, features and capabilities

## Powered by Python Packages

## A Fluidsim extension
Snek5000 leverages a variety of Python packages, including Snakemake
[@snakemake], FluidSim [@fluidsim], Pymech [@pymech], Matplotlib [@matplotlib],
Jinja, Pytest, and Xarray [@xarray], to deliver a robust and user-friendly
workflow management tool for Nek5000. These packages provide a powerful
foundation for Snek5000, enabling its seamless integration with existing
Python-based workflows and enhancing its overall usability.

## A FluidSim extension

Snek5000 is based on the CDF framework Fluidsim [@fluidsim], which introduces
the concept of "Fluidsim solvers". A Fluidsim solver consists of few files
Snek5000 is based on the CFD framework FluidSim [@fluidsim], which introduces
the concept of "FluidSim solvers". A FluidSim solver consists of few files
describing a set of potential and similar simulations. A concrete simulation
can be created via a simple and generic Python API. For example, for the
`snek5000-cbox` solver,
Expand All @@ -70,36 +122,36 @@ params = Simul.create_default_params()
sim = Simul(params)
```

During the instanciation of the `Simul` object, all the directories and files
During the instantiation of the `Simul` object, all the directories and files
necessary to run the simulation have been created. We see that Snek5000 can be
seen as an advanced template system. Then, one can launch the Nek5000
simulation with `sim.make.exec("run_fg")` . Since the simulations generated by
a solver share some similarities (for example some aspects of the geometry and
the equations), the solver can contain code to create, plot and postprocess
output data, which is accessible through objects contained in `sim.output` .

Snek5000 extends Fluidsim to enable users to create Fluidsim solvers for
simulations based on the Nek5000 code. Open-source solvers, such as
[snek5000-phill](https://github.com/snek5000/snek5000-phill),
[snek5000-cbox](https://github.com/snek5000/snek5000-cbox), and
[snek5000-tgv](https://github.com/snek5000/snek5000/tree/main/docs/examples/snek5000-tgv),
are available, and users can easily develop custom solvers tailored to their
specific Nek5000 cases. This flexibility allows researchers to adapt Snek5000
to a wide range of fluid dynamics problems and simulation requirements. For
example, Snek5000-cbox has been used for a study on linear stability of
vertical convection [@Khoubani2023vertical].
simulation with `sim.make.exec("run_fg")`. Further details of these two stages
can be found in the Jinja templates and Snakemake rules, which are responsible for
source-code generation and execution of Nek5000 commands respectively. These
files are organized under the sub-package
[`snek5000.resources`](https://snek5000.readthedocs.io/en/stable/_generated/snek5000.resources.html)
and are both re-usable and extendable.

Since the simulations generated by a solver share some similarities (for
example some aspects of the geometry and the equations), the solver can contain
code to create, plot and post-process output data, which is accessible through
objects contained in `sim.output`.

## Streamlined simulation management

With a Snek5000-Fluidsim solver, users can efficiently launch and restart
simulations using Python scripts and a terminal command ( `snek-restart` ).
With a Snek5000-FluidSim solver, users can efficiently launch and restart
simulations using Python scripts and a terminal command (
[`snek-restart`](https://snek5000.readthedocs.io/en/latest/how-to/restart.html)
).
Snek5000 handles all file operations, such as directory creation and file
copying. This streamlines the process of managing simulations, freeing up time
and resources for data analysis and understanding the underlying physics.

## Loading simulations for data visualization, post-processing and data analysis

It is very easy to "load" an existing simulation, i.e. to recreate a Python
It is very easy to ["load" an existing
simulation](https://snek5000.readthedocs.io/en/latest/tuto_phill_script.html#load-the-simulation),
i.e. to recreate a Python
object `sim` similar to the one used to create the simulation. This can be done
with the function `snek5000.load` or with the command `snek-ipy-load` , which
opens a IPython session with a `sim` variable. Snek5000 simplifies the process
Expand All @@ -117,16 +169,7 @@ comparison between different simulations. This streamlined approach to data
analysis enables researchers to gain valuable insights into their simulations
and focus on the underlying physical processes.

## Powered by Python Packages

Snek5000 leverages a variety of Python packages, including Snakemake
[@snakemake], Fluidsim [@fluidsim], Pymech [@pymech], Matplotlib [@matplotlib],
Jinja, Pytest, and Xarray [@xarray], to deliver a robust and user-friendly
workflow management tool for Nek5000. These packages provide a powerful
foundation for Snek5000, enabling its seamless integration with existing
Python-based workflows and enhancing its overall usability.

## Tutorials and Documentation
## Tutorials and documentation

Snek5000 provides comprehensive
[documentation](https://snek5000.readthedocs.io/) and tutorials to guide users
Expand All @@ -136,7 +179,18 @@ features and customization options. By providing thorough documentation,
Snek5000 promotes its widespread adoption and fosters a community of users and
developers.

## Future Developments and Enhancements
Open-source solvers, such as
[snek5000-phill](https://github.com/snek5000/snek5000-phill),
[snek5000-cbox](https://github.com/snek5000/snek5000-cbox), and
[snek5000-tgv](https://github.com/snek5000/snek5000/tree/main/docs/examples/snek5000-tgv),
are available, and [users can easily develop custom
solvers](https://snek5000.readthedocs.io/en/latest/tuto_packaging.html)
tailored to their specific Nek5000 cases. This flexibility allows researchers
to adapt Snek5000 to a wide range of fluid dynamics problems and simulation
requirements. For example, Snek5000-cbox has been used for a study on linear
stability of vertical convection [@Khoubani2023vertical].

## Future developments and enhancements

The Snek5000 development team is committed to continuously improving the
package and incorporating user feedback to address evolving needs within the
Expand All @@ -147,64 +201,25 @@ principles in mind. By leveraging inheritance and object-oriented programming,
Snek5000 is well-positioned to accommodate the adoption of the next-generation
NekRS [@nekrs] code, developed by the Nek5000 team, while maintaining its
existing structure and functionality. This adaptability ensures that the
framework stays up-to-date with the latest advancements in the field.

Moreover, FluidsimFoam, currently under development, is a promising Fluidsim
extension similar to Snek5000 designed to bridge the gap between Fluidsim and
OpenFOAM [@openfoam]. This extension allows users to create custom Fluidsim
solvers specifically tailored for simulations on the widely-used open-source
CFD software package, OpenFOAM. By harnessing the strengths of Python and
OpenFOAM, FluidsimFoam aims to provide a versatile and user-friendly
framework stays up-to-date with the latest advancements in the field. In the
future, Snek5000 can also function as a compatibility layer to migrate to
upcoming rewrites of Nek5000 which require some extra input files [@nekrs;@neko].

The design principles of Snek5000 has inspired
[FluidsimFoam](https://fluidsimfoam.readthedocs.io/), currently under
development, a promising FluidSim extension to bridge the gap between
FluidSim and OpenFOAM [@openfoam]. This extension allows users to create custom
FluidSim solvers specifically tailored for simulations on the widely-used
open-source CFD software package, OpenFOAM. By harnessing the strengths of
Python and OpenFOAM, FluidsimFoam aims to provide a versatile and user-friendly
environment for conducting computational fluid dynamics simulations, broadening
the scope of potential applications.

# Statement of need

## State of art

The CFD framework Nek5000 is the culmination of several decades of development.
Nek5000 solvers can produce high-fidelity simulations owing to spectral-element
method and can scale up to several thousands of cores [@nek5000_scaling].
Development of Nek5000 is primarily driven by performance optimization,
incorporating new numerical method whilst following a keep-it-simple approach
to ensure portability across various HPC machines.

Development of Nek5000 continues to this day with efforts underway to use GPUs
[@nek5000_openacc] and to rewrite it in C++ [@nekrs] and modern Fortran
[@neko].

To the best of the authors' knowledge no other actively maintained and reusable
approaches have been made to wrap Nek5000. A project called `nekpy` [@nekpy]
was the only known prior work resembling Snek5000, where it uses templated
source files to fill in parameters.

## Better user-experience with Snek5000

Snek5000 enhances the user-experience by addressing the following downsides of
using a typical Nek5000 solver:

1. Only a limited set of utilities come packaged with Nek5000 and those focus
on compilation and mesh-generation. As a result, usability of Nek5000 takes a
hit and a practitioner is left to construct a homebrewn solution to conduct
exploratory research and parametric studies. Snek5000 functions as a workflow
manager for assisting packaging, setup, compilation and post-processing aspects
of a simulation.

2. The simulation parameters are spread in at least three different files (
`*.box`, `*.par` and `SIZE`). Some parameters have short and cryptic names (for
example, `lx1`, `lxd`, etc.) and are dependent on each other. Snek5000 tries to
provide good defaults and [dynamically set some of these
parameters](https://snek5000.readthedocs.io/en/stable/_generated/snek5000.operators.html#snek5000.operators.Operators)
when possible, allowing a user to get started without the need to master the
whole manual.

In the future, Snek5000 can also function as a compatibility layer to migrate
to upcoming rewrites of Nek5000 which require some extra input files [@nekrs,
@neko].

# Acknowledgements

The authors acknowledge the numerical support provided by Olivier De-Marchi,
The financial support of the SeRC ExABL project which made this project possible
is duly acknowledged.
The authors also acknowledge the numerical support provided by Olivier De-Marchi,
Gabriel Moreau and Cyrille Bonamy of the LEGI informatics team. This project
was funded by the project LEFE/IMAGO-2019 contract COSTRIO. AK acknowledges the
finance of his PhD thesis from the school STEP of the University Grenoble
Expand Down

0 comments on commit 6060655

Please sign in to comment.