From 6d4aa9e63bfae0a265d21bbbb5ef74fea1a796ad Mon Sep 17 00:00:00 2001 From: paugier Date: Fri, 5 Jan 2024 11:08:29 +0100 Subject: [PATCH] Update documentation --- CHANGES.md | 299 +++++++++++++++++++++++++++++++++++ CHANGES.rst | 336 ---------------------------------------- README.md | 69 +++++---- doc/HOWTO_build_the_doc | 8 - doc/changes.md | 1 + doc/changes.rst | 1 - doc/conf.py | 27 +++- doc/index.md | 191 +++++++++++++++++++++++ doc/index.rst | 182 ---------------------- 9 files changed, 556 insertions(+), 558 deletions(-) create mode 100644 CHANGES.md delete mode 100644 CHANGES.rst delete mode 100644 doc/HOWTO_build_the_doc create mode 120000 doc/changes.md delete mode 100644 doc/changes.rst create mode 100644 doc/index.md delete mode 100644 doc/index.rst diff --git a/CHANGES.md b/CHANGES.md new file mode 100644 index 000000000..5a03da2e3 --- /dev/null +++ b/CHANGES.md @@ -0,0 +1,299 @@ +# Release notes + +All notable changes to this project will be documented in this file. + +The format is based on [Keep a +Changelog](https://keepachangelog.com/en/1.0.0/), and this project +adheres to [Semantic +Versioning](https://semver.org/spec/v2.0.0.html). + +% Type of changes + +% --------------- + +% Added Added for new features. + +% Changed Changed for changes in existing functionality. + +% Deprecated Deprecated for soon-to-be removed features. + +% Removed Removed for now removed features. + +% Fixed Fixed for any bug fixes. + +% Security Security in case of vulnerabilities. + +% Unreleased_ + +% ----------- + +% towncrier release notes start + +## [0.7.4] (2023-10-05) + +- [!342](https://foss.heptapod.net/fluiddyn/fluidsim/-/merge_requests/342) + Refactoring and improvements spectra ns2d and ns3d. +- [!335](https://foss.heptapod.net/fluiddyn/fluidsim/-/merge_requests/335) + Improvement `fluidsim-ipy-load` which can now take a path as argument +- Code improvements, bug fixes (in particular for movies) and compatibility + with new Matplotlib + +## [0.7.3] (2023-05-24) + +- Official support for only Python 3.9, 3.10 and 3.11. +- Few improvements for [Fluidsimfoam](https://foss.heptapod.net/fluiddyn/fluidsimfoam). + +## [0.7.2] (2023-01-05) + +- New module {mod}`fluidsim_core.output.remaining_clock_time`. + +## [0.7.1] (2022-11-30) + +- [!325](https://foss.heptapod.net/fluiddyn/fluidsim/-/merge_requests/325) + Small changes in restarts utilities for Snek5000 0.8.0. + +## [0.7.0] (2022-11-23) + +- [!316](https://foss.heptapod.net/fluiddyn/fluidsim/-/merge_requests/316) + Interactive movies + +- [!317](https://foss.heptapod.net/fluiddyn/fluidsim/-/merge_requests/317) + and [!318](https://foss.heptapod.net/fluiddyn/fluidsim/-/merge_requests/318) + + - Refactor movie code in fluidsim-core with several improvements and bugfixes + ({mod}`fluidsim_core.output.movies` and {mod}`fluidsim_core.output.phys_fields`) + - Movies for Snek5000 + +- [!319](https://foss.heptapod.net/fluiddyn/fluidsim/-/merge_requests/319) + Refactor restart code in fluidsim-core + ({class}`fluidsim_core.scripts.restart.RestarterABC` and + {class}`fluidsim.util.scripts.restart.Restarter`) + +- [!320](https://foss.heptapod.net/fluiddyn/fluidsim/-/merge_requests/320) Restart for Snek5000 in fluidsim-core + +- [!321](https://foss.heptapod.net/fluiddyn/fluidsim/-/merge_requests/321) command `fluidsim-ipy-load`. + +## [0.6.1] (2022-09-07) + +- Turbulence models with `extend_simul_class` ([!308](https://foss.heptapod.net/fluiddyn/fluidsim/-/merge_requests/308), see + {mod}`fluidsim.base.turb_model`) + +- Kolmogorov forcing ([!307](https://foss.heptapod.net/fluiddyn/fluidsim/-/merge_requests/307), see + {mod}`fluidsim.base.forcing.kolmogorov`) + +- Output {mod}`fluidsim.base.output.horiz_means` ([!309](https://foss.heptapod.net/fluiddyn/fluidsim/-/merge_requests/309)) + +- Output {mod}`fluidsim.base.output.cross_corr3d` ([!295](https://foss.heptapod.net/fluiddyn/fluidsim/-/merge_requests/295)) + +- Better support for 3d FFT libs based on pencil decompositions ([!283](https://foss.heptapod.net/fluiddyn/fluidsim/-/merge_requests/283)) + +- [!289](https://foss.heptapod.net/fluiddyn/fluidsim/-/merge_requests/289) + + - File `is_being_advanced.lock` in the result directory during the runs + - Better handling of signals (`SIGINT`, `SIGTERM` and `SIGUSR2`) + - `fluidsim-restart` supports idempotent jobs (OAR scheduler) + - {func}`fluidsim.util.get_dataframe_from_paths` using `sim.output.get_mean_values` + - {func}`fluidsim.util.get_last_estimated_remaining_duration` + - `sim.output.spatiotemporal_spectra.get_spectra` + +- CI also running on Github Actions ([!224](https://foss.heptapod.net/fluiddyn/fluidsim/-/merge_requests/224)) + +- Various fixes (in particular energy steps with `fluidsim-restart`) + +- Various plot improvements (in particular `plot_omega_emp` in {mod}`fluidsim.base.output.spatiotemporal_spectra`) + +## [0.6.0] (2022-02-07) + +- New subpackage {mod}`fluidsim.util.scripts` and module + {mod}`fluidsim.util.scripts.turb_trandom_anisotropic` ([!255](https://foss.heptapod.net/fluiddyn/fluidsim/-/merge_requests/255)). + +- Entry points console_scripts `fluidsim-restart` ([!261](https://foss.heptapod.net/fluiddyn/fluidsim/-/merge_requests/261)) and + `fluidsim-modif-resolution` ([!263](https://foss.heptapod.net/fluiddyn/fluidsim/-/merge_requests/263)). + +- Forcing {class}`fluidsim.base.forcing.anisotropic.TimeCorrelatedRandomPseudoSpectralAnisotropic` + (extension for 3d solvers + new parameter `params.forcing.tcrandom_anisotropic.delta_angle`) + ([!247](https://foss.heptapod.net/fluiddyn/fluidsim/-/merge_requests/247)). + +- New projection functions (toroidal/poloidal) in + {mod}`fluidsim.operators.operators3d` ([!247](https://foss.heptapod.net/fluiddyn/fluidsim/-/merge_requests/247)). + +- [! 250](https://foss.heptapod.net/fluiddyn/fluidsim/-/merge_requests/250): + New parameter `params.projection` for ns3d solvers. + + The equations (`ns3d`, `ns3d.strat` and `ns3d.bouss`) can be modified by + projecting the solutions on the poloidal or toroidal manifolds. + +- Faster loading at Python start ([!264](https://foss.heptapod.net/fluiddyn/fluidsim/-/merge_requests/264)) + +- Various bugfixes, in particular related to restart. + +## [0.5.1] (2021-11-05) + +- [!244](https://foss.heptapod.net/fluiddyn/fluidsim/-/merge_requests/244): + Taylor Green forcing for ns3d solvers +- fluidsim-core: change order for the initialization of the parameters: Simul + class before the subclasses. + +## [0.5.0] (2021-09-29) + +### Added + +- [!200](https://foss.heptapod.net/fluiddyn/fluidsim/-/merge_requests/200) : + New mechanism to easily extend a Simul class (subpackage + {mod}`fluidsim.extend_simul`). + +- [!201](https://foss.heptapod.net/fluiddyn/fluidsim/-/merge_requests/201) : + Improve FluidSim Core API with a warning and a convenience function + + - Warnings added when `_set_attrib` is called instead of `_set_child` by + a InfoSolver instance + - New function `iter_complete_params` + +- Output `spatial_means_regions_milestone.py` using {mod}`fluidsim.extend_simul`. + +- New options `no_vz_kz0` and `NO_KY0`. + +- Spatiotemporal spectra and many improvements for the temporal spectra for + ns3d and ns2d solvers by Jason Reneuve ([!202](https://foss.heptapod.net/fluiddyn/fluidsim/-/merge_requests/202), ...) + +- Better Burgers1d solvers (by Ashwin Vishnu) + +### Changed + +- [!200](https://foss.heptapod.net/fluiddyn/fluidsim/-/merge_requests/200) : + (internal) {class}`fluidsim_core.info.InfoSolverCore`: `__init__` now fully + initializes the instance (calling the method `complete_with_classes`). New + keyword argument `only_root` to initialize only the root level. +- [!211](https://foss.heptapod.net/fluiddyn/fluidsim/-/merge_requests/211) : + Replace for ns2d solvers the output `frequency_spectra` (nearly not used) by + the newer output `temporal_spectra` written for ns3d solvers. + +### Fixed + +- Many bugfixes! + +## [0.4.1] (2021-02-02) + +Few bugfixes and [!192](https://foss.heptapod.net/fluiddyn/fluidsim/-/merge_requests/192) +(temporal spectra for ns3d solvers). + +## [0.4.0] (2021-01-11) + +- [!186](https://foss.heptapod.net/fluiddyn/fluidsim/-/merge_requests/186): Package split into `fluidsim-core` and `fluidsim` + + - Base classes and abstract base classes defined for `params`, `info_solver`, `sim`, `output` instances + - Entry points as a *plugin framework* to register FluidSim solvers + +- `base/output/print_stdout.py`: better regularity saving + method `plot_clock_times` + +- Able to run bigger simulations (`2034x2034x384`) on the Occigen cluster (in + particular new function `fluidsim.modif_resolution_from_dir_memory_efficient`) + +## [0.3.3] (2020-10-15) + +- Bugfixes and optimizations (in particular for ns3d solvers) +- Forcing WATU Coriolis and Milestone for ns3d.strat +- pyproject.toml and isolated build +- Timestepping using phase-shifting for dealiasing +- Improve regularity of saving for some outputs + +## [0.3.2] (2019-11-14) + +- Bug fixes and Transonic 0.4 compatibility + +## [0.3.1] (2019-03-07) + +- Windows compatibility +- Only Python code (stop using Cython) +- Improvements ns2d.strat + +## [0.3.0] (2019-01-31) + +- Drop support for Python 2.7! +- Accelerated by Transonic & Pythran (also time stepping) +- Better setup.py (by Ashwin Vishnu) +- Improvement ns2d.strat (by Miguel Calpe Linares) +- Much better testing (internal, CI, compatibility pytest, coverage 87%) +- Fix several bugs :-) +- New function load_for_restart + +## [0.2.2] (2018-07-01) + +- Let fluidfft decides which FFT class to use (dependency fluidfft >= 0.2.4) + +## [0.2.1] (2018-05-24) + +- IPython magic commands (by Ashwin Vishnu). +- Bugfix divergence-free flow and time_stepping in ns3d solvers. + +## [0.2.0] (2018-05-04) + +- Many bugfixes and nicer code (using the Python code formatter Black). +- Faster ns3d solver. +- ns2d.strat + anisotropic forcing (by Miguel Calpe Linares). +- Nicer forcing parameters. + +## 0.1.1 + +- Better `phys_fields.plot` and `phys_fields.animate` (by Ashwin Vishnu and + Miguel Calpe Linares). +- Faster installation (with configuration file). +- Installation without mpi4py. +- Faster time stepping with less memory allocation. +- Much faster ns3d solvers. + +## 0.1.0 + +- Uses fluidfft and Pythran + +## 0.0.5 + +- Compatible fluiddyn 0.1.2 + +## 0.0.4 + +- 0D models (predaprey, lorenz) +- Continuous integration, unittests with bitbucket-pipelines + +## 0.0.3a0 + +Merge with geofluidsim (Ashwin Vishnu Mohanan repository) + +- Movies. +- Preprocessing of parameters. +- Less bugs. + +## 0.0.2a1 + +- Use a cleaner parameter container class (fluiddyn 0.0.8a1). + +## 0.0.2a0 + +- SetOfVariables inherits from numpy.ndarray. +- The creation of default parameter has been simplified and is done + by a class function Simul.create_default_params. + +## 0.0.1a + +- Split the package fluiddyn between one base package and specialized + packages. + +[0.2.0]: https://foss.heptapod.net/fluiddyn/fluidsim/-/compare/0.1.1...0.2.0 +[0.2.1]: https://foss.heptapod.net/fluiddyn/fluidsim/-/compare/0.2.0...0.2.1 +[0.2.2]: https://foss.heptapod.net/fluiddyn/fluidsim/-/compare/0.2.1...0.2.2 +[0.3.0]: https://foss.heptapod.net/fluiddyn/fluidsim/-/compare/0.2.2...0.3.0 +[0.3.1]: https://foss.heptapod.net/fluiddyn/fluidsim/-/compare/0.3.0...0.3.1 +[0.3.2]: https://foss.heptapod.net/fluiddyn/fluidsim/-/compare/0.3.1...0.3.2 +[0.3.3]: https://foss.heptapod.net/fluiddyn/fluidsim/-/compare/0.3.2...0.3.3 +[0.4.0]: https://foss.heptapod.net/fluiddyn/fluidsim/-/compare/0.3.3...0.4.0 +[0.4.1]: https://foss.heptapod.net/fluiddyn/fluidsim/-/compare/0.4.0...0.4.1 +[0.5.0]: https://foss.heptapod.net/fluiddyn/fluidsim/-/compare/0.4.1...0.5.0 +[0.5.1]: https://foss.heptapod.net/fluiddyn/fluidsim/-/compare/0.5.0...0.5.1 +[0.6.0]: https://foss.heptapod.net/fluiddyn/fluidsim/-/compare/0.5.1...0.6.0 +[0.6.1]: https://foss.heptapod.net/fluiddyn/fluidsim/-/compare/0.6.0...0.6.1 +[0.7.0]: https://foss.heptapod.net/fluiddyn/fluidsim/-/compare/0.6.1...0.7.0 +[0.7.1]: https://foss.heptapod.net/fluiddyn/fluidsim/-/compare/0.7.0...0.7.1 +[0.7.2]: https://foss.heptapod.net/fluiddyn/fluidsim/-/compare/0.7.1...0.7.2 +[0.7.3]: https://foss.heptapod.net/fluiddyn/fluidsim/-/compare/0.7.2...0.7.3 +[0.7.4]: https://foss.heptapod.net/fluiddyn/fluidsim/-/compare/0.7.3...0.7.4 +[unreleased]: https://foss.heptapod.net/fluiddyn/fluidsim/-/compare/0.7.3...branch%2Fdefault diff --git a/CHANGES.rst b/CHANGES.rst deleted file mode 100644 index d9dea0350..000000000 --- a/CHANGES.rst +++ /dev/null @@ -1,336 +0,0 @@ -Changes -======= - -All notable changes to this project will be documented in this file. - -The format is based on `Keep a -Changelog `__, and this project -adheres to `Semantic -Versioning `__. - -.. Type of changes -.. --------------- -.. Added Added for new features. -.. Changed Changed for changes in existing functionality. -.. Deprecated Deprecated for soon-to-be removed features. -.. Removed Removed for now removed features. -.. Fixed Fixed for any bug fixes. -.. Security Security in case of vulnerabilities. - - -.. Unreleased_ -.. ----------- - -.. towncrier release notes start - -0.7.4_ (2023-10-05) -------------------- - -- `!342 `__ - Refactoring and improvements spectra ns2d and ns3d. - -- `!335 `__ - Improvement `fluidsim-ipy-load` which can now take a path as argument - -- Code improvements, bug fixes (in particular for movies) and compatibility - with new Matplotlib - -0.7.3_ (2023-05-24) -------------------- - -- Official support for only Python 3.9, 3.10 and 3.11. - -- Few improvements for `Fluidsimfoam - `_. - -0.7.2_ (2023-01-05) -------------------- - -- New module :mod:`fluidsim_core.output.remaining_clock_time`. - -0.7.1_ (2022-11-30) -------------------- - -- `!325 `__ - Small changes in restarts utilities for Snek5000 0.8.0. - -0.7.0_ (2022-11-23) -------------------- - -- `!316 `__ - Interactive movies - -- `!317 `__ - and `!318 `__ - - - Refactor movie code in fluidsim-core with several improvements and bugfixes - (:mod:`fluidsim_core.output.movies` and :mod:`fluidsim_core.output.phys_fields`) - - Movies for Snek5000 - -- `!319 `__ - Refactor restart code in fluidsim-core - (:class:`fluidsim_core.scripts.restart.RestarterABC` and - :class:`fluidsim.util.scripts.restart.Restarter`) - -- `!320 `__ Restart for Snek5000 in fluidsim-core - -- `!321 `__ command ``fluidsim-ipy-load``. - -0.6.1_ (2022-09-07) -------------------- - -- Turbulence models with ``extend_simul_class`` (`!308 - `__, see - :mod:`fluidsim.base.turb_model`) - -- Kolmogorov forcing (`!307 - `__, see - :mod:`fluidsim.base.forcing.kolmogorov`) - -- Output :mod:`fluidsim.base.output.horiz_means` (`!309 `__) - -- Output :mod:`fluidsim.base.output.cross_corr3d` (`!295 `__) - -- Better support for 3d FFT libs based on pencil decompositions (`!283 `__) - -- `!289 `__ - - - File ``is_being_advanced.lock`` in the result directory during the runs - - Better handling of signals (``SIGINT``, ``SIGTERM`` and ``SIGUSR2``) - - ``fluidsim-restart`` supports idempotent jobs (OAR scheduler) - - :func:`fluidsim.util.get_dataframe_from_paths` using ``sim.output.get_mean_values`` - - :func:`fluidsim.util.get_last_estimated_remaining_duration` - - ``sim.output.spatiotemporal_spectra.get_spectra`` - -- CI also running on Github Actions (`!224 `__) - -- Various fixes (in particular energy steps with ``fluidsim-restart``) - -- Various plot improvements (in particular ``plot_omega_emp`` in :mod:`fluidsim.base.output.spatiotemporal_spectra`) - -0.6.0_ (2022-02-07) -------------------- - -- New subpackage :mod:`fluidsim.util.scripts` and module - :mod:`fluidsim.util.scripts.turb_trandom_anisotropic` (`!255 - `__). - -- Entry points console_scripts ``fluidsim-restart`` (`!261 - `__) and - ``fluidsim-modif-resolution`` (`!263 - `__). - -- Forcing :class:`fluidsim.base.forcing.anisotropic.TimeCorrelatedRandomPseudoSpectralAnisotropic` - (extension for 3d solvers + new parameter ``params.forcing.tcrandom_anisotropic.delta_angle``) - (`!247 `__). - -- New projection functions (toroidal/poloidal) in - :mod:`fluidsim.operators.operators3d` (`!247 - `__). - -- `! 250 `__: - New parameter ``params.projection`` for ns3d solvers. - - The equations (``ns3d``, ``ns3d.strat`` and ``ns3d.bouss``) can be modified by - projecting the solutions on the poloidal or toroidal manifolds. - -- Faster loading at Python start (`!264 - `__) - -- Various bugfixes, in particular related to restart. - -0.5.1_ (2021-11-05) -------------------- - -- `!244 `__: - Taylor Green forcing for ns3d solvers -- fluidsim-core: change order for the initialization of the parameters: Simul - class before the subclasses. - -0.5.0_ (2021-09-29) -------------------- - -Added -~~~~~ - -* `!200 `__ : - New mechanism to easily extend a Simul class (subpackage - :mod:`fluidsim.extend_simul`). - -* `!201 `__ : - Improve FluidSim Core API with a warning and a convenience function - - - Warnings added when ``_set_attrib`` is called instead of ``_set_child`` by - a InfoSolver instance - - New function ``iter_complete_params`` - -* Output ``spatial_means_regions_milestone.py`` using :mod:`fluidsim.extend_simul`. - -* New options ``no_vz_kz0`` and ``NO_KY0``. - -* Spatiotemporal spectra and many improvements for the temporal spectra for - ns3d and ns2d solvers by Jason Reneuve (`!202 - `__, ...) - -* Better Burgers1d solvers (by Ashwin Vishnu) - -Changed -~~~~~~~ - -* `!200 `__ : - (internal) :class:`fluidsim_core.info.InfoSolverCore`: ``__init__`` now fully - initializes the instance (calling the method ``complete_with_classes``). New - keyword argument ``only_root`` to initialize only the root level. - -* `!211 `__ : - Replace for ns2d solvers the output ``frequency_spectra`` (nearly not used) by - the newer output ``temporal_spectra`` written for ns3d solvers. - -Fixed -~~~~~ - -* Many bugfixes! - -0.4.1_ (2021-02-02) -------------------- - -Few bugfixes and `!192 `__ -(temporal spectra for ns3d solvers). - -0.4.0_ (2021-01-11) -------------------- - -* `!186 `__: Package split into ``fluidsim-core`` and ``fluidsim`` - - - Base classes and abstract base classes defined for ``params``, ``info_solver``, ``sim``, ``output`` instances - - Entry points as a *plugin framework* to register FluidSim solvers - -* ``base/output/print_stdout.py``: better regularity saving + method ``plot_clock_times`` - -* Able to run bigger simulations (``2034x2034x384``) on the Occigen cluster (in - particular new function ``fluidsim.modif_resolution_from_dir_memory_efficient``) - -0.3.3_ (2020-10-15) -------------------- - -- Bugfixes and optimizations (in particular for ns3d solvers) -- Forcing WATU Coriolis and Milestone for ns3d.strat -- pyproject.toml and isolated build -- Timestepping using phase-shifting for dealiasing -- Improve regularity of saving for some outputs - -0.3.2_ (2019-11-14) -------------------- - -- Bug fixes and Transonic 0.4 compatibility - -0.3.1_ (2019-03-07) -------------------- - -- Windows compatibility -- Only Python code (stop using Cython) -- Improvements ns2d.strat - -0.3.0_ (2019-01-31) -------------------- - -- Drop support for Python 2.7! -- Accelerated by Transonic & Pythran (also time stepping) -- Better setup.py (by Ashwin Vishnu) -- Improvement ns2d.strat (by Miguel Calpe Linares) -- Much better testing (internal, CI, compatibility pytest, coverage 87%) -- Fix several bugs :-) -- New function load_for_restart - -0.2.2_ (2018-07-01) -------------------- - -- Let fluidfft decides which FFT class to use (dependency fluidfft >= 0.2.4) - -0.2.1_ (2018-05-24) -------------------- - -- IPython magic commands (by Ashwin Vishnu). -- Bugfix divergence-free flow and time_stepping in ns3d solvers. - -0.2.0_ (2018-05-04) -------------------- - -- Many bugfixes and nicer code (using the Python code formatter Black). -- Faster ns3d solver. -- ns2d.strat + anisotropic forcing (by Miguel Calpe Linares). -- Nicer forcing parameters. - -0.1.1 ------ - -- Better ``phys_fields.plot`` and ``phys_fields.animate`` (by Ashwin Vishnu and - Miguel Calpe Linares). -- Faster installation (with configuration file). -- Installation without mpi4py. -- Faster time stepping with less memory allocation. -- Much faster ns3d solvers. - -0.1.0 ------ - -- Uses fluidfft and Pythran - -0.0.5 ------ - -- Compatible fluiddyn 0.1.2 - -0.0.4 ------ - -- 0D models (predaprey, lorenz) -- Continuous integration, unittests with bitbucket-pipelines - -0.0.3a0 -------- - -Merge with geofluidsim (Ashwin Vishnu Mohanan repository) - -- Movies. -- Preprocessing of parameters. -- Less bugs. - -0.0.2a1 -------- - -- Use a cleaner parameter container class (fluiddyn 0.0.8a1). - -0.0.2a0 -------- - -- SetOfVariables inherits from numpy.ndarray. - -- The creation of default parameter has been simplified and is done - by a class function Simul.create_default_params. - -0.0.1a ------- - -- Split the package fluiddyn between one base package and specialized - packages. - -.. _Unreleased: https://foss.heptapod.net/fluiddyn/fluidsim/-/compare/0.7.3...branch%2Fdefault -.. _0.7.4: https://foss.heptapod.net/fluiddyn/fluidsim/-/compare/0.7.3...0.7.4 -.. _0.7.3: https://foss.heptapod.net/fluiddyn/fluidsim/-/compare/0.7.2...0.7.3 -.. _0.7.2: https://foss.heptapod.net/fluiddyn/fluidsim/-/compare/0.7.1...0.7.2 -.. _0.7.1: https://foss.heptapod.net/fluiddyn/fluidsim/-/compare/0.7.0...0.7.1 -.. _0.7.0: https://foss.heptapod.net/fluiddyn/fluidsim/-/compare/0.6.1...0.7.0 -.. _0.6.1: https://foss.heptapod.net/fluiddyn/fluidsim/-/compare/0.6.0...0.6.1 -.. _0.6.0: https://foss.heptapod.net/fluiddyn/fluidsim/-/compare/0.5.1...0.6.0 -.. _0.5.1: https://foss.heptapod.net/fluiddyn/fluidsim/-/compare/0.5.0...0.5.1 -.. _0.5.0: https://foss.heptapod.net/fluiddyn/fluidsim/-/compare/0.4.1...0.5.0 -.. _0.4.1: https://foss.heptapod.net/fluiddyn/fluidsim/-/compare/0.4.0...0.4.1 -.. _0.4.0: https://foss.heptapod.net/fluiddyn/fluidsim/-/compare/0.3.3...0.4.0 -.. _0.3.3: https://foss.heptapod.net/fluiddyn/fluidsim/-/compare/0.3.2...0.3.3 -.. _0.3.2: https://foss.heptapod.net/fluiddyn/fluidsim/-/compare/0.3.1...0.3.2 -.. _0.3.1: https://foss.heptapod.net/fluiddyn/fluidsim/-/compare/0.3.0...0.3.1 -.. _0.3.0: https://foss.heptapod.net/fluiddyn/fluidsim/-/compare/0.2.2...0.3.0 -.. _0.2.2: https://foss.heptapod.net/fluiddyn/fluidsim/-/compare/0.2.1...0.2.2 -.. _0.2.1: https://foss.heptapod.net/fluiddyn/fluidsim/-/compare/0.2.0...0.2.1 -.. _0.2.0: https://foss.heptapod.net/fluiddyn/fluidsim/-/compare/0.1.1...0.2.0 diff --git a/README.md b/README.md index 17465e1b5..554182795 100644 --- a/README.md +++ b/README.md @@ -8,12 +8,12 @@ [![Heptapod CI](https://foss.heptapod.net/fluiddyn/fluidsim/badges/branch/default/pipeline.svg)](https://foss.heptapod.net/fluiddyn/fluidsim/-/pipelines) [![Github Actions](https://github.com/fluiddyn/fluidsim/actions/workflows/ci.yml/badge.svg?branch=branch/default)](https://github.com/fluiddyn/fluidsim/actions) -Fluidsim is an extensible framework for studying fluid dynamics with -numerical simulations using Python. Fluidsim is an object-oriented -library to develop solvers (mainly using pseudo-spectral methods) by -writing mainly Python code. The result is **very efficient** even -compared to a pure Fortran or C++ code since the time-consuming tasks -are performed by optimized compiled functions. +Fluidsim is an extensible framework for studying fluid dynamics with numerical +simulations using Python. Fluidsim is an object-oriented library to develop +Fluidsim "solvers" (i.e. Python packages solving equations) by writing mainly +Python code. The result is **very efficient** even compared to a pure Fortran +or C++ code since the time-consuming tasks are performed by optimized compiled +functions. **Documentation**: @@ -26,7 +26,7 @@ For a **basic installation** it should be sufficient to run: pip install fluidsim -or with conda: +or with [conda/mamba](https://github.com/conda-forge/miniforge): conda install -c conda-forge fluidsim @@ -59,7 +59,7 @@ used to extend existing solvers with Python interfaces such as We have created fluidsim to be **easy and nice to use and to develop**, **efficient** and **robust**. -*Keywords and ambitions*: fluid dynamics research with Python (>=3.6); +*Keywords and ambitions*: fluid dynamics research with Python (>=3.9); modular, object-oriented, collaborative, tested and documented, free and open-source software. @@ -78,23 +78,36 @@ project](https://openresearchsoftware.metajnl.com/articles/10.5334/jors.237/), and [FluidSim](https://openresearchsoftware.metajnl.com/articles/10.5334/jors.239/): - @article{fluiddyn, doi = {10.5334/jors.237}, year = {2019}, publisher - = {Ubiquity Press, Ltd.}, volume = {7}, author = {Pierre Augier and - Ashwin Vishnu Mohanan and Cyrille Bonamy}, title = {{FluidDyn}: A - Python Open-Source Framework for Research and Teaching in Fluid - Dynamics by Simulations, Experiments and Data Processing}, journal = - {Journal of Open Research Software} } - - @article{fluidfft, doi = {10.5334/jors.238}, year = {2019}, publisher - = {Ubiquity Press, Ltd.}, volume = {7}, author = {Ashwin Vishnu - Mohanan and Cyrille Bonamy and Pierre Augier}, title = {{FluidFFT}: - Common {API} (C\$mathplusmathplus\$ and Python) for Fast Fourier - Transform {HPC} Libraries}, journal = {Journal of Open Research - Software} } - - @article{fluidsim, doi = {10.5334/jors.239}, year = {2019}, publisher - = {Ubiquity Press, Ltd.}, volume = {7}, author = {Mohanan, Ashwin - Vishnu and Bonamy, Cyrille and Linares, Miguel Calpe and Augier, - Pierre}, title = {{FluidSim}: {Modular}, {Object}-{Oriented} {Python} - {Package} for {High}-{Performance} {CFD} {Simulations}}, journal = - {Journal of Open Research Software} } + @article{fluiddyn, + doi = {10.5334/jors.237}, + year = {2019}, + publisher = {Ubiquity Press, Ltd.}, + volume = {7}, + author = {Pierre Augier and Ashwin Vishnu Mohanan and Cyrille Bonamy}, + title = {{FluidDyn}: A Python Open-Source Framework for Research and Teaching in Fluid Dynamics + by Simulations, Experiments and Data Processing}, + journal = {Journal of Open Research Software} + } + + @article{fluidfft, + doi = {10.5334/jors.238}, + year = {2019}, + publisher = {Ubiquity Press, Ltd.}, + volume = {7}, + author = {Ashwin Vishnu Mohanan and Cyrille Bonamy and Pierre Augier}, + title = {{FluidFFT}: Common {API} (C$\mathplus\mathplus$ and Python) + for Fast Fourier Transform {HPC} Libraries}, + journal = {Journal of Open Research Software} + } + + @article{fluidsim, + doi = {10.5334/jors.239}, + year = {2019}, + publisher = {Ubiquity Press, Ltd.}, + volume = {7}, + author = {Mohanan, Ashwin Vishnu and Bonamy, Cyrille and Linares, Miguel + Calpe and Augier, Pierre}, + title = {{FluidSim}: {Modular}, {Object}-{Oriented} {Python} {Package} for + {High}-{Performance} {CFD} {Simulations}}, + journal = {Journal of Open Research Software} + } diff --git a/doc/HOWTO_build_the_doc b/doc/HOWTO_build_the_doc deleted file mode 100644 index 3725d5b44..000000000 --- a/doc/HOWTO_build_the_doc +++ /dev/null @@ -1,8 +0,0 @@ -Run in a terminal from this directory:: - - make html - -Also useful:: - - rm -rf generated - make clean diff --git a/doc/changes.md b/doc/changes.md new file mode 120000 index 000000000..cf547089d --- /dev/null +++ b/doc/changes.md @@ -0,0 +1 @@ +../CHANGES.md \ No newline at end of file diff --git a/doc/changes.rst b/doc/changes.rst deleted file mode 100644 index d9e113ec6..000000000 --- a/doc/changes.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../CHANGES.rst diff --git a/doc/conf.py b/doc/conf.py index 03d5d3d3b..09876c374 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -247,6 +247,14 @@ ' Citation', "https://doi.org/10.5334/jors.239", ), + ( + ' Mastodon', + "https://hachyderm.io/@fluiddyn", + ), + ( + ' Twitter', + "https://twitter.com/pyfluiddyn", + ), ], } @@ -327,9 +335,7 @@ # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). -man_pages = [ - ("index", "FluidSim", "FluidSim Documentation", ["Pierre Augier"], 1) -] +man_pages = [("index", "FluidSim", "FluidSim Documentation", ["Pierre Augier"], 1)] # If true, show URL addresses after external links. # man_show_urls = False @@ -380,3 +386,18 @@ for css_class in ("python", "ipython3", "default") ] ) + +myst_enable_extensions = [ + "amsmath", + # "attrs_inline", + # "colon_fence", + # "deflist", + "dollarmath", + # "fieldlist", + # "linkify", + # "replacements", + # "smartquotes", + # "strikethrough", + "substitution", + # "tasklist", +] diff --git a/doc/index.md b/doc/index.md new file mode 100644 index 000000000..cb92cc088 --- /dev/null +++ b/doc/index.md @@ -0,0 +1,191 @@ +--- +myst: + substitutions: + coverage: |- + ```{image} https://codecov.io/gh/fluiddyn/fluidsim/graph/badge.svg?token=dVfssLBgF2 + :alt: Code coverage + :target: https://codecov.io/gh/fluiddyn/fluidsim/ + ``` + release: |- + ```{image} https://img.shields.io/pypi/v/fluidsim.svg + :alt: Latest version + :target: https://pypi.org/project/fluidsim/ + ``` +--- + +# Fluidsim documentation + +## Overview + +Fluidsim is a framework for studying fluid dynamics with numerical simulations +using Python. It is part of the wider project +[FluidDyn](http://fluiddyn.readthedocs.io). + +Fluidsim is an object-oriented library to develop "solvers" (i.e. Python packages +solving equations) by writing mainly Python code. The result is **very efficient** +even compared to a pure Fortran or C++ code since the time-consuming tasks are +performed by optimized compiled functions. + +Fluidsim is a [HPC](https://en.wikipedia.org/wiki/High-performance_computing) code +written mostly in Python. It uses the library +[Fluidfft](http://fluidfft.readthedocs.io) to use very efficient FFT libraries. +Fluidfft is written in C++, Cython and Python. Fluidfft and fluidsim take +advantage of [Pythran](https://github.com/serge-sans-paille/pythran), a static +Python compiler which produces very efficient binaries by compiling Python via +C++11. Pythran is actually used in Fluidsim through +[Transonic](http://transonic.readthedocs.io), which is a new and cool project for +HPC with Python. + +An advantage of a CFD code written mostly in Python is that to run simulations and +analyze the results, the users communicate (possibly interactively) together and +with the machine with Python, which is nowadays among the best languages to do +these tasks. Moreover, it is much simpler and faster than with pure Fortran or C++ +codes to add any complicate analysis or to write a modified solver. + +We have created fluidsim to be **easy and nice to use and to develop**, highly +**efficient** and **robust**. + +Being a framework, Fluidsim can easily be extended in other packages to develop +other solvers (see for example the packages [snek5000] and [fluidsimfoam]). + +The list of solvers implemented using Fluidsim (see {mod}`fluidsim.solvers`, +[snek5000] and [fluidsimfoam]) gives a good idea of the versatility of this +framework. The main Fluidsim package contains mostly solvers solving equations +over a periodic space: + +- 2d and 3d incompressible Navier-Stokes equations, +- 2d and 3d incompressible Navier-Stokes equations under the Boussinesq + approximation (with a buoyancy variable), +- 2d and 3d stratified Navier-Stokes equations under the Boussinesq approximation + with constant Brunt-Väisälä frequency, +- 2d one-layer shallow-water equations + modified versions of these equations, +- 2d Föppl-von Kármán equations (elastic thin plate). + +### Metapapers and citations + +If you use FluidSim to produce scientific articles, please cite our metapapers +presenting the +[FluidDyn project](https://openresearchsoftware.metajnl.com/articles/10.5334/jors.237/), +[FluidFFT](https://openresearchsoftware.metajnl.com/articles/10.5334/jors.238/), +and +[FluidSim](https://openresearchsoftware.metajnl.com/articles/10.5334/jors.239/): + +```bibtex +@article{fluiddyn, +doi = {10.5334/jors.237}, +year = {2019}, +publisher = {Ubiquity Press, Ltd.}, +volume = {7}, +author = {Pierre Augier and Ashwin Vishnu Mohanan and Cyrille Bonamy}, +title = {{FluidDyn}: A Python Open-Source Framework for Research and Teaching in Fluid Dynamics + by Simulations, Experiments and Data Processing}, +journal = {Journal of Open Research Software} +} + +@article{fluidfft, +doi = {10.5334/jors.238}, +year = {2019}, +publisher = {Ubiquity Press, Ltd.}, +volume = {7}, +author = {Ashwin Vishnu Mohanan and Cyrille Bonamy and Pierre Augier}, +title = {{FluidFFT}: Common {API} (C$\mathplus\mathplus$ and Python) + for Fast Fourier Transform {HPC} Libraries}, +journal = {Journal of Open Research Software} +} + +@article{fluidsim, +doi = {10.5334/jors.239}, +year = {2019}, +publisher = {Ubiquity Press, Ltd.}, +volume = {7}, +author = {Mohanan, Ashwin Vishnu and Bonamy, Cyrille and Linares, Miguel + Calpe and Augier, Pierre}, +title = {{FluidSim}: {Modular}, {Object}-{Oriented} {Python} {Package} for + {High}-{Performance} {CFD} {Simulations}}, +journal = {Journal of Open Research Software} +} +``` + +```{toctree} +--- +caption: Get started +maxdepth: 1 +--- +install +tutorials +examples +faq +``` + +```{toctree} +--- +caption: Utilities +maxdepth: 1 +--- +test_bench_profile +ipynb/restart_modif_resol +``` + +## API Reference + +A pure-Python package `fluidsim-core` houses all the abstraction necessary to +define solvers. + +```{eval-rst} +.. autosummary:: + :toctree: generated/ + :caption: API reference fluidsim-core + + fluidsim_core +``` + +The package `fluidsim` provides a set of specialized solvers solvers, supporting +classes and functions. + +```{eval-rst} +.. autosummary:: + :toctree: generated/ + :caption: API reference fluidsim + + fluidsim.base + fluidsim.operators + fluidsim.solvers + fluidsim.util + fluidsim.magic + fluidsim.extend_simul + +``` + +```{toctree} +--- +caption: Fluidsim development +maxdepth: 1 +--- +changes +authors +Advice for FluidDyn developers +to_do +roadmap +release_process +``` + +## Links + +- [FluidDyn documentation](http://fluiddyn.readthedocs.io) +- [Fluidsim forge on Heptapod](https://foss.heptapod.net/fluiddyn/fluidsim) +- Fluidsim in PyPI {{release}} +- Unittest coverage {{coverage}} +- FluidDyn user chat room in + [Riot](https://riot.im/app/#/room/#fluiddyn-users:matrix.org) or + [Slack](https://fluiddyn.slack.com) +- [FluidDyn mailing list](https://www.freelists.org/list/fluiddyn) +- [FluidDyn on Twitter](https://twitter.com/pyfluiddyn) + +## Indices and tables + +- {ref}`genindex` +- {ref}`modindex` +- {ref}`search` + +[fluidsimfoam]: https://foss.heptapod.net/fluiddyn/fluidsimfoam +[snek5000]: https://github.com/exabl/snek5000/ diff --git a/doc/index.rst b/doc/index.rst deleted file mode 100644 index e15bc3580..000000000 --- a/doc/index.rst +++ /dev/null @@ -1,182 +0,0 @@ -.. FluidDyn documentation master file, created by - sphinx-quickstart on Sun Mar 2 12:15:31 2014. - -Fluidsim documentation -====================== - -Fluidsim is a framework for studying fluid dynamics with numerical -simulations using Python. It is part of the wider project `FluidDyn -`_. - -Fluidsim is an object-oriented library to develop solvers (mainly using -pseudo-spectral methods) by writing mainly Python code. The result is **very -efficient** even compared to a pure Fortran or C++ code since the -time-consuming tasks are performed by optimized compiled functions. - -Fluidsim is a `HPC `_ -code written mostly in Python. It uses the library `Fluidfft -`_ to use very efficient FFT libraries. -Fluidfft is written in C++, Cython and Python. Fluidfft and fluidsim take -advantage of `Pythran `_, a -static Python compiler which produces very efficient binaries by compiling -Python via C++11. Pythran is actually used in Fluidsim through `Transonic -`_, which is a new and cool project for HPC -with Python. - -An advantage of a CFD code written mostly in Python is that to run simulations -and analyze the results, the users communicate (possibly interactively) -together and with the machine with Python, which is nowadays among the best -languages to do these tasks. Moreover, it is much simpler and faster than with -pure Fortran or C++ codes to add any complicate analysis or to write a modified -solver. - -We have created fluidsim to be **easy and nice to use and to develop**, highly -**efficient** and **robust**. - -Fluidsim is a young package but the list of solvers already implemented (see -:mod:`fluidsim.solvers`) gives a good idea of the versatility of this -framework. However, currently, Fluidsim excels in particular in solving -equations over a periodic space: - -* 2d and 3d incompressible Navier-Stokes equations, - -* 2d and 3d incompressible Navier-Stokes equations under the Boussinesq - approximation (with a buoyancy variable), - -* 2d and 3d stratified Navier-Stokes equations under the Boussinesq - approximation with constant Brunt-Väisälä frequency, - -* 2d one-layer shallow-water equations + modified versions of these - equations, - -* 2d Föppl-von Kármán equations (elastic thin plate). - -Being a framework, Fluidsim can easily be extended in other packages to develop -other solvers (see for example the packages `snek5000 -`_, `fluidsimfoam -`_ and `fluidsim_ocean -`_). - - -**Metapapers and citations** - -If you use FluidSim to produce scientific articles, please cite our metapapers -presenting the `FluidDyn project -`__, -`FluidFFT -`__, and -`FluidSim -`__: - - -.. code-block :: bibtex - - @article{fluiddyn, - doi = {10.5334/jors.237}, - year = {2019}, - publisher = {Ubiquity Press, Ltd.}, - volume = {7}, - author = {Pierre Augier and Ashwin Vishnu Mohanan and Cyrille Bonamy}, - title = {{FluidDyn}: A Python Open-Source Framework for Research and Teaching in Fluid Dynamics - by Simulations, Experiments and Data Processing}, - journal = {Journal of Open Research Software} - } - - @article{fluidfft, - doi = {10.5334/jors.238}, - year = {2019}, - publisher = {Ubiquity Press, Ltd.}, - volume = {7}, - author = {Ashwin Vishnu Mohanan and Cyrille Bonamy and Pierre Augier}, - title = {{FluidFFT}: Common {API} (C$\mathplus\mathplus$ and Python) - for Fast Fourier Transform {HPC} Libraries}, - journal = {Journal of Open Research Software} - } - - @article{fluidsim, - doi = {10.5334/jors.239}, - year = {2019}, - publisher = {Ubiquity Press, Ltd.}, - volume = {7}, - author = {Mohanan, Ashwin Vishnu and Bonamy, Cyrille and Linares, Miguel - Calpe and Augier, Pierre}, - title = {{FluidSim}: {Modular}, {Object}-{Oriented} {Python} {Package} for - {High}-{Performance} {CFD} {Simulations}}, - journal = {Journal of Open Research Software} - } - -.. toctree:: - :maxdepth: 1 - :caption: User Guide - - install - tutorials - examples - test_bench_profile - ipynb/restart_modif_resol - faq - -Modules Reference ------------------ - -A pure-Python package ``fluidsim-core`` houses all the abstraction necessary to -define solvers. - -.. autosummary:: - :toctree: generated/ - - fluidsim_core - -The package ``fluidsim`` provides a set of specialized solvers solvers, -supporting classes and functions. - -.. autosummary:: - :toctree: generated/ - - fluidsim.base - fluidsim.operators - fluidsim.solvers - fluidsim.util - fluidsim.magic - fluidsim.extend_simul - - -.. toctree:: - :maxdepth: 1 - :caption: More - - changes - Advice for FluidDyn developers - to_do - authors - roadmap - release_process - -Links ------ - -.. |release| image:: https://img.shields.io/pypi/v/fluidsim.svg - :target: https://pypi.org/project/fluidsim/ - :alt: Latest version - -.. |coverage| image:: https://codecov.io/gh/fluiddyn/fluidsim/branch/default/graph/badge.svg - :target: https://codecov.io/gh/fluiddyn/fluidsim/ - :alt: Code coverage - -- `FluidDyn documentation `_ -- `Fluidsim forge on Heptapod `_ -- Fluidsim in PyPI |release| -- Unittest coverage |coverage| -- FluidDyn user chat room in - `Riot `_ or - `Slack `_ -- `FluidDyn mailing list `_ -- `FluidDyn on Twitter `_ - - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search`