Skip to content
Snippets Groups Projects
Commit 14b002ab authored by Simon Labarthe's avatar Simon Labarthe
Browse files

changes for doc compilation

parent 434e0382
No related branches found
No related tags found
No related merge requests found
Pipeline #196105 passed with warnings
Showing
with 498 additions and 5 deletions
......@@ -2,7 +2,7 @@
Changelog
=========
0.0.0 (2024-02-02)
0.1.0 (2024-02-03)
------------------
* First release on Zenodo
* VDA-BI toolbox used for the paper "Biology-Informed inverse problems for insect pests detection using pheromone sensors"
......@@ -49,7 +49,7 @@ To set up `pherosensor-toolbox` for local development:
Now you can make your changes locally.
4. When you're done making changes run all the checks with `tox`_ one command::
4. When you're done making changes run all the checks with `tox` one command::
tox
......
......@@ -11,7 +11,7 @@ Installation
You can install the in-development version with::
pip install git+ssh://git@forgemia.inra.fr/simon.labarthe/pherosensor-toolbox.git@main
pip install git+ssh://git@forgemia.inra.fr/pherosensor/pherosensor-toolbox.git@main
Development
......@@ -37,3 +37,20 @@ Note, to combine the coverage data from all the tox environments run:
- ::
PYTEST_ADDOPTS=--cov-append tox
Building the docs
=================
You can install sphinx and sphinx-rtd-theme with::
pip install sphinx sphinx-rtd-theme
Then, you can do::
cd docs
and::
make html
The documentations (in html) are then stored in the folder 'build/html'
# Minimal makefile for Sphinx documentation
#
# You can set these variables from the command line, and also
# from the environment for the first two.
SPHINXOPTS ?=
SPHINXBUILD ?= sphinx-build
SOURCEDIR = source
BUILDDIR = build
# Put it first so that "make" without argument is like "make help".
help:
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
.PHONY: help Makefile
# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
@ECHO OFF
pushd %~dp0
REM Command file for Sphinx documentation
if "%SPHINXBUILD%" == "" (
set SPHINXBUILD=sphinx-build
)
set SOURCEDIR=source
set BUILDDIR=build
%SPHINXBUILD% >NUL 2>NUL
if errorlevel 9009 (
echo.
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
echo.installed, then set the SPHINXBUILD environment variable to point
echo.to the full path of the 'sphinx-build' executable. Alternatively you
echo.may add the Sphinx directory to PATH.
echo.
echo.If you don't have Sphinx installed, grab it from
echo.https://www.sphinx-doc.org/
exit /b 1
)
if "%1" == "" goto help
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
goto end
:help
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
:end
popd
.. include:: ../../AUTHORS.rst
.. include:: ../../CHANGELOG.rst
# Configuration file for the Sphinx documentation builder.
#
# For the full list of built-in configuration values, see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html
# -- Project information -----------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
import os
import sys
sys.path.insert(0, os.path.abspath('../../src'))
project = 'pheromone-toolbox'
copyright = '2024, Thibault Malou'
author = 'Thibault Malou'
release = '0.1.0'
# -- General configuration ---------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
extensions = ['sphinx.ext.autodoc',
'sphinx.ext.doctest',
'sphinx.ext.intersphinx',
'sphinx.ext.todo',
'sphinx.ext.coverage',
'sphinx.ext.mathjax',
'sphinx.ext.ifconfig',
'sphinx.ext.viewcode',
'sphinx.ext.githubpages',
'sphinx.ext.napoleon',]
# Napoleon settings
napoleon_google_docstring = True
napoleon_numpy_docstring = True
napoleon_include_init_with_doc = True
napoleon_include_private_with_doc = True
napoleon_include_special_with_doc = True
napoleon_use_admonition_for_examples = False
napoleon_use_admonition_for_notes = False
napoleon_use_admonition_for_references = False
napoleon_use_ivar = False
napoleon_use_param = True
napoleon_use_rtype = True
templates_path = ['_templates']
exclude_patterns = []
autodoc_mock_imports = ['numpy',
'geopandas',
'matplotlib',
'scipy',
'imageio',
'pandas',
'shapely',
'joblib'
]
# -- Options for HTML output -------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
html_theme = 'sphinx_rtd_theme'
html_static_path = ['_static']
.. include:: ../../CONTRIBUTING.rst
.. pheromone-toolbox documentation master file, created by
sphinx-quickstart on Sat May 4 12:01:02 2024.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Welcome to pheromone-toolbox's documentation!
=============================================
.. toctree::
:maxdepth: 2
:caption: Contents:
readme
authors
changelog
contributing
installation
usage
modules
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
============
Installation
============
At the command line::
pip install git+ssh://git@forgemia.inra.fr/pherosensor/pherosensor-toolbox.git@main
src
===
.. toctree::
:maxdepth: 4
pheromone_dispersion
pherosensor
source_localization
utils
pheromone\_dispersion package
=============================
Submodules
----------
pheromone\_dispersion.advection\_operator module
------------------------------------------------
.. automodule:: pheromone_dispersion.advection_operator
:members:
:undoc-members:
:show-inheritance:
pheromone\_dispersion.cli module
--------------------------------
.. automodule:: pheromone_dispersion.cli
:members:
:undoc-members:
:show-inheritance:
pheromone\_dispersion.convection\_diffusion\_2D module
------------------------------------------------------
.. automodule:: pheromone_dispersion.convection_diffusion_2D
:members:
:undoc-members:
:show-inheritance:
pheromone\_dispersion.deposition\_coeff module
----------------------------------------------
.. automodule:: pheromone_dispersion.deposition_coeff
:members:
:undoc-members:
:show-inheritance:
pheromone\_dispersion.diffusion\_operator module
------------------------------------------------
.. automodule:: pheromone_dispersion.diffusion_operator
:members:
:undoc-members:
:show-inheritance:
pheromone\_dispersion.diffusion\_tensor module
----------------------------------------------
.. automodule:: pheromone_dispersion.diffusion_tensor
:members:
:undoc-members:
:show-inheritance:
pheromone\_dispersion.gaussian\_plume module
--------------------------------------------
.. automodule:: pheromone_dispersion.gaussian_plume
:members:
:undoc-members:
:show-inheritance:
pheromone\_dispersion.geom module
---------------------------------
.. automodule:: pheromone_dispersion.geom
:members:
:undoc-members:
:show-inheritance:
pheromone\_dispersion.identity\_operator module
-----------------------------------------------
.. automodule:: pheromone_dispersion.identity_operator
:members:
:undoc-members:
:show-inheritance:
pheromone\_dispersion.reaction\_operator module
-----------------------------------------------
.. automodule:: pheromone_dispersion.reaction_operator
:members:
:undoc-members:
:show-inheritance:
pheromone\_dispersion.source\_term module
-----------------------------------------
.. automodule:: pheromone_dispersion.source_term
:members:
:undoc-members:
:show-inheritance:
pheromone\_dispersion.velocity module
-------------------------------------
.. automodule:: pheromone_dispersion.velocity
:members:
:undoc-members:
:show-inheritance:
Module contents
---------------
.. automodule:: pheromone_dispersion
:members:
:undoc-members:
:show-inheritance:
pherosensor package
===================
Submodules
----------
pherosensor.cli module
----------------------
.. automodule:: pherosensor.cli
:members:
:undoc-members:
:show-inheritance:
Module contents
---------------
.. automodule:: pherosensor
:members:
:undoc-members:
:show-inheritance:
.. include:: ../../README.rst
source\_localization package
============================
Submodules
----------
source\_localization.adjoint\_convection\_diffusion\_2D module
--------------------------------------------------------------
.. automodule:: source_localization.adjoint_convection_diffusion_2D
:members:
:undoc-members:
:show-inheritance:
source\_localization.control module
-----------------------------------
.. automodule:: source_localization.control
:members:
:undoc-members:
:show-inheritance:
source\_localization.cost module
--------------------------------
.. automodule:: source_localization.cost
:members:
:undoc-members:
:show-inheritance:
source\_localization.gradient\_descent module
---------------------------------------------
.. automodule:: source_localization.gradient_descent
:members:
:undoc-members:
:show-inheritance:
source\_localization.obs module
-------------------------------
.. automodule:: source_localization.obs
:members:
:undoc-members:
:show-inheritance:
source\_localization.population\_dynamique module
-------------------------------------------------
.. automodule:: source_localization.population_dynamique
:members:
:undoc-members:
:show-inheritance:
source\_localization.proximal\_gradient module
----------------------------------------------
.. automodule:: source_localization.proximal_gradient
:members:
:undoc-members:
:show-inheritance:
Module contents
---------------
.. automodule:: source_localization
:members:
:undoc-members:
:show-inheritance:
=====
Usage
=====
To use pherosensor-toolbox in a project::
import pherosensor
utils package
=============
Submodules
----------
utils.generate\_gif module
--------------------------
.. automodule:: utils.generate_gif
:members:
:undoc-members:
:show-inheritance:
utils.geom\_to\_shapefile module
--------------------------------
.. automodule:: utils.geom_to_shapefile
:members:
:undoc-members:
:show-inheritance:
utils.plot\_colormap module
---------------------------
.. automodule:: utils.plot_colormap
:members:
:undoc-members:
:show-inheritance:
utils.plot\_cost module
-----------------------
.. automodule:: utils.plot_cost
:members:
:undoc-members:
:show-inheritance:
utils.plot\_ctrl module
-----------------------
.. automodule:: utils.plot_ctrl
:members:
:undoc-members:
:show-inheritance:
utils.plot\_ctrl\_error module
------------------------------
.. automodule:: utils.plot_ctrl_error
:members:
:undoc-members:
:show-inheritance:
utils.plot\_env\_param module
-----------------------------
.. automodule:: utils.plot_env_param
:members:
:undoc-members:
:show-inheritance:
utils.plot\_obs module
----------------------
.. automodule:: utils.plot_obs
:members:
:undoc-members:
:show-inheritance:
utils.superlevel\_set module
----------------------------
.. automodule:: utils.superlevel_set
:members:
:undoc-members:
:show-inheritance:
Module contents
---------------
.. automodule:: utils
:members:
:undoc-members:
:show-inheritance:
......@@ -7,6 +7,7 @@ from pheromone_dispersion.velocity import Velocity
def sum_advection_flux_given_U(U, x, msh):
"""
compute the sum over a cell of the flux of the advection term for a given velocity field
- TO BE DONE:
* change the BC, for now: no income, change for: a given income
- input:
......@@ -67,6 +68,7 @@ class Advection(LinOp):
def __init__(self, U, msh):
"""
Instanciation of the class.
- input:
* U: object of the class Velocity
* msh: object of the class MeshRect2D
......@@ -99,17 +101,20 @@ class Advection(LinOp):
def at_current_time(self, tc, U):
"""
Update the velocity field U at a given time.
- input:
* tc: the current time
* U: object of the class Velocity, velocity field to be updated
- do:
update the velocity field U and its attribute using the method at_current_time of the class Velocity
* update the velocity field U and its attribute using the method at_current_time of the class Velocity
"""
U.at_current_time(tc)
def _matvec(self, x_out):
"""
Compute the image (matrix-vector product) of the convection linear operator for a given vector of concentration
- input:
* x_out:
numpy array of shape (msh.x.size*msh.y.size, ),
......@@ -130,6 +135,7 @@ class Advection(LinOp):
Compute the image (matrix-vector product) of the flux part of the adjoint of the convection linear operator
for a given vector of concentration.
This flux part of the adjoint operator is the adjoint operator if the velocity field has a divergence equal to 0
- input:
* x_out:
numpy array of shape (msh.x.size*msh.y.size, ),
......@@ -148,6 +154,7 @@ class Advection(LinOp):
def _matmat(self, x_out):
"""
Compute the image (matrix-matrix product) of the advection linear operator for a given (matrix of) concentration
- input:
* x_out:
numpy array of (shape msh.x.size*msh.y.size, msh.x.size*msh.y.size),
......@@ -171,6 +178,7 @@ class AdvectionAdjoint(LinOp):
def __init__(self, U, msh):
"""
Instanciation of the class.
- input:
* U: object of the class Velocity
* msh: object of the class MeshRect2D
......@@ -203,6 +211,7 @@ class AdvectionAdjoint(LinOp):
def at_current_time(self, tc):
"""
Update the attributes U and minus_U of the class at a given time.
- input:
* tc: the current time
"""
......@@ -212,6 +221,7 @@ class AdvectionAdjoint(LinOp):
def _matvec(self, x_out):
"""
Compute the image (matrix-vector product) of the adjoint of the convection linear operator for a given vector of concentration
- input:
* x_out:
numpy array of shape (msh.x.size*msh.y.size, ),
......@@ -230,6 +240,7 @@ class AdvectionAdjoint(LinOp):
def _matmat(self, x_out):
"""
Compute the image (matrix-matrix product) of the adjoint advection linear operator for a given (matrix of) concentration
- input:
* x_out:
numpy array of (shape msh.x.size*msh.y.size, msh.x.size*msh.y.size),
......
......@@ -28,6 +28,7 @@ class DiffusionConvectionReaction2DEquation:
def __init__(self, U, K, coeff_depot, S, msh, time_discretization='semi-implicit', tol_inversion=1e-14):
"""
Instanciation of the class.
- input:
* msh: object of the class MeshRect2D
* U: object of the class Velocity
......@@ -148,6 +149,7 @@ class DiffusionConvectionReaction2DEquation:
def set_source(self, value, t=None):
"""
Update the source term with the values provided as input
- input:
* value: numpy array of shape (t.size, msh.y.size, msh.x.size), the new values of the source term
* t: numpy array of shape (t.size,), the vector containing the associated times, by default None if the source is stationnary
......@@ -157,6 +159,7 @@ class DiffusionConvectionReaction2DEquation:
def at_current_time(self, tc, i=None):
"""
Update the linear operators of the PDE (attributes A, D and S of the class) at a given time.
- input:
* tc: the current time
"""
......@@ -181,6 +184,7 @@ class DiffusionConvectionReaction2DEquation:
"""
solve the PDE for one time step
inverse the linear system (I + dt (- D + R)).c^{n+1} = c^n + dt (- A.c^n + S)
- input:
* c: numpy array of shape (msh.y.size, msh.x.size), contains the concentration of pheromones at the previous time step
- output:
......@@ -202,6 +206,7 @@ class DiffusionConvectionReaction2DEquation:
def solver(self, save_all=False, path_save='./save/', display_flag=True):
"""
solve the PDE on the whole time window
- input:
* save_all:
boolean, False by default,
......@@ -299,6 +304,7 @@ class DiffusionConvectionReaction2DEquation:
def solver_save_all(self, path_save='./save/', display_flag=True, save_rate=1000):
"""
solve the PDE on the whole time window
- input:
* save_all:
boolean, False by default,
......@@ -395,6 +401,7 @@ class DiffusionConvectionReaction2DEquation:
def solver_est_at_obs_times(self, obs, display_flag=True):
"""
solve the PDE on the whole time window and store the resulting estimations of the concentration at the observations times
- TO DO:
* check that the function works
- input:
......@@ -483,6 +490,7 @@ class DiffusionConvectionReaction2DEquation:
"""
solve the steady-state version of the PDE
inverse the linear system (- D + A + R) c = S using a conjugate gradient method
- output:
* numpy array of shape (msh.y.size, msh.x.size), resulting concentration at the steady state
"""
......
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment