From 0276f8e43c358a2080747fba17c74c690fbf6a30 Mon Sep 17 00:00:00 2001
From: JM Etancelin <jean-matthieu.etancelin@univ-pau.fr>
Date: Wed, 22 Feb 2023 17:15:28 +0100
Subject: [PATCH] update structure + getting-started and install guide
---
build_doc.sh | 2 +-
.../figures/advection_scalaire_passif.png | Bin
.../figures/dissolution_castlegate.png | Bin
docs/{ => sphinx}/figures/logo_hysop_rgb.png | Bin
docs/{ => sphinx}/figures/sediments.png | Bin
docs/{ => sphinx}/figures/sphere_3D_wake.png | Bin
docs/{ => sphinx}/figures/vorticity_field.png | Bin
docs/sphinx/getting_started/index.rst | 139 ++++++++++++++++++
docs/{ => sphinx}/hysop.bib | 0
docs/{ => sphinx}/index.rst | 32 ++--
docs/sphinx/install_guide/index.rst | 101 +++++++++++++
11 files changed, 258 insertions(+), 16 deletions(-)
rename docs/{ => sphinx}/figures/advection_scalaire_passif.png (100%)
rename docs/{ => sphinx}/figures/dissolution_castlegate.png (100%)
rename docs/{ => sphinx}/figures/logo_hysop_rgb.png (100%)
rename docs/{ => sphinx}/figures/sediments.png (100%)
rename docs/{ => sphinx}/figures/sphere_3D_wake.png (100%)
rename docs/{ => sphinx}/figures/vorticity_field.png (100%)
create mode 100644 docs/sphinx/getting_started/index.rst
rename docs/{ => sphinx}/hysop.bib (100%)
rename docs/{ => sphinx}/index.rst (94%)
create mode 100644 docs/sphinx/install_guide/index.rst
diff --git a/build_doc.sh b/build_doc.sh
index e7751ba..5a5ce26 100755
--- a/build_doc.sh
+++ b/build_doc.sh
@@ -11,7 +11,7 @@ INSTALL_DIR="$(pwd)/install"
git clone https://gricad-gitlab.univ-grenoble-alpes.fr/particle_methods/hysop.git
# Merge content from hysop-doc
-cp -r ./docs/* ${ROOT_DIR}/docs/sphinx/.
+cp -r ./docs/* ${ROOT_DIR}/docs/.
mkdir -p "${BUILD_DIR}"
cd "${BUILD_DIR}"
diff --git a/docs/figures/advection_scalaire_passif.png b/docs/sphinx/figures/advection_scalaire_passif.png
similarity index 100%
rename from docs/figures/advection_scalaire_passif.png
rename to docs/sphinx/figures/advection_scalaire_passif.png
diff --git a/docs/figures/dissolution_castlegate.png b/docs/sphinx/figures/dissolution_castlegate.png
similarity index 100%
rename from docs/figures/dissolution_castlegate.png
rename to docs/sphinx/figures/dissolution_castlegate.png
diff --git a/docs/figures/logo_hysop_rgb.png b/docs/sphinx/figures/logo_hysop_rgb.png
similarity index 100%
rename from docs/figures/logo_hysop_rgb.png
rename to docs/sphinx/figures/logo_hysop_rgb.png
diff --git a/docs/figures/sediments.png b/docs/sphinx/figures/sediments.png
similarity index 100%
rename from docs/figures/sediments.png
rename to docs/sphinx/figures/sediments.png
diff --git a/docs/figures/sphere_3D_wake.png b/docs/sphinx/figures/sphere_3D_wake.png
similarity index 100%
rename from docs/figures/sphere_3D_wake.png
rename to docs/sphinx/figures/sphere_3D_wake.png
diff --git a/docs/figures/vorticity_field.png b/docs/sphinx/figures/vorticity_field.png
similarity index 100%
rename from docs/figures/vorticity_field.png
rename to docs/sphinx/figures/vorticity_field.png
diff --git a/docs/sphinx/getting_started/index.rst b/docs/sphinx/getting_started/index.rst
new file mode 100644
index 0000000..1500a28
--- /dev/null
+++ b/docs/sphinx/getting_started/index.rst
@@ -0,0 +1,139 @@
+.. _getting_started:
+
+Getting Started With HySoP
+==========================
+
+Basics : running a simulation with HySoP
+----------------------------------------
+
+The problem to be solved must be described using Python language either interactively or in a python script.
+If you are not at ease with this language, we strongly encourage you to check one of the numerous python tutorials available on the web. Try for example https://docs.python.org/2/tutorial/. A basic understanding of numpy may also be useful : http://www.numpy.org.
+Numpy is the python package for scientific computing on which HySoP relies, especially for arrays handling.
+
+
+Some, python references:
+
+* https://www.python.org/about/gettingstarted/, for beginners with python
+* https://docs.python.org/2/, python official documentation, including tutorials
+* http://www.numpy.org, numpy, scipy documentation
+* http://hplgit.github.io/homepage/books.html
+
+Interactive session
+*******************
+
+For an interactive use, we recommend ipython or even ipython notebook. Start the interpreter and then import hysop and/or its
+submodules. For example, try in a terminal window::
+
+ ipython
+
+and
+
+ >>> from hysop import Box
+ >>> from hysop.operators import Poisson
+ >>> dom = Box(dim=2) # 2D [0:1]^2 domain
+
+Use script
+**********
+
+Interactive session is very useful for tests, basic understanding of hysop functionnalities but real simulation must
+be executed by using a script.
+
+To do so, write a python script 'myscript.py' which contains all python commands required to describe and solve your problem (see next part or user guide) and run in a terminal window::
+
+ python myscript.py
+
+for sequential run, or::
+
+ mpirun -np 4 python myscript.py
+
+for parallel run on 4 mpi processes.
+
+The best way to begin with HySoP is to try one of the numerous examples available in the distribution.
+
+
+Basics : describe a problem in HySoP
+------------------------------------
+
+This short introduction presents the basic objects to know to describe and solve properly a problem with HySoP.
+
+HySoP provides a framework for flow simulation, based on particles methods. The workflow for such a simulation will be:
+
+* define a physical domain : geometry and boundary conditions,
+* define some scalar or vector fields on this domain, the unknowns,
+* describe which equations are applied on these unknowns, thanks to a sequence of operators,
+* configure these operators (space discretization, numerical methods ...),
+* define a time discretisation and initialize the operators and fields,
+* run the simulation : execute the sequence of operators at each time step,
+* post-process the results.
+
+Here is a short glossary of the objects which form a simulation process within HySoP:
+
+**Domain**: a physical domain, defined by its origin, its size and some types of boundary conditions. Different space discretisations and data distributions can be associated with a domain. See details in :ref:`domains`.
+
+**Fields**: the unknowns of your problem, the 'classical' mathematical vector or scalar fields, i.e. a function which associates a scalar or a vector to each point of the space.
+Fields obviously depends on time and space. See details in :ref:`fields`.
+
+**Operator**: a set of equations (most of the time ode), defined on a domain, with some fields as unknowns. See details in :ref:`operators`.
+
+**Problem**: a sequence of operators associated with a simulation.
+
+All of the objects defined above are high-level continuous objects, only descriptions indeed.
+In particular, none of them depends on the type of execution (parallel or sequential) and on the number of mpi processes involved.
+Indeed, to proceed with the simulation, it is necessary to define space and time discretization, to choose some numerical methods to solve each operator, in some words to configure and discretize the whole process. Thus, we need to introduce the following objects:
+
+**Discretization** : space discretization of the global domain (grid resolution, space step size ...).
+
+**Topology** : description of how data are distributed among mpi processes and of the space discretisation (global and local to each process)
+
+For details about discretisation and data distribution, check :ref:`topologies`.
+
+**Simulation**: description of the time discretisation (start and end time, time step ...)
+
+Consider for example the following advection problem,
+
+.. math::
+
+ \frac{\partial \rho(\boldsymbol{x},t)}{\partial t} + v(\boldsymbol{x},t).\nabla\rho(\boldsymbol{x},t) = 0
+
+
+
+where :math:`\rho`, a scalar field, and :math:`v`, a vector field, are the unknowns, defined on a box-shaped domain with some given values on the boundaries
+and initial values at time :math:`t=t_0`.
+
+Then, in HySoP, you will have to define two *Fields*, representing :math:`\rho` and :math:`v`, a 3d domain, an operator 'advection' and a problem including only one operator. Such a process may look like::
+
+
+ from hysop import Box, Field, Simulation, Problem
+ from hysop.defaults import TimeParameters
+ from hysop.operators import Advection
+
+ # A box-shaped 3d domain
+ dom = Box(length=[1., 1., 1.], origin=[0., 0., 0.])
+ # Define some continuous fields
+ v = Field(domain=dom, name='velocity', is_vector=True)
+ rho = Field(domain=dom, name='rho')
+ # Space discretisation (cartesian)
+ n = (64, 64, 64)
+ # Time discretization
+ t, dt = TimeParameters()
+ simu = Simulation(t=t, dt=dt, dt0=0.01)
+ # Define a continuous operator, that will be discretized in space and time
+ adv = Advection(v, rho, variables={v:n, rho:n}, dt=dt)
+ # Define a problem containing the operator
+ problem = Problem()
+ problem.insert(adv)
+
+ # Discretize everything, and prepare lower level functionnalities
+ problem.build()
+
+ # ... some stuff to initialize fields values ...
+
+ # solve advection for the current time
+ problem.solve(simu)
+
+ # ... post process ...
+
+ problem.finalize()
+
+Notice that you don't need a deep understanding about 'parallel' things, mpi or gpu, to use HySoP, at least for a basic usage.
+As you can see in the example above, we try to hide as much as possible those parallel stuff from the high-level user interface. Just keep in mind that your programm may run on several processes and that data may be distributed accross different memory areas.
diff --git a/docs/hysop.bib b/docs/sphinx/hysop.bib
similarity index 100%
rename from docs/hysop.bib
rename to docs/sphinx/hysop.bib
diff --git a/docs/index.rst b/docs/sphinx/index.rst
similarity index 94%
rename from docs/index.rst
rename to docs/sphinx/index.rst
index a25dabe..bab7435 100644
--- a/docs/index.rst
+++ b/docs/sphinx/index.rst
@@ -5,12 +5,26 @@
Welcome to HySoP's webpage!
===========================
+.. toctree::
+ :hidden:
+ :maxdepth: 3
+ :caption: Contents:
+
+ install_guide/index
+ getting_started/index
+ reference/index
+
+..
+ users_guide/index
+ examples/index
+ devel/index
+
.. image:: figures/logo_hysop_rgb.png
HySoP (Hybrid Simulation with Particles) is a library dedicated to high performance direct numerical simulation of fluid related problems based on semi-lagrangian particle methods, for hybrid architectures providing multiple compute devices including CPUs, GPUs or MICs.
Gallery
-=======
+-------
Passive scalar advection
.. image:: figures/advection_scalaire_passif.png
@@ -35,7 +49,7 @@ Playlist of several simulations
Programming elements
-=====================
+--------------------
The high level functionalities and the user interface are mainly written in Python using the object oriented programming model.
@@ -44,21 +58,9 @@ This choice was made because of the large software integration benefits it can p
The compiled Fortran and C++ compute backends allow us to integrate a variety of external dependencies by connecting them to the main HySoP python module with interface wrappers such as F2PY or SWIG. Note that many scientific libraries already provide Python interfaces so that they can be directly used in python without needing the user to implement his own wrapper. In addition to the compiled languages, the library offers the possibility to compile generated code just-in-time during execution. This is the case for OpenCL, the language used to drive OpenCL-compatible accelerators, like GPUs, but also to translate python methods to fast machine code by using the Numba just-in-time compiler.
References
-===========
+----------
HySoP has been used to produce numerical results in the following references:
.. bibliography::
:all:
-
-.. toctree::
- :maxdepth: 2
- :caption: Contents:
-
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
diff --git a/docs/sphinx/install_guide/index.rst b/docs/sphinx/install_guide/index.rst
new file mode 100644
index 0000000..3bea4a8
--- /dev/null
+++ b/docs/sphinx/install_guide/index.rst
@@ -0,0 +1,101 @@
+.. hysop_install_guide:
+
+HySoP installation guide
+========================
+
+
+HySoP is written in Python (main user interface and high level functionnalities) and Fortran.
+
+Quick start and install
+-----------------------
+
+::
+
+ cd path_to_build
+ cmake path_to_sources
+ make -j N
+ make install
+
+Note:
+
+* -jN for make command runs the build process on N processes. Choose a value of N that fits with your machine.
+* depending on your system you may need to set PYTHONPATH to where hysop has been installed::
+
+ export PYTHONPATH=hysop_install_path:${PYTHONPATH}
+
+ Check the end of cmake output, where the proper command will be indicated.
+
+
+
+
+Then just run python interactively and ::
+
+
+ >>> import hysop
+ >>> dir(hysop)
+
+
+or run python on an hysop example file::
+
+
+ mpirun -np 4 python your_file.py
+
+
+.. _hysop_config:
+
+Configuration options
+---------------------
+
+cmake configuration may be customized by user, using::
+
+ cmake -DOPTION_NAME=option_value path_to_source
+
+'OPTION_NAME' being one of the options described below. The most
+important options are listed here, other options are defined in
+`CMakeList.txt` file.
+
+Behavior options:
+
+* DOUBLEPREC=ON/OFF : Set default HySoP floating point
+ precision. Default=ON, ie double precision else single precision
+ will be used.
+* PROFILE=ON/OFF : Enable profiling mode for HySoP (default=ON).
+* VERBOSE=ON/OFF : Enable verbose mode for HySoP (default=ON).
+* DEBUG=ON/OFF : Enable debug mode for HySoP (default=OFF).
+
+Components options :
+
+* WITH_FFTW=ON/OFF : Link with fftw library (required for some HySoP solvers), (default=ON).
+* FFTW_ROOT : where to find fftw if it's not in a "standard" place.
+* WITH_EXTRAS=ON/OFF : Link with some extra fortran libraries (like arnoldi solver), (default=OFF).
+* WITH_GPU=ON/OFF : Use of GPU (required for some HySoP solvers), (default=ON)
+* WITH_SCALES=ON/OFF : to compile an HySoP version including scales (default = ON).
+* WITH_TESTS=ON/OFF : enable testing (i.e. prepare target "make test", default = OFF).
+* WITH_DOCUMENTATION=ON/OFF : Build Documentation. (default=OFF)
+
+
+.. _hysop_dependencies:
+
+Dependencies
+------------
+
+* python > 3.8 with the packages defined in `requirements.txt` file in source repository.
+* cmake > 3.0.2
+* a proper mpi implementation
+* fftw library with single and double precision both for serial and
+ mpi versions
+* hdf5
+* doxygen and python sphinx package for generating the documentation
+
+Additionally you may want to provide a working Fortran compiler, OpenCL platform, HPTT, llvm/llvmlite/numba, clFFT/gpyFFT, flint/arb/python-flint and tbb/mklfft. See the docker files to get instructions on how to configure and install these packages (hysop/ci/docker_images/ubuntu/jammy/Dockerfile).
+
+
+.. _hysop_install:
+
+What will be installed
+----------------------
+
+* python package in PREFIX/lib/pythonX.Y/site-packages/hysop/
+* library in PREFIX/lib/pythonX.Y/site-packages/hysop/lib
+* fortran modules in PREFIX/lib/pythonX.Y/site-packages/hysop/include/Modules
+* CMake configuration files in PREFIX/lib/pythonX.Y/site-packages/hysop/share/CMake
--
GitLab