From 1d734f3b82a014341f9bac646acd3838bea6f7c4 Mon Sep 17 00:00:00 2001 From: Stefan Pflueger Date: Thu, 21 Mar 2019 17:14:03 +0800 Subject: [PATCH] finished docu --- Tools/PythonInterface/PyComPWA.cpp | 17 +-------- doc/source/conf.py | 18 ++------- doc/source/cpp-modules.rst | 59 +++++++++++++++--------------- doc/source/examples.rst | 1 + doc/source/python-ui.rst | 40 ++++++++++---------- 5 files changed, 58 insertions(+), 77 deletions(-) diff --git a/Tools/PythonInterface/PyComPWA.cpp b/Tools/PythonInterface/PyComPWA.cpp index 8403aac372..0bb48d3564 100644 --- a/Tools/PythonInterface/PyComPWA.cpp +++ b/Tools/PythonInterface/PyComPWA.cpp @@ -2,11 +2,6 @@ // This file is part of the ComPWA framework, check // https://github.com/ComPWA/ComPWA/license.txt for details. -/// -/// \file -/// ComPWA Python Interface using pybind11 -/// - #include #include #include @@ -48,17 +43,9 @@ PYBIND11_MAKE_OPAQUE(std::vector); PYBIND11_DECLARE_HOLDER_TYPE(T, std::shared_ptr); PYBIND11_MAKE_OPAQUE(std::vector>); -/// -/// Python interface for ComPWA -/// -/// USAGE: -/// export PYTHONPATH=$PYTHONPATH:YOUR_COMPWA_BUILD_DIR/lib -/// python3 -/// >>> import pycompwa as pwa -/// >>> ... -/// PYBIND11_MODULE(pycompwa, m) { - m.doc() = "ComPWA python interface"; // optional module docstring + m.doc() = "ComPWA Python Interface\n" + "-----------------------\n"; // ------- Logging diff --git a/doc/source/conf.py b/doc/source/conf.py index 863edfad63..1bb1f95299 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -26,7 +26,7 @@ # build docu for c++ code subprocess.call('cd ../.. ; doxygen doc/Doxyfile;', shell=True) subprocess.call( - 'cd .. ; breathe-apidoc -f -o source/cpp -p ComPWA -g file xml', + 'cd .. ; breathe-apidoc -f -o source/cpp -p ComPWA -g file,namespace xml', shell=True) # build docu for python code subprocess.call( @@ -54,7 +54,6 @@ 'sphinx.ext.mathjax', 'sphinx.ext.ifconfig', 'sphinx.ext.viewcode', - # 'sphinx.ext.githubpages', 'sphinx.ext.napoleon', 'breathe' ] @@ -73,18 +72,9 @@ # General information about the project. project = 'ComPWA' -copyright = '2019, Mathias Michel, Stefan Pflueger, Peter Weidenkaff' +copyright = '2019, ComPWA Team' author = 'Mathias Michel, Stefan Pflueger, Peter Weidenkaff' -# The version info for the project you're documenting, acts as replacement for -# |version| and |release|, also used in various other places throughout the -# built documents. -# -# The short X.Y version. -version = '0.1a' -# The full version, including alpha/beta/rc tags. -release = '0.1a' - # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. # @@ -198,7 +188,7 @@ # author, documentclass [howto, manual, or own class]). latex_documents = [ (master_doc, 'ComPWA.tex', 'ComPWA Documentation', - 'Mathias Michel, Stefan Pflueger, Peter Weidenkaff', 'manual'), + author, 'manual'), ] @@ -219,6 +209,6 @@ # dir menu entry, description, category) texinfo_documents = [ (master_doc, 'ComPWA', 'ComPWA Documentation', - author, 'ComPWA', 'One line description of project.', + author, 'ComPWA', '', 'Miscellaneous'), ] diff --git a/doc/source/cpp-modules.rst b/doc/source/cpp-modules.rst index d0c58d3988..ad5ad6dbdb 100644 --- a/doc/source/cpp-modules.rst +++ b/doc/source/cpp-modules.rst @@ -1,46 +1,47 @@ C++ Modules =========== +All of the c++ code belongs to one of the 4 main module groups in ComPWA, +which are: -Ok here we can ask ourselves, what the "Core" library is really needed for. -I think all of the classes or files belong to one of the 4 groups. +- Data +- Physics/Models +- Esimators +- Optimizers +There is another supplementary module group `Tools`, which contains for example +integration algorithms. -The 4 main component groups in ComPWA are: +Data Modules +------------ --Data --Physics/Models --Esimators --Optimaizers +The Data modules is responsible for: -(There is one more group, Tools. It contains tools that do not belong specifically to one of these groups) - -The Data Modules ----------------- - -The data component group is responsible for: - -- transformation of data -- data IO +- transformation of different data structures +- data input/output - data generation (generators should be moved from tools to here) -.. doxygennamespace:: ComPWA::Data - :project: ComPWA +Physics Modules +--------------- -The Physics component group consists of several subcomponents: +The Physics modules -- definitions of all physics models (helicty formalism, ...) - -> they use the intensity and amplitude interface - -> they need the data to be evaluated, so as an input -- definition of kinematics class and its interface - -> they are responsible for transforming Event ../Tools/Plotting/ROOT/DalitzPlot.cppbased data to the kinematic variables - that are needed by the underlying theory of a model. - -> they take data as an input and output +- define Intensities and Amplitudes of physics models/theories + (i.e. helicty formalism, ...) +- define Kinematics classes, which are responsible for transforming Event based + data to the kinematic variables that are needed by the underlying theory. +Estimator Modules +----------------- -The estimator is responsible for determining the "closeness" of the model to the data. -It needs both the data and the data, obviously. +An estimator is responsible for determining the "closeness" of the model to the data. +Each estimator module has a specific way to estimate the closeness. +Optimizer Modules +----------------- -The optimizer needs the estimator, and a set of fit parameters that are obtained from the model. \ No newline at end of file +The Optimizer modules are responsible for finding the "optimal" set of +parameters of a model, by minimizing the "closeness" determined by a specific +Estimator. +Each Optimizer module implements a specific algorithm for finding the optimum. \ No newline at end of file diff --git a/doc/source/examples.rst b/doc/source/examples.rst index 5ce006de26..f4730ceef9 100644 --- a/doc/source/examples.rst +++ b/doc/source/examples.rst @@ -1,3 +1,4 @@ +.. _examples: Examples ======== diff --git a/doc/source/python-ui.rst b/doc/source/python-ui.rst index aa413e02a2..3fa0c4cf00 100644 --- a/doc/source/python-ui.rst +++ b/doc/source/python-ui.rst @@ -3,23 +3,25 @@ Python UI ========= -Explain a little how to use the python interface. mention pybind11. -mention its the preferred way to use compwa! -So to construct a model, we do not expect to use or need a dataset, and vice versa. -What is the way to use ComPWA: --First you readin your datasets. Alternatively you can generate new ones. --However for that you need a intensity or model first. -The kinematics and the intensity are created hand in hand using the builder. --If you have not read in data yet you can do that now, -or you can generate a dataset with Hit&Miss. --afterwards its rather straight forward. create an estimator - and give it the intensity and the data. --the estimator is given to the optimizer. +The Python User Interface is a python module named :code:`pycompwa`, built with +`pybind11 `_. +It is the recommended way to use ComPWA, since the user benefits from the python ease of use. -That's it. It would be straight forward to create the kinematics and the model first. -The only problem is the integration decorators that need a dataset. - So we need to give the decorators some integration strategy interface, - so that the model and kinematics can be created first. Then the integration strategy - can be actually initialized with a dataset. alternatively we can define a dataset - interface, which is empty in the beginning. that is passed to the builder. - then later on we can add actual data to the +.. note:: + Because the Python UI calls the c++ code in the background, you do not have to worry about speed. + It runs just as fast ;) + +The Python UI enables you to perform all of the tasks needed for your partial wave analysis: + +- load and create and intensity from a description +- load or generate data samples +- perform fits +- save & visualize results + +On how to use the Python UI, please refer to the :ref:`examples section`. +Below you can find the code documentation of **pycompwa**. + +.. automodule:: pycompwa + :members: + :undoc-members: + :show-inheritance: \ No newline at end of file