Skip to content

Commit 7977843

Browse files
theoheimeltheoheimel
committed
update documentation
1 parent 4c2d0d9 commit 7977843

10 files changed

Lines changed: 415 additions & 157 deletions

File tree

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,6 @@
22

33
This is the repository for the next major MadGraph release. It is still under active
44
development. If you are looking for a stable release of MadGraph, please go the
5-
[MadGraph5_aMC@NLO repository](http://launchpad.net/madgraph5) or the
5+
[MadGraph5_aMC@NLO repository](https://github.com/mg5amcnlo/mg5amcnlo) or the
66
[Launchpad](http://launchpad.net/madgraph5).
77

‎docs/source/index.rst‎

Lines changed: 10 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,10 @@
1-
MadSpace documentation
1+
MadGraph7 documentation
22
=======================
33

4-
MadSpace is a modular and GPU-ready phase-space sampling and event generation library.
5-
6-
You can find instructions on how to install and use MadSpace on the following pages:
7-
8-
* :doc:`installation`
9-
10-
The following pages contain a detailed reference of all the classes and methods in
11-
MadSpace:
12-
13-
* :doc:`python-api`
14-
* :doc:`cpp-api`
4+
This is the documentation for the next major MadGraph release. It is still under active
5+
development. If you are looking for a stable release of MadGraph, please go the
6+
`MadGraph5_aMC@NLO repository <https://github.com/mg5amcnlo/mg5amcnlo>`_ or the
7+
`Launchpad <http://launchpad.net/madgraph5>`_.
158

169
.. toctree::
1710
:maxdepth: 1
@@ -22,8 +15,10 @@ MadSpace:
2215

2316
.. toctree::
2417
:maxdepth: 1
25-
:caption: Reference
18+
:caption: MadSpace
2619
:hidden:
2720

28-
python-api
29-
cpp-api
21+
madspace/installation
22+
madspace/umami-api
23+
madspace/python-api
24+
madspace/cpp-api

‎docs/source/installation.rst‎

Lines changed: 1 addition & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -1,38 +1,4 @@
11
Installation
22
============
33

4-
Package
5-
-------
6-
7-
Packages on PyPI are available for Linux and MacOS X (with Apple silicon),
8-
for Python 3.11 to 3.14.::
9-
10-
pip install madspace
11-
12-
Build
13-
-----
14-
15-
First install `scikit_build_core` with::
16-
17-
pip install scikit_build_core
18-
19-
The pre-installed version of `cmake` under MacOS is outdated, so you might need to install a
20-
newer version, for example with::
21-
22-
brew install cmake
23-
24-
Then check out the `madspace` repository and build and install it with::
25-
26-
git clone git@github.com:madgraph-ml/madspace.git
27-
cd madspace
28-
pip install .
29-
30-
For a development version allowing for incremental build, use the following command instead::
31-
32-
pip install --no-build-isolation -Cbuild-dir=build -Ccmake.build-type=RelWithDebInfo .
33-
34-
This will create a directory `build` where you can run make directly to make development
35-
easier. To update the python module itself, make sure to also run the `pip install` command
36-
above again. This will not happen automatically, even if you make the installation editable!
37-
Build type `RelWithDebInfo` generates optimized code but includes debug symbols, so you
38-
can use `lldb` or `gdb` to debug the code.
4+
TBA

docs/source/cpp-api.rst renamed to docs/source/madspace/cpp-api.rst

File renamed without changes.

‎docs/source/madspace/installation.rst‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
Installation
2+
============
3+
4+
Package
5+
-------
6+
7+
Packages on PyPI are available for Linux and MacOS X (with Apple silicon),
8+
for Python 3.11 to 3.14.::
9+
10+
pip install madspace
11+
12+
Build
13+
-----
14+
15+
First install `scikit_build_core` with::
16+
17+
pip install scikit_build_core
18+
19+
The pre-installed version of `cmake` under MacOS is outdated, so you might need to install a
20+
newer version, for example with::
21+
22+
brew install cmake
23+
24+
Then check out the `madspace` repository and build and install it with::
25+
26+
git clone git@github.com:madgraph-ml/madspace.git
27+
cd madspace
28+
pip install .
29+
30+
For a development version allowing for incremental build, use the following command instead::
31+
32+
pip install --no-build-isolation -Cbuild-dir=build -Ccmake.build-type=RelWithDebInfo .
33+
34+
This will create a directory `build` where you can run make directly to make development
35+
easier. To update the python module itself, make sure to also run the `pip install` command
36+
above again. This will not happen automatically, even if you make the installation editable!
37+
Build type `RelWithDebInfo` generates optimized code but includes debug symbols, so you
38+
can use `lldb` or `gdb` to debug the code.

docs/source/python-api.rst renamed to docs/source/madspace/python-api.rst

File renamed without changes.

‎docs/source/madspace/umami-api.rst‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
UMAMI API
2+
=========
3+
4+
.. doxygenfile:: umami.h

‎madspace/generate_pyi.sh‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
pybind11-stubgen madspace._madspace_py \
22
-o . \
33
--enum-class-locations=TChannelMode:PhaseSpaceMapping.TChannelMode \
4-
--enum-class-locations=Activation:MLP.Activation
4+
--enum-class-locations=Activation:MLP.Activation \
5+
--enum-class-locations=CutMode:Cuts.CutMode

‎madspace/include/madspace/umami.h‎

Lines changed: 41 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -32,12 +32,21 @@ const inline int UMAMI_MAJOR_VERSION = 1;
3232
const inline int UMAMI_MINOR_VERSION = 0;
3333

3434
typedef enum {
35+
/** operation was executed successfully */
3536
UMAMI_SUCCESS,
37+
/** an unspecified error */
3638
UMAMI_ERROR,
39+
/** operation not implemented */
3740
UMAMI_ERROR_NOT_IMPLEMENTED,
41+
/** the provided input key is not supported by this matrix element implementation */
3842
UMAMI_ERROR_UNSUPPORTED_INPUT,
43+
/** the provided output key is not supported by this matrix element implementation
44+
*/
3945
UMAMI_ERROR_UNSUPPORTED_OUTPUT,
46+
/** the provided metadata key is not supported by this matrix element implementation
47+
*/
4048
UMAMI_ERROR_UNSUPPORTED_META,
49+
/** a mandatory matrix element input was not provided */
4150
UMAMI_ERROR_MISSING_INPUT,
4251
} UmamiStatus;
4352

@@ -48,46 +57,63 @@ typedef enum {
4857
} UmamiDevice;
4958

5059
typedef enum {
60+
/** `UmamiDevice` specifying the type of device */
5161
UMAMI_META_DEVICE,
62+
/** `int` specifying the number of external particles */
5263
UMAMI_META_PARTICLE_COUNT,
64+
/** `int` specifying the number of Feynman diagrams */
5365
UMAMI_META_DIAGRAM_COUNT,
66+
/** `int` specifying the number of helicities */
5467
UMAMI_META_HELICITY_COUNT,
68+
/** `int` specifying the number of colors */
5569
UMAMI_META_COLOR_COUNT,
5670
} UmamiMetaKey;
5771

5872
typedef enum {
73+
/** momenta of the external legs, type: `double`, shape: `(particle count, 4)` */
5974
UMAMI_IN_MOMENTA,
75+
/** value for the strong coupling, type: `double`, shape: `()` */
6076
UMAMI_IN_ALPHA_S,
77+
/** flavor index, type: `int`, shape: `()` */
6178
UMAMI_IN_FLAVOR_INDEX,
79+
/** random number for color selection, type: `double`, shape: `()` */
6280
UMAMI_IN_RANDOM_COLOR,
81+
/** random number for helicity selection, type: `double`, shape: `()` */
6382
UMAMI_IN_RANDOM_HELICITY,
83+
/** random number for diagram selection, type: `double`, shape: `()` */
6484
UMAMI_IN_RANDOM_DIAGRAM,
85+
/** externally selected helicity index, type: `int`, shape: `()` */
6586
UMAMI_IN_HELICITY_INDEX,
87+
/** externally selected diagram index, type: `int`, shape: `()` */
6688
UMAMI_IN_DIAGRAM_INDEX,
67-
UMAMI_IN_GPU_STREAM,
6889
} UmamiInputKey;
6990

7091
typedef enum {
92+
/** value of the matrix element, type: `double`, shape: `()` */
7193
UMAMI_OUT_MATRIX_ELEMENT,
94+
/** selected color index, type: `double`, shape: `(diagram count)` */
7295
UMAMI_OUT_DIAGRAM_AMP2,
96+
/** selected color index, type: `int`, shape: `()` */
7397
UMAMI_OUT_COLOR_INDEX,
98+
/** selected helicity index, type: `int`, shape: `()` */
7499
UMAMI_OUT_HELICITY_INDEX,
100+
/** selected diagram index, type: `int`, shape: `()` */
75101
UMAMI_OUT_DIAGRAM_INDEX,
76-
// NLO: born, virtual, poles, counterterms
77-
// color: LC-ME, FC-ME
102+
/** CUDA or HIP stream for asynchronous execution. Listed as an output as it is a
103+
* mutable pointer */
104+
UMAMI_OUT_GPU_STREAM,
78105
} UmamiOutputKey;
79106

107+
/** Implementation-defined pointer to a matrix element instance */
80108
typedef void* UmamiHandle;
81109

82110
/**
83-
* Creates an instance of the matrix element. Each instance is independent, so thread
84-
* safety can be achieved by creating a separate one for every thread.
111+
* Retrieve metadata about the implemented matrix element
85112
*
86113
* @param meta_key
87-
* path to the parameter file
88-
* @param handle
89-
* pointer to an instance of the subprocess. Has to be cleaned up by
90-
* the caller with `free_subprocess`.
114+
* key specifying the type of metadata to be retrieved
115+
* @param result
116+
* pointer to store the result. It's type depends on the metadata key
91117
* @return
92118
* UMAMI_SUCCESS on success, error code otherwise
93119
*/
@@ -97,11 +123,11 @@ UmamiStatus umami_get_meta(UmamiMetaKey meta_key, void* result);
97123
* Creates an instance of the matrix element. Each instance is independent, so thread
98124
* safety can be achieved by creating a separate one for every thread.
99125
*
100-
* @param param_card_path
101-
* path to the parameter file
102126
* @param handle
103127
* pointer to an instance of the subprocess. Has to be cleaned up by
104128
* the caller with `free_subprocess`.
129+
* @param param_card_path
130+
* path to the parameter file
105131
* @return
106132
* UMAMI_SUCCESS on success, error code otherwise
107133
*/
@@ -146,14 +172,16 @@ UmamiStatus umami_get_parameter(
146172

147173
/**
148174
* Evaluates the matrix element as a function of the given inputs, filling the
149-
* requested outputs.
175+
* requested outputs. Unless otherwise specified, all inputs and outputs have a
176+
* column-major memory layout and have a batch dimension that is contiguous in memory.
150177
*
151178
* @param handle
152179
* handle of a matrix element instance
153180
* @param count
154181
* number of events to evaluate the matrix element for
155182
* @param stride
156-
* stride of the batch dimension of the input and output arrays, see memory layout
183+
* stride of the batch dimension of the input and output arrays to simplify
184+
* parallel execution on CPUs, see memory layout
157185
* @param offset
158186
* offset of the event index
159187
* @param input_count

0 commit comments

Comments
 (0)