Skip to content

Commit 79067b9

Browse files
ewanwmewanwm
authored
More Documentation (#135)
* restructure into of docs and add installation instructions * add sphinx-tabs module to documentation build * add section on benchmarking in the developer docs * add quick start guide * add user manual page...... to be filled out later * add section on automatic differentiation to tensor part of QSG * add info on PCH * add simple-tensor.py script which has all code from the tensor section of the QSG * add small section on testing
1 parent ff981ce commit 79067b9

File tree

12 files changed

+791
-10
lines changed

12 files changed

+791
-10
lines changed

‎doc/source/conf.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@
1313
# -- General configuration ---------------------------------------------------
1414
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
1515

16-
extensions = [ 'sphinx.ext.autodoc', 'breathe', "sphinx.ext.graphviz" ]
16+
extensions = [ 'sphinx.ext.autodoc', 'breathe', "sphinx.ext.graphviz", "sphinx_tabs.tabs" ]
1717

1818
breathe_projects = {"nuTens": "doxygen/xml"}
1919
breathe_default_project = "nuTens"

‎doc/source/development.rst‎

Lines changed: 100 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,32 @@
11

2-
Profiling
3-
=========
2+
.. _testing:
3+
4+
Testing 🧪
5+
==========
6+
7+
Tests live in the `tests <https://github.com/ewanwm/nuTens/tree/main/tests>`_ directory. For c++ tests we use Googles `GoogleTest <http://google.github.io/googletest/primer.html>`_ framework and for python tests we use `pytest <https://docs.pytest.org/en/stable/>`_ in order to organise our tests and more easily track them.
8+
Tests are run as part of our continuous integration and generally for every pull request all tests should pass (i.e. your new change should not break the behaviour of existing code).
9+
10+
If you are adding a new feature to nuTens, you should also include some tests of your new feature.
11+
These tests should ideally cover all of the new code that you are adding and should be as "simple" as possible i.e. they should rely as little as possible on other parts of the code.
12+
Try to test the smallest possible "units" of your code on their own, ideally against externally calculated values (unit tests), and also the overall behaviour of your new feature (integration tests).
13+
14+
If your new feature has a python interface, new python tests should also be added.
15+
16+
Coverage
17+
--------
18+
19+
The coverage (how much of the source code appears in tests) of our test suite is tracked using `CodeCov <https://codecov.io/github/ewanwm/nuTens>`_.
20+
We would ideally like for this to be as close as possible to 100% (though as you can see we aren't quite there yet).
21+
22+
For this reason, new features should be covered as close as possible to 100%.
23+
You will be able to see the coverage of added code in any pull request.
24+
Unless there is a good reason for not doing so, new code should only be merged if it is fully covered by new tests.
25+
26+
.. _profiling:
27+
28+
Profiling 📊
29+
============
430

531
nuTens is instrumented with a custom profiler. Compiling with the cmake option
632

@@ -22,6 +48,17 @@ will enable the profiling information. You can then profile an application by ad
2248
// the rest of your application
2349
// ...
2450
51+
and adding the NT_PROFILE_ENDSESSION() to the end:
52+
53+
.. code::
54+
55+
// ...
56+
// the rest of your application
57+
// ...
58+
59+
NT_PROFILE_ENDSESSION()
60+
61+
}
2562
2663
Now after running that application, a file will be produced called "<name of the profile>.json" containing profile information.
2764

@@ -33,7 +70,67 @@ https://profiler.firefox.com/
3370

3471
If using chrome, open chrome and type
3572

36-
chrome://tracing
73+
.. code::
74+
75+
chrome://tracing
3776
3877
You can then drag and drop the json profile into the profiler.
3978

79+
.. _benchmarking:
80+
81+
Benchmarking 📉
82+
===============
83+
84+
nuTens uses `Googles benchmark library <https://github.com/google/benchmark>`_ to perform benchmarking.
85+
86+
To compile the benchmark executable you will need to configure nuTens with the cmake option
87+
88+
.. code::
89+
90+
-DNT_ENABLE_BENCHMARK=ON
91+
92+
Then after make installing, there will be a ``benchmarks/`` directory in the build directory containing the ``benchmark`` executable.
93+
94+
You can run this with all command line options available that are specified in the `benchmark user guide <https://github.com/google/benchmark/blob/main/docs/user_guide.md>`_.
95+
96+
This is useful to run to compare speed after your changes to the code with the main branch (see below). In fact, this is done as part of the continuous integration process.
97+
98+
Code that causes serious performance regressions in the benchmarks should be very carefully considered before being committed to the main branch.
99+
100+
Results
101+
-------
102+
103+
the main branch is benchmarked every time there is a commit, and the results are tracked uing `Bencher <https://bencher.dev>`_. Each benchmark consists of calculating neutrino oscillations for 1024 random variations of parameters in the 3 flavour formalism for 1024 neutrino energies in vacuum and in constant density matter:
104+
105+
.. raw:: html
106+
107+
<p align="center">
108+
<a
109+
href="https://bencher.dev/perf/nutens?lower_value=false&upper_value=false&lower_boundary=false&upper_boundary=false&x_axis=date_time&branches=9fb1fa7d-4e90-4889-a370-8488dea67849&testbeds=49818c12-6c02-42a2-bbbb-697a772d8991&benchmarks=700b0d80-ef19-4fac-bc84-45d558df1801&measures=fc8c0fd1-3b41-4ce7-826c-74843c2ea71c&start_time=1718212890927&tab=plots&plots_search=36aa4017-86a3-47ff-8c39-b77045d5268b&key=true&reports_per_page=4&branches_per_page=8&testbeds_per_page=8&benchmarks_per_page=8&plots_per_page=8&reports_page=1&branches_page=1&testbeds_page=1&benchmarks_page=1&plots_page=1">
110+
<img
111+
src="https://api.bencher.dev/v0/projects/nutens/perf/img?branches=9fb1fa7d-4e90-4889-a370-8488dea67849&testbeds=49818c12-6c02-42a2-bbbb-697a772d8991&benchmarks=700b0d80-ef19-4fac-bc84-45d558df1801&measures=fc8c0fd1-3b41-4ce7-826c-74843c2ea71c&start_time=1718212890927&title=Const+Density+Osc+Benchmark"
112+
title="Const Density Osc Benchmark"
113+
alt="Const Density Osc Benchmark for nuTens - Bencher" /></a>
114+
</p>
115+
116+
<p align="center">
117+
<a
118+
href="https://bencher.dev/perf/nutens?lower_value=false&upper_value=false&lower_boundary=false&upper_boundary=false&x_axis=date_time&branches=9fb1fa7d-4e90-4889-a370-8488dea67849&testbeds=49818c12-6c02-42a2-bbbb-697a772d8991&benchmarks=bd0cdb00-102a-422a-a672-7f297e65fd7e&measures=fc8c0fd1-3b41-4ce7-826c-74843c2ea71c&start_time=1718212962301&tab=plots&plots_search=097d254e-f328-4643-9e51-7b37436df615&key=true&reports_per_page=4&branches_per_page=8&testbeds_per_page=8&benchmarks_per_page=8&plots_per_page=8&reports_page=1&branches_page=1&testbeds_page=1&benchmarks_page=1&plots_page=1">
119+
<img
120+
src="https://api.bencher.dev/v0/projects/nutens/perf/img?branches=9fb1fa7d-4e90-4889-a370-8488dea67849&testbeds=49818c12-6c02-42a2-bbbb-697a772d8991&benchmarks=bd0cdb00-102a-422a-a672-7f297e65fd7e&measures=fc8c0fd1-3b41-4ce7-826c-74843c2ea71c&start_time=1718212962301&title=Vacuum+Osc+Benchmark"
121+
title="Vacuum Osc Benchmark"
122+
alt="Vacuum Osc Benchmark for nuTens - Bencher"
123+
/></a>
124+
125+
</p>
126+
127+
Precompiled Headers 🗿
128+
======================
129+
130+
nuTens has the option to use precompiled headers which can significantyly speed up build times.
131+
To enable this feature use the :code:`NT_USE_PCH` cmake option:
132+
133+
.. code::
134+
135+
cmake [other options] -DNT_USE_PCH=ON <path to src>
136+

‎doc/source/index.rst‎

Lines changed: 26 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -4,22 +4,43 @@
44
nuTens documentation
55
====================
66

7-
nuTens is an engine for calculating neutrino oscillation probabilities in an extremely flexible way using tensors, allowing for automatic differentiation and extremely fast execution.
7+
nuTens is an engine for calculating neutrino oscillation probabilities in an extremely flexible way using tensors, allowing the calculations to be differentiable with fast execution.
8+
9+
.. raw:: html
10+
11+
<div align="center">
12+
13+
<img alt="DOI" src = https://zenodo.org/badge/824239795.svg href=https://doi.org/10.5281/zenodo.15873397>
14+
<img alt="GitHub Release" src = https://img.shields.io/github/v/release/ewanwm/nuTens?color=blue href=https://github.com/ewanwm/nuTens/releases>
15+
<img alt="PyPI - Version" src = https://img.shields.io/pypi/v/nuTens?color=blue href=https://pypi.org/project/nuTens/>
16+
<img alt="GitHub License" src = https://img.shields.io/github/license/ewanwm/nuTens?color=green href=https://github.com/ewanwm/nuTens/blob/main/LICENSE>
17+
18+
</div>
19+
20+
----
821

922
.. toctree::
10-
:caption: 🚀 Getting Started
1123

1224
intro.rst
1325

1426
.. toctree::
15-
:caption: 🖥️ For Developers
27+
:caption: 🚀 Getting Started
1628

17-
development.rst
29+
installation.rst
30+
quick-start-guide/quick-start-guide.rst
1831

1932
.. toctree::
2033
:maxdepth: 1
21-
:caption: 📖 References:
34+
:caption: 📖 References
2235

36+
user-manual.rst
2337
cpp-api.rst
2438
python-api.rst
2539
GitHub 🔗 <https://github.com/ewanwm/nuTens>
40+
Examples 🔗 <https://github.com/ewanwm/nuTens/tree/main/examples>
41+
42+
.. toctree::
43+
:caption: 🖥️ For Developers
44+
45+
development.rst
46+

‎doc/source/installation.rst‎

Lines changed: 162 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,162 @@
1+
2+
============
3+
Installation
4+
============
5+
6+
Installing Using Pip
7+
--------------------
8+
9+
A pypi distribution of nuTens is provided, the page for which can be found `here <https://pypi.org/project/nuTens/>`_.
10+
11+
This means that you can install nuTens via pip using the command
12+
13+
.. code::
14+
15+
pip install nuTens
16+
17+
18+
.. note::
19+
20+
The python interface can be installed manually after cloning the repository using pip by running
21+
22+
.. code::
23+
24+
pip install .
25+
26+
in the root directory of nuTens.
27+
28+
This may be useful if you are developing nuTens.
29+
30+
31+
Installing From Source
32+
----------------------
33+
34+
Step 1 is to get your hands on a copy of the nuTens source code.
35+
36+
To do this you can either clone the repository from github
37+
38+
.. code::
39+
40+
git clone git@github.com:ewanwm/nuTens.git
41+
42+
and checkout the release you want
43+
44+
.. code::
45+
46+
git checkout tags/v<X.Y.Z>
47+
48+
or visit the `releases <https://github.com/ewanwm/nuTens/releases>`_ page.
49+
50+
Requirements
51+
^^^^^^^^^^^^
52+
53+
CMake
54+
"""""
55+
Should work with most modern versions. If you wish to use precompiled headers to speed up build times you will need CMake > 3.16.
56+
57+
Compiler
58+
""""""""
59+
Requires compiler with support for c++17 standard - Tested with gcc and clang
60+
61+
PyTorch
62+
"""""""
63+
Currently pytorch is the only "backend" supported by nuTens. See https://pytorch.org/ for instructions on how to install it yourself, or you can use the requirements file provided as part of nuTens:
64+
65+
.. code::
66+
67+
pip install -r PyTorch_requirements.txt
68+
69+
Building
70+
^^^^^^^^
71+
72+
Create a build directory
73+
74+
.. code::
75+
76+
mkdir build
77+
cd build
78+
79+
Configure using cmake (see :ref:`cmake-config-options` for more information on available build options).
80+
One particularly important option to be aware of here is ``NT_ENABLE_PYTHON=<ON/OFF>`` which determines whether or not to build the nuTens python interface.
81+
82+
.. note::
83+
If you build the python interface using this method (specifying ``-DNT_ENABLE_PYTHON=ON`` during cmake configuration) you will need to tell python where it can find the nuTens python module by setting the ``PYTHONPATH`` environment variable:
84+
85+
.. code::
86+
87+
export PYTHONPATH=<path to nuTens build directory>:$PYTHONPATH
88+
89+
.. code::
90+
91+
cmake -DCMAKE_PREFIX_PATH=`python3 -c 'import torch;print(torch.utils.cmake_prefix_path)'` <path to source code>
92+
93+
Now build!
94+
95+
.. code::
96+
97+
make <-j Njobs> && make install
98+
99+
Verifying Your Installation
100+
^^^^^^^^^^^^^^^^^^^^^^^^^^^
101+
102+
Once you've installed nuTens, you can verify your installation by running
103+
104+
.. code::
105+
106+
make test
107+
108+
and (if you have installed the python interface)
109+
110+
.. code::
111+
112+
pip install pytest
113+
pytest tests
114+
115+
Known Issues
116+
------------
117+
118+
When trying to run using the python interface you may get complaints relating to not being able to locate `libtorch.so` or `libtorch_cpu.so` library files. If so running
119+
120+
.. code::
121+
122+
export LD_LIBRARY_PATH=`python3 -c 'import os;import torch;print(os.path.abspath(torch.__file__)[:-11])'`/lib:$LD_LIBRARY_PATH
123+
124+
125+
should allow these files to be found
126+
127+
128+
.. _cmake-config-options:
129+
130+
CMake Configuration Options
131+
---------------------------
132+
133+
========================== ============================================================================ =======
134+
Option Description Default
135+
========================== ============================================================================ =======
136+
NT_USE_TORCH Use torch as the backend for dealing with tensors ON
137+
NT_TORCH_FROM_PIP If it is not found, torch will be installed using pip ON
138+
NT_ALLOW_GLOBAL_PYTHON_ENV Allow installing pip packages in global python environment (Not recommended) OFF
139+
NT_COMPILE_TESTS Whether or not to compile the test library ON
140+
NT_ENABLE_PYTHON Enable compilation of the python interface OFF
141+
========================== ============================================================================ =======
142+
143+
For Developers
144+
^^^^^^^^^^^^^^
145+
146+
These options are a bit more "advanced" and probably only of interest to anyone actually writing nuTens library code.
147+
148+
====================== ===================================================================================================================================================================================== =======
149+
Option Description Default
150+
====================== ===================================================================================================================================================================================== =======
151+
NT_TORCH_FROM_SCRATCH If it is not found, torch will be compiled from scratch using CPM (very slow but maybe useful for debugging builds) OFF
152+
NT_ENABLE_BENCHMARKING Whether or not to compile benchmark executables OFF
153+
NT_BUILD_TIMING Whether or not to time the build process OFF
154+
NT_LOG_LEVEL Set the log level to one of <SILENT ERROR WARNING INFO DEBUG TRACE> INFO
155+
NT_PROFILING Enable profiling (see :ref:`profiling`) OFF
156+
NT_TEST_COVERAGE Add flags to allow checking of test coverage OFF
157+
NT_USE_PCH Use precompiled headers to speed up the build process OFF
158+
BUILD_SHARED_LIBS Whether or not to build shared libraries or static (not compatible with NT_ENABLE_PYTHON which requires static libraries. If both are specified BUILD SHARED_LIBS will be set to OFF) ON
159+
====================== ===================================================================================================================================================================================== =======
160+
161+
Building Against nuTens
162+
-----------------------

‎doc/source/intro.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
11

22
============
3-
Installation
3+
Introduction
44
============

‎doc/source/quick-start-guide/matter-solvers.rst‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
2+
==============
3+
Matter Solvers
4+
==============

0 commit comments

Comments
 (0)