Skip to content
Snippets Groups Projects
Commit bb6b7002 authored by EXT Jean-Matthieu Etancelin's avatar EXT Jean-Matthieu Etancelin
Browse files

restructure doc with submodule

parent 57b2fd04
No related branches found
No related tags found
1 merge request!45Update "Development documentation"
Hide whitespace changes
Inline Side-by-side
Showing
with 44 additions and 501 deletions
.gitmodules 0 → 100644
+ 3
− 0
View file @ bb6b7002
[submodule "docs/hysop-doc"]
path = docs/hysop-doc
url = git@gricad-gitlab.univ-grenoble-alpes.fr:particle_methods/hysop-doc.git
docs/CMakeLists.txt
+ 39
− 25
View file @ bb6b7002
......@@ -14,8 +14,6 @@ if(WITH_DOCUMENTATION)
endif()
execute_process(COMMAND head -n1 ${CMAKE_SOURCE_DIR}/NOTICE OUTPUT_VARIABLE HYSOP_COPYRIGHT)
execute_process(COMMAND cat ${CMAKE_CURRENT_SOURCE_DIR}/sphinx/license-title.rst ${CMAKE_SOURCE_DIR}/LICENSE
OUTPUT_FILE ${CMAKE_CURRENT_BINARY_DIR}/sphinx/license.rst)
# --------------------- Doxygen setup ---------------------
find_package(Doxygen)
......@@ -58,22 +56,47 @@ if(WITH_DOCUMENTATION)
include(FindSphinxModule)
find_python_module(sphinx REQUIRED)
find_sphinx_module(sphinxcontrib bibtex REQUIRED)
#import ISSUE: find_sphinx_module(sphinxcontrib doxylink REQUIRED)
#import ISSUE: find_sphinx_module(sphinxcontrib doxylink REQUIRED)
if(EXISTS ${CMAKE_CURRENT_SOURCE_DIR}/hysop-doc)
message("[Doc] Full documentation build (user + generated from source)")
set(HYSOP_DOC_SPHINX_SRC ${CMAKE_CURRENT_SOURCE_DIR}/hysop-doc)
set(BIBTEXFILE "hysop.bib")
configure_file (
"${HYSOP_DOC_SPHINX_SRC}/hysop.bib"
"${CMAKE_CURRENT_BINARY_DIR}/sphinx/hysop.bib" @ONLY)
# list of all dirs where rst or other sphinx required files are located
set(sphinx_doc_dirs
_static
_templates
devel
examples
install_guide
getting_started
reference
users_guide
figures
)
else()
message("[Doc] Minimal documentation generated from sources.")
message("[Doc] In order to build the full documentation consider runnig `git submodule init && git submodule update`")
set(HYSOP_DOC_SPHINX_SRC ${CMAKE_CURRENT_SOURCE_DIR}/sphinx_minimal)
set(BIBTEXFILE "")
# list of all dirs where rst or other sphinx required files are located
set(sphinx_doc_dirs _static reference )
endif()
message("[Doc] Sphinx source dir: ${HYSOP_DOC_SPHINX_SRC}")
# generate sphinx conf file
configure_file (
"${CMAKE_CURRENT_SOURCE_DIR}/sphinx/conf.py.in"
"${HYSOP_DOC_SPHINX_SRC}/conf.py.in"
"${CMAKE_CURRENT_BINARY_DIR}/sphinx/conf.py" @ONLY)
# generate main sphinx index
configure_file (
"${CMAKE_CURRENT_SOURCE_DIR}/sphinx/index.rst"
"${HYSOP_DOC_SPHINX_SRC}/index.rst"
"${CMAKE_CURRENT_BINARY_DIR}/sphinx/index.rst" @ONLY)
configure_file (
"${CMAKE_CURRENT_SOURCE_DIR}/sphinx/hysop.bib"
"${CMAKE_CURRENT_BINARY_DIR}/sphinx/hysop.bib" @ONLY)
# --- Build sphinx targets ---
set(SPHINX_APIDOC sphinx-apidoc)
set(GENERATED_DOC ${CMAKE_CURRENT_BINARY_DIR}/sphinx/apidoc)
......@@ -84,33 +107,24 @@ if(WITH_DOCUMENTATION)
${HYSOP_BUILD_PYTHONPATH}/hysop
)
# list of all dirs where rst or other sphinx required files are located
set(sphinx_doc_dirs
_static
_templates
devel
examples
install_guide
getting_started
reference
users_guide
figures
)
# symbolic links to directories of sphinx_doc_dirs, created when make apidoc is called.
foreach(dir ${sphinx_doc_dirs})
add_custom_command(
TARGET apidoc PRE_BUILD
COMMAND ln -sf ${CMAKE_CURRENT_SOURCE_DIR}/sphinx/${dir}
COMMAND ln -sf ${HYSOP_DOC_SPHINX_SRC}/${dir}
${CMAKE_CURRENT_BINARY_DIR}/sphinx/)
endforeach()
file(GLOB files_rst ${CMAKE_CURRENT_SOURCE_DIR}/sphinx/*.rst)
file(GLOB files_rst ${HYSOP_DOC_SPHINX_SRC}/*.rst)
foreach(filepath ${files_rst})
get_filename_component(filename ${filepath} NAME)
configure_file (
"${CMAKE_CURRENT_SOURCE_DIR}/sphinx/${filename}"
"${HYSOP_DOC_SPHINX_SRC}/${filename}"
"${CMAKE_CURRENT_BINARY_DIR}/sphinx/${filename}" @ONLY)
endforeach()
## Complete the license.rst with actual LICENCE file content
execute_process(COMMAND cat ${HYSOP_DOC_SPHINX_SRC}/license.rst ${CMAKE_SOURCE_DIR}/LICENSE
OUTPUT_FILE ${CMAKE_CURRENT_BINARY_DIR}/sphinx/license.rst)
# --> use make html or make latex ... to build documentation.
set(SPHINX_EXECUTABLE sphinx-build )
......
docs/config/hysop.doxyfile.in
+ 1
− 1
View file @ bb6b7002
......@@ -51,7 +51,7 @@ PROJECT_BRIEF = "Particle Methods simulation on hybrid architectures"
# pixels and the maximum width should not exceed 200 pixels. Doxygen will copy
# the logo to the output directory.
PROJECT_LOGO = @CMAKE_CURRENT_SOURCE_DIR@/sphinx/figures/logo_hysop_nb.png
PROJECT_LOGO = @CMAKE_CURRENT_SOURCE_DIR@/sphinx_minimal/_static/logo_hysop_couleur.png
# The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) path
# into which the generated documentation will be written. If a relative path is
......
docs/config/mainpage.doxygen deleted 100644 → 0
+ 0
− 175
View file @ 57b2fd04
/** \mainpage HySoP
\anchor doxyHySoP
\section doxyHySoPIntro Introduction
HySoP (Hybrid SimulatiOn with Particles) is a library dedicated to flow simulation based on particular methods, on hybrid (multi CPU-GPU) architecture.
It is written in Python (high level functionnalities) and Fortran.
The library is also supposed to provide a common framework to the following libraries :
- the library of Adrien Magni (split3D and 2D for remeshing methods tests)
- an interface to a spectral software from LEGI (Scales)
- ...
===================================================================================================================
\section installhysop Install :
\subsection reqInstall Requirements
- a fortran compiler and a proper mpi implementation
- fftw
- cmake > 2.8
- a python implementation including numpy and mpi4py.
The install consists in 3 steps. First configuration of the package, makefile, setup.py and other files generation, then build of the underlying fortran libraries and of the python package and finally copy of the required files in the appropriate place.
We denote :
- SOURCEDIR as the directory which contains the sources (and this INSTALL file)
- BUILDDIR the directory where the package will be configured and build
- INSTALLDIR the directory where the package will be installed.
Those 3 locations must be different.
\subsection config Configuration :
You need to generate some makefile and a setup.py that fits with your platform, your compilers,
the libraries versions and so on. That will take place in BUILDDIR.
-# get SOURCEDIR (i.e. download the package any way you want)
-# create BUILDDIR. Any place, preferably local to your machine for efficiency reasons.
-# enforce a fortran compiler using FC environment variable
-# Change to BUILDDIR and run cmake
\code
mkdir $BUILDIR
cd $BUILDDIR
export FC=mpif90
cmake $SOURCEDIR
\endcode
At the end of this step BUILDDIR contains all makefiles, setup.py and other required files for compilation.
Some useful options for cmake :
- -DFFTW_ROOT : where to find fftw if it's not in a "standard" place.
- -DWITH_SCALES=ON/OFF : to compile an HySoP version including scales (default = on)
- -DWITH_TESTS=ON/OFF: enable testing (i.e. prepare target "make test", default = off)
example :
\code
mkdir /home/mylogin/buildHySoP
cd /home/mylogin/buildHySoP
export FC=mpif90
module load cmake-2.8
cmake -DFFTW_ROOT/softs/install/fftw3.1 ~/Softs/HySoP
\endcode
\subsection installDirConfig Install directory configuration :
Installation scheme is following Python distutils one (<a href="http://docs.python.org/2/install/">http://docs.python.org/2/install/</a>).
\subsubsection installDirConfigDefault Default configuration
Default setup leads to a 'User scheme installation' : <a href="http://docs.python.org/2/install/#alternate-installation-the-user-scheme">http://docs.python.org/2/install/#alternate-installation-the-user-scheme</a>. Files are installed into subdirectories of Python 'site.USER_BASE' (USER_BASE/lib/pythonX.Y/site-packages for UNIX systems).
After install completed, new files are located as follows :
- python package in USER_BASE/lib/pythonX.Y/site-packages/hysop/
- library in USER_BASE/lib/pythonX.Y/site-packages/hysop/lib
- fortran modules in USER_BASE/lib/pythonX.Y/site-packages/hysop/include/Modules
- CMake configuration files in USER_BASE/lib/pythonX.Y/site-packages/hysop/share/cmake
\subsubsection installDirConfigCustom Custom configuration
The other available setup is based on the Python 'Prefix scheme installation' : <a href="http://docs.python.org/2/install/#alternate-installation-unix-the-prefix-scheme">http://docs.python.org/2/install/#alternate-installation-unix-the-prefix-scheme</a>. You need to specify your prefix that replace the default USER_BASE. This prefix is passed to cmake through the variable PREFIX.
Example :
\code
cmake -DPREFIX=/my/custom/prefix $SOURCEDIR
\endcode
After install completed, new files are located as follows :
- 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
\subsection buildhysop Build
You need to build the underlying fortran libraries (mainly libhysop) and the python package.
Just run "make" to do both.
make python-build will run only python package building.
\subsection installhysop Install
Run :
\code
make python-install
\endcode
\subsection summaryInstall Summary
Default process :
\code
mkdir $BUILDDIR
cd $BUILDDIR
export FC=mpif90
cmake $SOURCEDIR
make -jN
make python-install
\endcode
Note : -jN for make command runs the build process on N processus. Choose a value of N that fits with your machine.
Other useful commands :
- make python-cleaninstall : to remove all installed files for the current build.
- make clean : to clean the build (remove modules, .o ...)
\subsection RemarkBrewedPython Note for OSX brewed python :
If you are using a Python distribution from the <a href="http://brew.sh/">Homebrew</a> package manager for OSX, the --user install option is disbled. Default installation will fail "error: can't combine user with prefix, exec_prefix/home, or install_(plat)base". Installation require a prefix:
\code
cmake -DPREFIX=$(brew --prefix) $SOURCEDIR
\endcode
and it will install package to '$(brew --prefix)/lib/pythonX.Y/site-packages', for example '/usr/local/lib/python3.8/site-packages'
A posible issue is that Python libraries and headers are not correctly discovered by CMake. We invite the user to carefully check that Python stuff in the cmake summary are correct and set the two variables : PYTHON_LIBRARY and PYTHON_INCLUDE_DIR.
For example:
\code
cmake -DPYTHON_LIBRARY=$(brew --prefix)/Cellar/python/3.8.5/Frameworks/Python.framework/Versions/3.8/Python \
-DPYTHON_INCLUDE_DIR=$(brew --prefix)/Cellar/python/3.8.5/Frameworks/Python.framework/Headers \
$SOURCEDIR
\endcode
===================================================================================================================
\section usehysop Use
Use as a classical python package :
\code
import hysop as hy
print hy.Box
\endcode
and so on ...
Several examples are available in the directory "examples" of the tgz distribution.
You can download them with "import examples.NAME"
To get the list of available NAMES, try
\code
import examples
help examples
\endcode
To run a parallel simulation try :
\code
mpirun -np 4 python ns3d.py
\endcode
*/
hysop-doc @ a09c2d1e
Subproject commit a09c2d1e571464d0e1368670b0a1a1cfe0736b2f
docs/sphinx/_static/layout.css deleted 100644 → 0
+ 0
− 37
View file @ 57b2fd04
@media (max-width:1000px) {
#sidebar { display: none; }
}
/* Background color for sidebar and navbar */
:root {
--menu-bg-color: #f1f6d0;
}
#sidebar {
padding-left: 10px;
background-color: var(--menu-bg-color);
}
/* body { */
/* padding-top: 120px */
/* } */
.navbar-default {
background-color: var(--menu-bg-color);
border-color: var(--menu-bg-color);
}
/* To remove project name displayed under logo*/
a.navbar-brand{
color: transparent!important;
}
/* index gallery scrolled or not ...*/
.index-gallery {
overflow-x: scroll;
overflow-y: hidden;
white-space: nowrap;
width: 100%;
margin-bottom: 1cm;
}
docs/sphinx/_static/logo_ljk_blanc2.png deleted 100644 → 0
+ 0
− 0
View file @ 57b2fd04
docs/sphinx/_static/logo_ljk_blanc2.png

