From 6d4aa9e63bfae0a265d21bbbb5ef74fea1a796ad Mon Sep 17 00:00:00 2001 From: paugier Date: Fri, 5 Jan 2024 11:08:29 +0100 Subject: [PATCH 1/3] 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` From d0c581f867908be0caa6ea7c21be0abbe34e8226 Mon Sep 17 00:00:00 2001 From: paugier Date: Fri, 5 Jan 2024 11:41:46 +0100 Subject: [PATCH 2/3] Doc: convert files to .md --- AUTHORS.md | 20 ++++++++ AUTHORS.rst | 23 --------- CHANGES.md | 131 +++++++++++++++++++++++++++-------------------- doc/authors.md | 1 + doc/authors.rst | 4 -- doc/conf.py | 6 ++- doc/examples.md | 18 +++++++ doc/examples.rst | 17 ------ doc/faq.md | 45 ++++++++++++++++ doc/faq.rst | 54 ------------------- doc/index.md | 4 +- doc/roadmap.md | 30 +++++------ 12 files changed, 181 insertions(+), 172 deletions(-) create mode 100644 AUTHORS.md delete mode 100644 AUTHORS.rst create mode 120000 doc/authors.md delete mode 100644 doc/authors.rst create mode 100644 doc/examples.md delete mode 100644 doc/examples.rst create mode 100644 doc/faq.md delete mode 100644 doc/faq.rst diff --git a/AUTHORS.md b/AUTHORS.md new file mode 100644 index 000000000..daccb4364 --- /dev/null +++ b/AUTHORS.md @@ -0,0 +1,20 @@ +# Authors + +Fluidsim has first been developed by +[Pierre Augier](http://www.legi.grenoble-inp.fr/people/Pierre.Augier/) (CNRS +researcher at [LEGI](http://www.legi.grenoble-inp.fr), Grenoble) at KTH +(Stockholm) as a numerical code to solve fluid equations in a periodic +two-dimensional space with pseudo-spectral methods. + +Fluidsim has been greatly improved during Ashwin Vishnu PhD at KTH (Stockholm). + +The main contributors are: + +- [Pierre Augier (LEGI, CNRS, UGA)](http://www.legi.grenoble-inp.fr/people/Pierre.Augier) +- [Ashwin Vishnu (KTH)](https://www.mech.kth.se/mech/info_staff.xhtml?ID=381) +- [Cyrille Bonamy (LEGI, CNRS, UGA)](http://www.legi.grenoble-inp.fr/web/spip.php?auteur223) +- [Miguel Calpe Linares (LEGI, CNRS, UGA)](http://www.legi.grenoble-inp.fr/web/spip.php?auteur328) +- [Jason Reneuve (ENS Lyon)](http://www.ens-lyon.fr/PHYSIQUE/presentation/anciens/reneuve-jason) +- Antoine Bardant (LEGI) +- [Vincent Labarre](https://www.researchgate.net/profile/Vincent-Labarre) + ([OCA](https://www.oca.eu/fr/fluid)) diff --git a/AUTHORS.rst b/AUTHORS.rst deleted file mode 100644 index fadaf012f..000000000 --- a/AUTHORS.rst +++ /dev/null @@ -1,23 +0,0 @@ - -Fluidsim has first been developed by `Pierre Augier -`_ (CNRS researcher at -`LEGI `_, Grenoble) at KTH (Stockholm) as a -numerical code to solve fluid equations in a periodic two-dimensional space -with pseudo-spectral methods. - -Fluidsim has been greatly improved during Ashwin Vishnu PhD at KTH (Stockholm). - -The main contributors are: - -- `Pierre Augier (LEGI, CNRS, UGA) - `_ -- `Ashwin Vishnu (KTH) `_ -- `Cyrille Bonamy (LEGI, CNRS, UGA) - `_ -- `Miguel Calpe Linares (LEGI, CNRS, UGA) - `_ -- `Jason Reneuve (ENS Lyon) - `_ -- Antoine Bardant (LEGI) -- `Vincent Labarre `__ - (`OCA `__) diff --git a/CHANGES.md b/CHANGES.md index 5a03da2e3..94a181fe4 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -2,10 +2,9 @@ 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). +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 @@ -35,13 +34,14 @@ Versioning](https://semver.org/spec/v2.0.0.html). 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 +- 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). +- Few improvements for + [Fluidsimfoam](https://foss.heptapod.net/fluiddyn/fluidsimfoam). ## [0.7.2] (2023-01-05) @@ -49,19 +49,20 @@ Versioning](https://semver.org/spec/v2.0.0.html). ## [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. +- [!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) +- [!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`) + ({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) @@ -69,68 +70,85 @@ Versioning](https://semver.org/spec/v2.0.0.html). ({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 +- [!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`. +- [!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 +- 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 +- 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.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)) +- 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)) +- 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_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)) +- 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`) +- 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`) + {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)). + {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. +- [! 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)) +- 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 +- [!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. @@ -138,23 +156,24 @@ Versioning](https://semver.org/spec/v2.0.0.html). ### Added -- [!200](https://foss.heptapod.net/fluiddyn/fluidsim/-/merge_requests/200) : - New mechanism to easily extend a Simul class (subpackage +- [!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 + - 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), ...) +- 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) @@ -165,8 +184,8 @@ Versioning](https://semver.org/spec/v2.0.0.html). 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. + Replace for ns2d solvers the output `frequency_spectra` (nearly not used) by the + newer output `temporal_spectra` written for ns3d solvers. ### Fixed @@ -174,17 +193,21 @@ Versioning](https://semver.org/spec/v2.0.0.html). ## [0.4.1] (2021-02-02) -Few bugfixes and [!192](https://foss.heptapod.net/fluiddyn/fluidsim/-/merge_requests/192) -(temporal spectra for ns3d solvers). +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` +- [!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 + - 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` +- `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`) @@ -235,8 +258,8 @@ Few bugfixes and [!192](https://foss.heptapod.net/fluiddyn/fluidsim/-/merge_requ ## 0.1.1 -- Better `phys_fields.plot` and `phys_fields.animate` (by Ashwin Vishnu and - Miguel Calpe Linares). +- 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. @@ -270,13 +293,12 @@ Merge with geofluidsim (Ashwin Vishnu Mohanan repository) ## 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. +- 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. +- 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 @@ -296,4 +318,3 @@ Merge with geofluidsim (Ashwin Vishnu Mohanan repository) [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/doc/authors.md b/doc/authors.md new file mode 120000 index 000000000..3234d6e07 --- /dev/null +++ b/doc/authors.md @@ -0,0 +1 @@ +../AUTHORS.md \ No newline at end of file diff --git a/doc/authors.rst b/doc/authors.rst deleted file mode 100644 index 0661b54dc..000000000 --- a/doc/authors.rst +++ /dev/null @@ -1,4 +0,0 @@ -Authors -======= - -.. include:: ../AUTHORS.rst diff --git a/doc/conf.py b/doc/conf.py index 09876c374..54290455c 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -335,7 +335,9 @@ # 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 @@ -390,7 +392,7 @@ myst_enable_extensions = [ "amsmath", # "attrs_inline", - # "colon_fence", + "colon_fence", # "deflist", "dollarmath", # "fieldlist", diff --git a/doc/examples.md b/doc/examples.md new file mode 100644 index 000000000..89273e880 --- /dev/null +++ b/doc/examples.md @@ -0,0 +1,18 @@ +# Examples + +```{toctree} +--- +maxdepth: 2 +--- +examples/running-simul-onlineplot +examples/running-simul-cluster +examples/running-simul-restart +examples/init-fields-in-script +examples/init-fields-in-script-3d +examples/forcing-in-script +examples/static-layers +ipynb/executed/taylor-green +``` + +There are more interesting examples in +! diff --git a/doc/examples.rst b/doc/examples.rst deleted file mode 100644 index 0626c3cb1..000000000 --- a/doc/examples.rst +++ /dev/null @@ -1,17 +0,0 @@ -Examples -======== - -.. toctree:: - :maxdepth: 2 - - examples/running-simul-onlineplot - examples/running-simul-cluster - examples/running-simul-restart - examples/init-fields-in-script - examples/init-fields-in-script-3d - examples/forcing-in-script - examples/static-layers - ipynb/executed/taylor-green - -There are more interesting examples in -https://foss.heptapod.net/fluiddyn/fluidsim/tree/branch/default/doc/examples! diff --git a/doc/faq.md b/doc/faq.md new file mode 100644 index 000000000..390f4cb3d --- /dev/null +++ b/doc/faq.md @@ -0,0 +1,45 @@ +# FAQ + +## Applications: Can I use FluidSim for + +:::\{admonition} Wall bounded / multiphase / reactive flows ...? Maybe. The +built-in {mod}`solvers ` excels solving within periodic domains +with pseudospectral solvers. However, FluidSim is a framework, and this allows +FluidSim to interface with third-party solvers. See for instance +{mod}`fluidsim.base.basilisk`, {mod}`fluidsim.base.dedalus` and +[snek5000](https://snek5000.readthedocs.io). ::: + +## Troubleshooting installation issues + +Make sure you read the [installation guide](install) carefully. + +:::\{admonition} Permission denied while running `pip install fluidsim` from PyPI +or `make develop` inside the repository. This means you are probably using the +Python bundled with the system and as a user you are restricted from installing +packages into it. If this is so, create a [virtual environment]. ::: + +:::\{admonition} *No module named pip* or `distutils.errors.DistutilsError` +Package manager `pip` was not installed into your environment or is too old. The +following commands should help: + +``` +python -m ensurepip +python -m pip install --upgrade pip setuptools wheel +``` + +::: + +:::\{admonition} System freezes or becomes unresponsive as fluidsim starts to +build extensions By default `pythran` extensions try to use `gcc` and this is a +CPU and memory intensive compilation. Instead `pythran` can be configured to use +`clang`. See {ref}`pythranrc` for more details. + +Additionally to reduce the load during installation is to configure certain +{ref}`build specific environment variables `. ::: + +:::\{admonition} `ModuleNotFoundError: No module named 'fluidsim_core. ...` +FluidSim depends on {mod}`fluidsim_core` and both follow the same versioning. Make +sure the versions match if you had used `pip install` or `conda install`. For +developers, `make develop` should install both as editable installations. ::: + +[virtual environment]: https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/#creating-a-virtual-environment diff --git a/doc/faq.rst b/doc/faq.rst deleted file mode 100644 index 2e0f8b21f..000000000 --- a/doc/faq.rst +++ /dev/null @@ -1,54 +0,0 @@ -FAQ -=== - -Applications: Can I use FluidSim for -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. admonition:: Wall bounded / multiphase / reactive flows ...? - - Maybe. The built-in :mod:`solvers ` excels solving within - periodic domains with pseudospectral solvers. However, FluidSim is a - framework, and this allows FluidSim to interface with third-party solvers. - See for instance :mod:`fluidsim.base.basilisk`, :mod:`fluidsim.base.dedalus` - and `snek5000 `__. - - -Troubleshooting installation issues -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Make sure you read the `installation guide `__ carefully. - -.. admonition:: Permission denied while running ``pip install fluidsim`` from - PyPI or ``make develop`` inside the repository. - - This means you are probably using the Python bundled with the system and as - a user you are restricted from installing packages into it. If this is so, - create a `virtual environment`_. - -.. _virtual environment: https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/#creating-a-virtual-environment - - -.. admonition:: *No module named pip* or ``distutils.errors.DistutilsError`` - - Package manager ``pip`` was not installed into your environment or is too - old. The following commands should help:: - - python -m ensurepip - python -m pip install --upgrade pip setuptools wheel - -.. admonition:: System freezes or becomes unresponsive as fluidsim starts to - build extensions - - By default ``pythran`` extensions try to use ``gcc`` and this is a CPU and - memory intensive compilation. Instead ``pythran`` can be configured to use - ``clang``. See :ref:`pythranrc` for more details. - - Additionally to reduce the load during installation is to configure certain - :ref:`build specific environment variables `. - -.. admonition:: ``ModuleNotFoundError: No module named 'fluidsim_core. ...`` - - FluidSim depends on :mod:`fluidsim_core` and both follow the same - versioning. Make sure the versions match if you had used ``pip install`` or - ``conda install``. For developers, ``make develop`` should install both as - editable installations. diff --git a/doc/index.md b/doc/index.md index cb92cc088..499906210 100644 --- a/doc/index.md +++ b/doc/index.md @@ -173,8 +173,8 @@ release_process - [FluidDyn documentation](http://fluiddyn.readthedocs.io) - [Fluidsim forge on Heptapod](https://foss.heptapod.net/fluiddyn/fluidsim) -- Fluidsim in PyPI {{release}} -- Unittest coverage {{coverage}} +- 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) diff --git a/doc/roadmap.md b/doc/roadmap.md index 511daf5c5..6e75c8de1 100644 --- a/doc/roadmap.md +++ b/doc/roadmap.md @@ -41,7 +41,8 @@ Specialized in pseudo-spectral Fourier. - [Gross–Pitaevskii equation](https://en.wikipedia.org/wiki/Gross%E2%80%93Pitaevskii_equation) - ... (?) -- Linear stability (as in [NS3D](http://yakari.polytechnique.fr/people/deloncle/ns3d.html) +- Linear stability (as in + [NS3D](http://yakari.polytechnique.fr/people/deloncle/ns3d.html) - FFT accelerated with GPU and MPI+GPU (fluidfft) @@ -49,9 +50,9 @@ Specialized in pseudo-spectral Fourier. [#99](https://foss.heptapod.net/fluiddyn/fluidsim/-/issues/99)) - Simul class made of 2 (or n) interacting Simul classes. For example, ns2d + -passive scalar at higher resolution. Or fluid-structure interaction as in -[FLUSI](https://github.com/pseudospectators/FLUSI) (see -[!104](https://foss.heptapod.net/fluiddyn/fluidsim/-/issues/104)) + passive scalar at higher resolution. Or fluid-structure interaction as in + [FLUSI](https://github.com/pseudospectators/FLUSI) (see + [!104](https://foss.heptapod.net/fluiddyn/fluidsim/-/issues/104)) - Particles and Lagrangian dynamics @@ -59,18 +60,17 @@ passive scalar at higher resolution. Or fluid-structure interaction as in - API to dynamically define a solver -"Ability to dynamically and concisely build a solver is what Dedalus is good -at. And performance and batteries-included approach is where FluidSim shines. -Our InfoSolver + Parameters approach is flexible but requires a lot of -boilerplate code. Even today I always need to refer to documentation while -creating a new solver. It must be possible to create intuitive factory classes -which dynamically generate InfoSolver, Parameters, Simul classes for us. We -could refer to some well known design patterns for inspiration." (Ashwin V. -Mohanan) +"Ability to dynamically and concisely build a solver is what Dedalus is good at. +And performance and batteries-included approach is where FluidSim shines. Our +InfoSolver + Parameters approach is flexible but requires a lot of boilerplate +code. Even today I always need to refer to documentation while creating a new +solver. It must be possible to create intuitive factory classes which dynamically +generate InfoSolver, Parameters, Simul classes for us. We could refer to some well +known design patterns for inspiration." (Ashwin V. Mohanan) - Explore use of type hints Inline or separate *.pyi files? Use MonkeyType or similar to autogenerate type -hints from tests? Some inspiration: [FOSDEM -talk](https://fosdem.org/2022/schedule/event/python_type_safety/) and [this -blog post](https://nskm.xyz/posts/stcmp2/) +hints from tests? Some inspiration: +[FOSDEM talk](https://fosdem.org/2022/schedule/event/python_type_safety/) and +[this blog post](https://nskm.xyz/posts/stcmp2/) From d64efff5823b5a3fc16344f0ca664c5e1ce9a5c1 Mon Sep 17 00:00:00 2001 From: paugier Date: Fri, 5 Jan 2024 12:13:21 +0100 Subject: [PATCH 3/3] Doc: convert all doc/*.rst files to .md --- doc/faq.md | 42 ++++-- doc/install.md | 274 +++++++++++++++++++++++++++++++++++++ doc/install.rst | 246 --------------------------------- doc/test_bench_profile.md | 34 +++++ doc/test_bench_profile.rst | 39 ------ doc/to_do.md | 19 +++ doc/to_do.rst | 24 ---- doc/tutorials.md | 23 ++++ doc/tutorials.rst | 21 --- 9 files changed, 377 insertions(+), 345 deletions(-) create mode 100644 doc/install.md delete mode 100644 doc/install.rst create mode 100644 doc/test_bench_profile.md delete mode 100644 doc/test_bench_profile.rst create mode 100644 doc/to_do.md delete mode 100644 doc/to_do.rst create mode 100644 doc/tutorials.md delete mode 100644 doc/tutorials.rst diff --git a/doc/faq.md b/doc/faq.md index 390f4cb3d..7dedd4e37 100644 --- a/doc/faq.md +++ b/doc/faq.md @@ -2,44 +2,56 @@ ## Applications: Can I use FluidSim for -:::\{admonition} Wall bounded / multiphase / reactive flows ...? Maybe. The -built-in {mod}`solvers ` excels solving within periodic domains -with pseudospectral solvers. However, FluidSim is a framework, and this allows -FluidSim to interface with third-party solvers. See for instance -{mod}`fluidsim.base.basilisk`, {mod}`fluidsim.base.dedalus` and -[snek5000](https://snek5000.readthedocs.io). ::: +:::{admonition} Wall bounded / multiphase / reactive flows ...? + +Maybe. The built-in {mod}`solvers ` excels solving within +periodic domains with pseudospectral solvers. However, FluidSim is a framework, +and this allows FluidSim to interface with third-party solvers. See for +instance {mod}`fluidsim.base.basilisk`, {mod}`fluidsim.base.dedalus` and +[snek5000](https://snek5000.readthedocs.io). + +::: ## Troubleshooting installation issues Make sure you read the [installation guide](install) carefully. -:::\{admonition} Permission denied while running `pip install fluidsim` from PyPI +:::{admonition} Permission denied while running `pip install fluidsim` from PyPI + or `make develop` inside the repository. This means you are probably using the Python bundled with the system and as a user you are restricted from installing -packages into it. If this is so, create a [virtual environment]. ::: +packages into it. If this is so, create a [virtual environment]. + +::: + +:::{admonition} *No module named pip* or `distutils.errors.DistutilsError` -:::\{admonition} *No module named pip* or `distutils.errors.DistutilsError` Package manager `pip` was not installed into your environment or is too old. The following commands should help: -``` +```sh python -m ensurepip python -m pip install --upgrade pip setuptools wheel ``` ::: -:::\{admonition} System freezes or becomes unresponsive as fluidsim starts to -build extensions By default `pythran` extensions try to use `gcc` and this is a +:::{admonition} System freezes or becomes unresponsive as fluidsim starts to build extensions + +By default `pythran` extensions try to use `gcc` and this is a CPU and memory intensive compilation. Instead `pythran` can be configured to use `clang`. See {ref}`pythranrc` for more details. Additionally to reduce the load during installation is to configure certain -{ref}`build specific environment variables `. ::: +{ref}`build specific environment variables `. +::: + +:::{admonition} `ModuleNotFoundError: No module named 'fluidsim_core. ...` -:::\{admonition} `ModuleNotFoundError: No module named 'fluidsim_core. ...` FluidSim depends on {mod}`fluidsim_core` and both follow the same versioning. Make sure the versions match if you had used `pip install` or `conda install`. For -developers, `make develop` should install both as editable installations. ::: +developers, `make develop` should install both as editable installations. + +::: [virtual environment]: https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/#creating-a-virtual-environment diff --git a/doc/install.md b/doc/install.md new file mode 100644 index 000000000..6b5df0327 --- /dev/null +++ b/doc/install.md @@ -0,0 +1,274 @@ +# Installation + +FluidSim is part of the FluidDyn project and requires Python >= 3.6. Some issues +regarding the installation of Python and Python packages are discussed in +[the main documentation of the project](http://fluiddyn.readthedocs.org/en/latest/install.html). + +We don't upload wheels on PyPI, so the simplest and fastest procedure is to use +`conda` (no compilation needed). Alternatively, one can compile fluidsim and +fluidfft using `pip`. + +## Installing the conda-forge packages with conda or mamba + +The fluidsim packages are in the conda-forge channels, so if it is not already +done, one needs to add it: + +```sh +conda config --add channels conda-forge +``` + +If you just want to run sequential simulations and/or analyze the results of +simulations, you can just install the fluidsim package: + +```sh +conda install fluidsim +``` + +For parallel simulations using MPI, let's create a dedicated environment: + +```sh +conda create -n env_fluidsim ipython fluidsim "fluidfft[build=mpi*]" "h5py[build=mpi*]" +``` + +The environment can then be activated with `conda activate env_fluidsim`. + +## Build/install using pip + +We recommend installing with a recent version of pip so you might want to run +`pip install pip -U` before anything (if you use conda, `conda update pip`). Then, +fluidsim can be installed with: + +```sh +pip install fluidsim +``` + +However, one have to note that (i) fluidsim builds are sensible to environment +variables (see below) and (ii) fluidsim can optionally use +[fluidfft](http://fluidfft.readthedocs.io) for pseudospectral solvers. Fluidsim +and fluidfft can be both installed with the command: + +```sh +pip install fluidsim[fft] +``` + +Moreover, fluidfft builds can also be tweaked so you could have a look at +[fluidfft documentation](http://fluidfft.readthedocs.io/en/latest/install.html). + +(env-vars)= + +## Environment variables and build configuration + +### Build time configuration + +- `FLUIDDYN_NUM_PROCS_BUILD` + +Fluidsim binaries are builds in parallel. This speedups the build process a lot on +most computers. However, it can be a very bad idea on computers with not enough +memory. If you encounter problems, you can force the number of processes used +during the build using the environment variable `FLUIDDYN_NUM_PROCS_BUILD`: + +```sh +export FLUIDDYN_NUM_PROCS_BUILD=2 +``` + +- Customize compilers to build extensions, if the defaults do not work for you, + either using the environment variables: + + - `MPICXX`: for Cython extensions in `fluidfft` (default: `mpicxx`) + - `CC`: command to generate object files in `fluidsim` + - `LDSHARED`: command to link and generate shared libraries in `fluidsim` + - `CARCH`: to cross compile (default: `native`) + +- `DISABLE_PYTHRAN` disables compilation with Pythran at build time. + +- `FLUIDSIM_TRANSONIC_BACKEND` + + "pythran" by default, it can be set to "python", "numba" or "cython". + +You can also configure the installation of fluidsim by creating the file +`~/.fluidsim-site.cfg` (or `site.cfg` in the repo directory) and modify it to fit +your requirements before the installation with pip: + +```sh +wget https://foss.heptapod.net/fluiddyn/fluidsim/-/raw/branch/default/site.cfg.default -O ~/.fluidsim-site.cfg +``` + +### Runtime configuration + +Fluidsim is also sensitive to the environment variables: + +- `FLUIDSIM_PATH`: path where the simulation results are saved. + + In Unix systems, you can for example put this line in your `~/.bashrc`: + + ```sh + export FLUIDSIM_PATH=$HOME/Data + ``` + +- `FLUIDDYN_PATH_SCRATCH`: working directory (can be useful on some clusters). + +## Warning about re-installing fluidsim and fluidfft with new build options + +If fluidsim has already been installed and you want to recompile with new +configuration values, you need to really recompile fluidsim and not just reinstall +an already produced wheel. To do this, use: + +```sh +pip install fluidsim --no-binary fluidsim -v +``` + +`-v` toggles the verbose mode of pip so that we see the compilation log and can +check that everything goes well. + +(pythranrc)= + +## About using Pythran to compile functions + +We choose to use the Python compiler +[Pythran](https://github.com/serge-sans-paille/pythran) for some functions of the +operators. Our microbenchmarks show that the performances are as good as what we +are able to get with Fortran or C++! + +But it implies that building Fluidsim requires a C++11 compiler (for example GCC +4.9 or clang). + +:::{note} + +If you don't want to use Pythran and C++ to speedup Fluidsim, you can +use the environment variable `DISABLE_PYTHRAN`. + +::: + +:::{warning} + +To reach good performance, we advice to try to put in the file +`~/.pythranrc` the lines (it seems to work well on Linux, see the +[Pythran documentation](https://pythran.readthedocs.io)): + +```bash +[pythran] +complex_hook = True +``` + +::: + +:::{warning} + +The compilation of C++ files produced by Pythran can be long and can +consume a lot of memory. If you encounter any problems, you can try to use clang +(for example with `conda install clangdev`) and to enable its use in the file +`~/.pythranrc` with: + +```bash +[compiler] +CXX=clang++ +CC=clang +``` + +::: + +## MPI simulations and mpi4py! + +Fluidsim can use [mpi4py](http://mpi4py.scipy.org) (which depends on a MPI +implementation) for MPI simulations. + +:::{warning} + +If the system has multiple MPI libraries, it is adviced to +explicitly mention the MPI command. For instance to use Intel MPI: + +```sh +CC=mpiicc pip install mpi4py --no-binary mpi4py +``` + +::: + +## About h5py and HDF5_MPI + +FluidSim is able to use h5py built with MPI support. + +:::{warning} + +Prebuilt installations (for e.g. via h5py wheels) lacks MPI support. +Most of the time, this is what you want. However, you can install h5py from source +and link it to a hdf5 built with MPI support, as follows: + +```bash +CC="mpicc" HDF5_MPI="ON" HDF5_DIR=/path/to/parallel-hdf5 pip install --no-deps --no-binary=h5py h5py +python -c 'import h5py; h5py.run_tests()' +``` + +In some cases you need to set C_INCLUDE_PATH variable before h5py installation. +For example on Debian stretch: + +```bash +export C_INCLUDE_PATH=/usr/include/openmpi/ +CC="mpicc" HDF5_MPI="ON" HDF5_DIR=/path/to/parallel-hdf5 pip install --no-deps --no-binary=h5py h5py +``` + +See the [h5py documentation](http://docs.h5py.org/en/latest/build.html) for more +details. + +::: + +## Installing from the repository + +:::{note} + +A good base to install Fluidsim from source can be to create and +activate a conda environment with: + +```sh +conda create -y -n env-fluidsim -c conda-forge "fluidfft=*=*openmpi*" pythran clangdev mako +conda activate env-fluidsim +``` + +::: + +For fluidsim, we use the revision control software Mercurial and the main +repository is hosted [here](https://foss.heptapod.net/fluiddyn/fluidsim) in +Heptapod. Download the source with something like: + +```sh +hg clone https://foss.heptapod.net/fluiddyn/fluidsim +``` + +If you are new with Mercurial and Heptapod, you can also read +[this short tutorial](http://fluiddyn.readthedocs.org/en/latest/mercurial_heptapod.html). + +For particular installation setup, copy the default configuration file to +`site.cfg`: + +```sh +cp site.cfg.default site.cfg +``` + +and modify it to fit your requirements. + +Build/install in development mode, by running from the top-level directory: + +```sh +cd lib && pip install -e .; cd .. +pip install -e . +``` + +:::{note} + +To install from source in a conda environment, it is actually necessary +to disable the isolated build by running the command +`pip install -e . --no-build-isolation`. + +::: + +To install Fluidsim with all optional dependencies and all capacities: + +```sh +pip install -e .[full] +``` + +### Run the tests + +You can run some unit tests by running `make tests` (shortcut for +`fluidsim-test -v`) or `make tests_mpi` (shortcut for +`mpirun -np 2 fluidsim-test -v`). Alternatively, you can also run `pytest` from +the root directory or from any of the source directories. diff --git a/doc/install.rst b/doc/install.rst deleted file mode 100644 index 16ea95069..000000000 --- a/doc/install.rst +++ /dev/null @@ -1,246 +0,0 @@ -Installation -============ - -FluidSim is part of the FluidDyn project and requires Python >= 3.6. Some -issues regarding the installation of Python and Python packages are discussed -in `the main documentation of the project -`_. - -We don't upload wheels on PyPI, so the simplest and fastest procedure is to -use ``conda`` (no compilation needed). Alternatively, one can compile fluidsim -and fluidfft using ``pip``. - -Installing the conda-forge packages with conda or mamba -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The fluidsim packages are in the conda-forge channels, so if it is not already -done, one needs to add it:: - - conda config --add channels conda-forge - -If you just want to run sequential simulations and/or analyze the results of -simulations, you can just install the fluidsim package:: - - conda install fluidsim - -For parallel simulations using MPI, let's create a dedicated environment:: - - conda create -n env_fluidsim ipython fluidsim "fluidfft[build=mpi*]" "h5py[build=mpi*]" - -The environment can then be activated with ``conda activate env_fluidsim``. - -Build/install using pip -~~~~~~~~~~~~~~~~~~~~~~~ - -We recommend installing with a recent version of pip so you might want to -run ``pip install pip -U`` before anything (if you use conda, ``conda update -pip``). Then, fluidsim can be installed with:: - - pip install fluidsim - -However, one have to note that (i) fluidsim builds are sensible to environment -variables (see below) and (ii) fluidsim can optionally use -`fluidfft `_ for pseudospectral solvers. -Fluidsim and fluidfft can be both installed with the command:: - - pip install fluidsim[fft] - -Moreover, fluidfft builds can also be tweaked so you could have a look at -`fluidfft documentation -`_. - -.. _env_vars: - -Environment variables and build configuration -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Build time configuration -........................ - -- ``FLUIDDYN_NUM_PROCS_BUILD`` - -Fluidsim binaries are builds in parallel. This speedups the build process a lot -on most computers. However, it can be a very bad idea on computers with not -enough memory. If you encounter problems, you can force the number of processes -used during the build using the environment variable -``FLUIDDYN_NUM_PROCS_BUILD``:: - - export FLUIDDYN_NUM_PROCS_BUILD=2 - -- Customize compilers to build extensions, if the defaults do not work for you, - either using the environment variables: - - - ``MPICXX``: for Cython extensions in ``fluidfft`` (default: ``mpicxx``) - - ``CC``: command to generate object files in ``fluidsim`` - - ``LDSHARED``: command to link and generate shared libraries in ``fluidsim`` - - ``CARCH``: to cross compile (default: ``native``) - -- ``DISABLE_PYTHRAN`` disables compilation with Pythran at build time. - -- ``FLUIDSIM_TRANSONIC_BACKEND`` - - "pythran" by default, it can be set to "python", "numba" or "cython". - -You can also configure the installation of fluidsim by creating the file -``~/.fluidsim-site.cfg`` (or ``site.cfg`` in the repo directory) and modify it -to fit your requirements before the installation with pip:: - - wget https://foss.heptapod.net/fluiddyn/fluidsim/-/raw/branch/default/site.cfg.default -O ~/.fluidsim-site.cfg - -Runtime configuration -..................... - -Fluidsim is also sensitive to the environment variables: - -- ``FLUIDSIM_PATH``: path where the simulation results are saved. - - In Unix systems, you can for example put this line in your ``~/.bashrc``:: - - export FLUIDSIM_PATH=$HOME/Data - -- ``FLUIDDYN_PATH_SCRATCH``: working directory (can be useful on some clusters). - -Warning about re-installing fluidsim and fluidfft with new build options -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -If fluidsim has already been installed and you want to recompile with new -configuration values, you need to really recompile fluidsim and not just -reinstall an already produced wheel. To do this, use:: - - pip install fluidsim --no-binary fluidsim -v - -``-v`` toggles the verbose mode of pip so that we see the compilation log and -can check that everything goes well. - -.. _pythranrc: - -About using Pythran to compile functions -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -We choose to use the Python compiler `Pythran -`_ for some functions of the -operators. Our microbenchmarks show that the performances are as good as what -we are able to get with Fortran or C++! - -But it implies that building Fluidsim requires a C++11 compiler (for example -GCC 4.9 or clang). - -.. note:: - - If you don't want to use Pythran and C++ to speedup Fluidsim, you can use the - environment variable ``DISABLE_PYTHRAN``. - -.. warning:: - - To reach good performance, we advice to try to put in the file - ``~/.pythranrc`` the lines (it seems to work well on Linux, see the `Pythran - documentation `_): - - .. code:: bash - - [pythran] - complex_hook = True - -.. warning:: - - The compilation of C++ files produced by Pythran can be long and can consume - a lot of memory. If you encounter any problems, you can try to use clang (for - example with ``conda install clangdev``) and to enable its use in the file - ``~/.pythranrc`` with: - - .. code:: bash - - [compiler] - CXX=clang++ - CC=clang - -MPI simulations and mpi4py! -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Fluidsim can use `mpi4py `_ (which depends on a MPI -implementation) for MPI simulations. - -.. warning:: - - If the system has multiple MPI libraries, it is adviced to explicitly - mention the MPI command. For instance to use Intel MPI:: - - CC=mpiicc pip install mpi4py --no-binary mpi4py - -About h5py and HDF5_MPI -~~~~~~~~~~~~~~~~~~~~~~~ - -FluidSim is able to use h5py built with MPI support. - -.. warning:: - - Prebuilt installations (for e.g. via h5py wheels) lacks MPI support. - Most of the time, this is what you want. However, you can install h5py - from source and link it to a hdf5 built with MPI support, as follows: - - .. code:: bash - - $ CC="mpicc" HDF5_MPI="ON" HDF5_DIR=/path/to/parallel-hdf5 pip install --no-deps --no-binary=h5py h5py - $ python -c 'import h5py; h5py.run_tests()' - - In some cases you need to set C_INCLUDE_PATH variable before h5py - installation. For example on Debian stretch: - - .. code:: bash - - $ export C_INCLUDE_PATH=/usr/include/openmpi/ - $ CC="mpicc" HDF5_MPI="ON" HDF5_DIR=/path/to/parallel-hdf5 pip install --no-deps --no-binary=h5py h5py - - See the `h5py documentation - `_ for more details. - -Installing from the repository -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. note:: - - A good base to install Fluidsim from source can be to create and activate a - conda environment with:: - - conda create -y -n env-fluidsim -c conda-forge "fluidfft=*=*openmpi*" pythran clangdev mako - conda activate env-fluidsim - -For fluidsim, we use the revision control software Mercurial and the main -repository is hosted `here `_ in -Heptapod. Download the source with something like:: - - hg clone https://foss.heptapod.net/fluiddyn/fluidsim - -If you are new with Mercurial and Heptapod, you can also read `this short -tutorial -`_. - -For particular installation setup, copy the default configuration file to -``site.cfg``:: - - cp site.cfg.default site.cfg - -and modify it to fit your requirements. - -Build/install in development mode, by running from the top-level directory:: - - cd lib && pip install -e .; cd .. - pip install -e . - -.. note:: - - To install from source in a conda environment, it is actually necessary to - disable the isolated build by running the command ``pip install -e . - --no-build-isolation``. - -To install Fluidsim with all optional dependencies and all capacities:: - - pip install -e .[full] - -Run the tests! -.............. - -You can run some unit tests by running ``make tests`` (shortcut for -``fluidsim-test -v``) or ``make tests_mpi`` (shortcut for ``mpirun -np 2 -fluidsim-test -v``). Alternatively, you can also run ``pytest`` from the root -directory or from any of the source directories. diff --git a/doc/test_bench_profile.md b/doc/test_bench_profile.md new file mode 100644 index 000000000..98768b682 --- /dev/null +++ b/doc/test_bench_profile.md @@ -0,0 +1,34 @@ +# Testing, benchmarks and profiling + +Fluidsim comes with command-line tools for testing, benchmarking and profiling. +Here are useful commands: + +```bash +fluidsim -h +``` + +## Testing + +```bash +fluidsim-test -h +fluidsim-test -v +``` + +## Benchmarks + +```bash +fluidsim-bench -h +fluidsim-bench -s ns2d +``` + +```bash +fluidsim-bench-analysis -h +``` + +## Profiling + +```bash +fluidsim-profile -h +fluidsim-profile -s ns2d +fluidsim-profile -p -sf /tmp/fluidsim_profile/result_bench_ns2d_512x512_2017-11-19_22-19-26_8772.json +``` diff --git a/doc/test_bench_profile.rst b/doc/test_bench_profile.rst deleted file mode 100644 index 30a2ea546..000000000 --- a/doc/test_bench_profile.rst +++ /dev/null @@ -1,39 +0,0 @@ -Testing, benchmarks and profiling -================================= - -Fluidsim comes with command-line tools for testing, benchmarking and -profiling. Here are useful commands: - -.. code-block:: bash - - fluidsim -h - -Testing -------- - -.. code-block:: bash - - fluidsim-test -h - fluidsim-test -v - -Benchmarks ----------- - -.. code-block:: bash - - fluidsim-bench -h - fluidsim-bench -s ns2d - -.. code-block:: bash - - fluidsim-bench-analysis -h - - -Profiling ---------- - -.. code-block:: bash - - fluidsim-profile -h - fluidsim-profile -s ns2d - fluidsim-profile -p -sf /tmp/fluidsim_profile/result_bench_ns2d_512x512_2017-11-19_22-19-26_8772.json diff --git a/doc/to_do.md b/doc/to_do.md new file mode 100644 index 000000000..c5e7caf67 --- /dev/null +++ b/doc/to_do.md @@ -0,0 +1,19 @@ +# To do list + +## Long term + +- better integration with + + - paraview + - VAPOR is the Visualization and Analysis Platform for Ocean, Atmosphere, and + Solar Researchers () + - VisIt is a free \[and open-source\], interactive parallel visualization and + graphical analysis tool + () + +## Inline to do items + +```{eval-rst} +.. todolist:: + +``` diff --git a/doc/to_do.rst b/doc/to_do.rst deleted file mode 100644 index 36e76697a..000000000 --- a/doc/to_do.rst +++ /dev/null @@ -1,24 +0,0 @@ -To do list -========== - -Long term ---------- - -- better integration with - - * paraview - - * VAPOR is the Visualization and Analysis Platform for Ocean, - Atmosphere, and Solar Researchers (https://www.vapor.ucar.edu/) - - * VisIt is a free [and open-source], interactive parallel - visualization and graphical analysis tool - (https://wci.llnl.gov/simulation/computer-codes/visit) - - -Inline to do items ------------------- - -.. todolist:: - - diff --git a/doc/tutorials.md b/doc/tutorials.md new file mode 100644 index 000000000..05b813135 --- /dev/null +++ b/doc/tutorials.md @@ -0,0 +1,23 @@ +# Tutorials + +Most of these tutorials have been produced by Ipython notebook. + +```{toctree} +--- +maxdepth: 2 +--- +ipynb/tuto_user +ipynb/tuto_dev +ipynb/executed/taylor-green +``` + +## Parametric study with fluidsim.solvers.ns3d.strat + +```{toctree} +--- +maxdepth: 2 +--- +ipynb/executed/parametric_study_ns3dstrat/0_run_simulations +ipynb/executed/parametric_study_ns3dstrat/1_analyze_1_simul +ipynb/executed/parametric_study_ns3dstrat/2_compare_simulations +``` diff --git a/doc/tutorials.rst b/doc/tutorials.rst deleted file mode 100644 index f8adc0812..000000000 --- a/doc/tutorials.rst +++ /dev/null @@ -1,21 +0,0 @@ -Tutorials -========= - -Most of these tutorials have been produced by Ipython notebook. - -.. toctree:: - :maxdepth: 2 - - ipynb/tuto_user - ipynb/tuto_dev - ipynb/executed/taylor-green - -Parametric study with fluidsim.solvers.ns3d.strat -------------------------------------------------- - -.. toctree:: - :maxdepth: 2 - - ipynb/executed/parametric_study_ns3dstrat/0_run_simulations - ipynb/executed/parametric_study_ns3dstrat/1_analyze_1_simul - ipynb/executed/parametric_study_ns3dstrat/2_compare_simulations