5.91 KiB

docs/sphinx/_templates/layout.html deleted 100644 → 0
+ 0
− 5
View file @ 57b2fd04
{# Import the theme's layout. #}
{% extends "!layout.html" %}
{# Custom CSS overrides #}
{% set bootswatch_css_custom = ['_static/layout.css'] %}
docs/sphinx/_templates/menu.html deleted 100644 → 0
+ 0
− 8
View file @ 57b2fd04
<h3><a href="{{ pathto(master_doc) }}">Table Of Contents</a></h3>
{{ toctree(includehidden=True) }}
<h3>Links</h3>
<p><a class="reference external" href="https://gitlab.com/LJK/hysop" target="_top">HySoP on GitLab</a></p>
<p><a class="reference external" href="http://my.cdash.org/index.php?project=HySoP" target="_top">HySoP dashboard</a></p>
<p><a href="http://ljk.imag.fr/"><img src="{{ pathto('_static/logo_ljk_blanc2.png', 2) }}" " /></a></p>
docs/sphinx/devel/about_codegen.rst deleted 100644 → 0
+ 0
− 12
View file @ 57b2fd04
.. _about_codegen:
Code generation and autotuning
==============================
To Be done
see
:class:`~hysop.backend.device.autotunable_kernel.AutotunableKernel`
and hysop.symbolic
docs/sphinx/devel/about_doc.rst deleted 100644 → 0
+ 0
− 16
View file @ 57b2fd04
.. _about_doc:
How to document classes in HySoP
=================================
We try to fit as much as possible with `numpydoc guide <https://numpydoc.readthedocs.io/en/latest/>`_
guide standards.
See the files fields/continuous.py and operator/drag_and_lift.py which
are used as reference files for documentation.
Mind the need of `raw strings litterals <https://docs.python.org/3/reference/lexical_analysis.html#string-and-bytes-literals>`_ in python docstrings for keeping the `\stuff` from math
environments `".. :math:"`.
Mind the 'space' character before colon character `":"` in parameters or
attributes definitions.
docs/sphinx/devel/about_operators_graph.rst deleted 100644 → 0
+ 0
− 45
View file @ 57b2fd04
.. _about_operators_graph:
How HySoP deals with computational graphs of operators
======================================================
.. inheritance-diagram::
hysop.core.graph.computational_node.ComputationalGraphNode
hysop.core.graph.computational_graph.ComputationalGraph
hysop.core.graph.node_generator.ComputationalGraphNodeGenerator
hysop.core.graph.computational_operator.ComputationalGraphOperator
hysop.core.graph.computational_node_frontend.ComputationalGraphNodeFrontend
hysop.operator.directional.directional.DirectionalOperatorBase
hysop.operator.directional.directional.DirectionalOperatorGenerator
hysop.operator.directional.directional.DirectionalOperatorFrontend
hysop.numerics.splitting.directional_splitting.DirectionalSplitting
hysop.problem.Problem
:parts: 1
:caption: Inheritance diagram for HySoP computational graphs.
HySoP library is designed for the user to manipulate only operators
and problems. It internally build a directed graph of operators (low level
computations or data operations) for running a single a solver
iteration. Therefore, solving a Problem means running iteratively the
graph traversal. Order of inserting elements in the Problem using
:meth:`~hysop.problem.Problem.insert` (or graph using :meth:`~hysop.core.graph.computational_graph.ComputationalGraph.push_nodes`)
is important.
Two kind of object can be inserted into a graph:
- a :class:`~hysop.core.graph.computational_node.ComputationalGraphNode` by means of:
* an operator (:class:`~hysop.core.graph.computational_operator.ComputationalGraphOperator`)
* a sub-graph (:class:`~hysop.core.graph.computational_graph.ComputationalGraph`) when using a operator of operators
- an operator generator (:class:`~hysop.core.graph.node_generator.ComputationalGraphNodeGenerator` or
:class:`~hysop.core.graph.computational_node_frontend.ComputationalGraphNodeFrontend`). In that case, only generated
operators are inserted into graph, the generator itself is not inserted.
We distinguish directional operators from operators. Directional
operators must split into several operators (at least one per spatial
directions) using a :class:`~hysop.numerics.splitting.directional_splitting.DirectionalSplitting`. The nested
operators are sharing a common basis:
:class:`~hysop.operator.directional.directional.DirectionalOperatorBase` that are generated by :class:`~hysop.operator.directional.directional.DirectionalOperatorGenerator`. Directional operators generators will automatically insert also
transposition operators (see :ref:`about_work_arrays`).
docs/sphinx/devel/about_work_arrays.rst deleted 100644 → 0
+ 0
− 9
View file @ 57b2fd04
.. _about_work_arrays:
Temporary work arays in HySoP
=============================
TO BE DONE
See :class:`~hysop.core.memory.memory_request.MemoryRequest`
docs/sphinx/devel/coding_guidelines.rst deleted 100644 → 0
+ 0
− 11
View file @ 57b2fd04
.. _coding_guidelines:
How to write proper code in HySoP
=================================
Developper should follow python recommandations for code style.
Lower-level functions should be tested in the appropriate unitary
tests folders.
Higher-level functionalities should be exposed in an example file.
docs/sphinx/devel/fortran2python.rst deleted 100644 → 0
+ 0
− 32
View file @ 57b2fd04
.. _fortran2python:
Fortran to python interface
===========================
This page propose a tutorial to call some fortran subroutines in python within hysop.
Sources:
* some fortran files which contain some subroutines inside some modules
* a pyf file
TO BE DONE !!!
Kind values
-----------
According to f2py doc: "Currently, F2PY can handle only <type spec>(kind=<kindselector>) declarations where <kindselector> is a numeric integer (e.g. 1, 2, 4,...) but not a function call KIND(..) or any other expression. F2PY needs to know what would be the corresponding C type and a general solution for that would be too complicated to implement."
To overcome this, a .f2py_f2cmap is generated during the build, from hysop/f2py_f2cmap.in.
It contains all the required mappings defined as a dictionnary, like::
{'integer':{'c_int':'int'}, 'real':{'real64':'double', 'wp':'double'}}
In that example, a fortran :code:'real(kind=wp)' will be mapped into a double-precision real in python.
docs/sphinx/devel/hysop_validation.rst deleted 100644 → 0
+ 0
− 7
View file @ 57b2fd04
.. _hysop_validation:
HySoP validation
================
To be done
docs/sphinx/devel/index.rst deleted 100644 → 0
+ 0
− 20
View file @ 57b2fd04
.. _devel:
############################
HySoP Developers Guide
############################
This part is for developers of Hysop and provides guidelines on the "proper" ways to write python code, documentation, examples, tests ... in HySoP.
.. toctree::
:maxdepth: 2
about_doc
coding_guidelines
fortran2python
about_operators_graph
about_work_arrays
about_codegen
memo_sphinx
hysop_validation
docs/sphinx/devel/memo_sphinx.rst deleted 100644 → 0
+ 0
− 89
View file @ 57b2fd04
.. _memo_sphinx:
Reminder for sphinx utilities
=============================
Source code for this page::
To print source Code::
for i in range(3):
do un_truc()
Hyperlinks `HySoP Web`_.
.. math::
\begin{eqnarray}
a &=& \frac{1}{2}\\
\alpha &=& 3 \times \nabla \omega
\end{eqnarray}
To print a link to some HySoP object:
.. currentmodule:: hysop.operator.discrete
An example of a discrete operator, :class:`stretching.Conservative`, used to represent the
stretching part of NS.
Reference to :ref:`forces`.
Links
-----
* rst :
http://sphinx-doc.org/rest.html
* math support
http://sphinx-doc.org/ext/math.html
* numpydoc :
https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
.. _Hysop Web: https://forge.imag.fr
Which results in:
To print source Code::
for i in range(3):
do un_truc()
Hyperlinks `HySoP Web`_.
.. math::
\begin{eqnarray}
a &=& \frac{1}{2}\\
\alpha &=& 3 \times \nabla \omega
\end{eqnarray}
To print a link to some HySoP object:
.. currentmodule:: hysop.operator.discrete
An example of a discrete operator, :class:`stretching.Conservative`, used to represent the
stretching part of NS.
Reference to :ref:`forces`.
Links
-----
* rst :
http://sphinx-doc.org/rest.html
* math support
http://sphinx-doc.org/ext/math.html
* numpydoc :
https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
.. _Hysop Web: https://forge.imag.fr
docs/sphinx/examples/index.rst deleted 100644 → 0
+ 0
− 9
View file @ 57b2fd04
.. _examples:
############################
HySoP Examples
############################
Some tutorials and examples:
- on how to use HySoP
- demos about HySoP perf and capabilities
docs/sphinx/figures/PolesExample.png deleted 100644 → 0
+ 0
− 0
View file @ 57b2fd04
docs/sphinx/figures/PolesExample.png

241 KiB

0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment