xcoll 0.5.11__py3-none-any.whl → 0.6.0__py3-none-any.whl

xcoll/scattering_routines/geant4/collimasim/lib/pybind11/docs/basics.rst

@@ -1,308 +0,0 @@
-.. _basics:
-
-First steps
-###########
-
-This sections demonstrates the basic features of pybind11. Before getting
-started, make sure that development environment is set up to compile the
-included set of test cases.
-
-
-Compiling the test cases
-========================
-
-Linux/macOS
------------
-
-On Linux  you'll need to install the **python-dev** or **python3-dev** packages as
-well as **cmake**. On macOS, the included python version works out of the box,
-but **cmake** must still be installed.
-
-After installing the prerequisites, run
-
-.. code-block:: bash
-
-   mkdir build
-   cd build
-   cmake ..
-   make check -j 4
-
-The last line will both compile and run the tests.
-
-Windows
--------
-
-On Windows, only **Visual Studio 2015** and newer are supported since pybind11 relies
-on various C++11 language features that break older versions of Visual Studio.
-
-.. Note::
-
-    To use the C++17 in Visual Studio 2017 (MSVC 14.1), pybind11 requires the flag
-    ``/permissive-`` to be passed to the compiler `to enforce standard conformance`_. When
-    building with Visual Studio 2019, this is not strictly necessary, but still advised.
-
-..  _`to enforce standard conformance`: https://docs.microsoft.com/en-us/cpp/build/reference/permissive-standards-conformance?view=vs-2017
-
-To compile and run the tests:
-
-.. code-block:: batch
-
-   mkdir build
-   cd build
-   cmake ..
-   cmake --build . --config Release --target check
-
-This will create a Visual Studio project, compile and run the target, all from the
-command line.
-
-.. Note::
-
-    If all tests fail, make sure that the Python binary and the testcases are compiled
-    for the same processor type and bitness (i.e. either **i386** or **x86_64**). You
-    can specify **x86_64** as the target architecture for the generated Visual Studio
-    project using ``cmake -A x64 ..``.
-
-.. seealso::
-
-    Advanced users who are already familiar with Boost.Python may want to skip
-    the tutorial and look at the test cases in the :file:`tests` directory,
-    which exercise all features of pybind11.
-
-Header and namespace conventions
-================================
-
-For brevity, all code examples assume that the following two lines are present:
-
-.. code-block:: cpp
-
-    #include <pybind11/pybind11.h>
-
-    namespace py = pybind11;
-
-Some features may require additional headers, but those will be specified as needed.
-
-.. _simple_example:
-
-Creating bindings for a simple function
-=======================================
-
-Let's start by creating Python bindings for an extremely simple function, which
-adds two numbers and returns their result:
-
-.. code-block:: cpp
-
-    int add(int i, int j) {
-        return i + j;
-    }
-
-For simplicity [#f1]_, we'll put both this function and the binding code into
-a file named :file:`example.cpp` with the following contents:
-
-.. code-block:: cpp
-
-    #include <pybind11/pybind11.h>
-
-    int add(int i, int j) {
-        return i + j;
-    }
-
-    PYBIND11_MODULE(example, m) {
-        m.doc() = "pybind11 example plugin"; // optional module docstring
-
-        m.def("add", &add, "A function which adds two numbers");
-    }
-
-.. [#f1] In practice, implementation and binding code will generally be located
-         in separate files.
-
-The :func:`PYBIND11_MODULE` macro creates a function that will be called when an
-``import`` statement is issued from within Python. The module name (``example``)
-is given as the first macro argument (it should not be in quotes). The second
-argument (``m``) defines a variable of type :class:`py::module_ <module>` which
-is the main interface for creating bindings. The method :func:`module_::def`
-generates binding code that exposes the ``add()`` function to Python.
-
-.. note::
-
-    Notice how little code was needed to expose our function to Python: all
-    details regarding the function's parameters and return value were
-    automatically inferred using template metaprogramming. This overall
-    approach and the used syntax are borrowed from Boost.Python, though the
-    underlying implementation is very different.
-
-pybind11 is a header-only library, hence it is not necessary to link against
-any special libraries and there are no intermediate (magic) translation steps.
-On Linux, the above example can be compiled using the following command:
-
-.. code-block:: bash
-
-    $ c++ -O3 -Wall -shared -std=c++11 -fPIC $(python3 -m pybind11 --includes) example.cpp -o example$(python3-config --extension-suffix)
-
-.. note::
-
-    If you used :ref:`include_as_a_submodule` to get the pybind11 source, then
-    use ``$(python3-config --includes) -Iextern/pybind11/include`` instead of
-    ``$(python3 -m pybind11 --includes)`` in the above compilation, as
-    explained in :ref:`building_manually`.
-
-For more details on the required compiler flags on Linux and macOS, see
-:ref:`building_manually`. For complete cross-platform compilation instructions,
-refer to the :ref:`compiling` page.
-
-The `python_example`_ and `cmake_example`_ repositories are also a good place
-to start. They are both complete project examples with cross-platform build
-systems. The only difference between the two is that `python_example`_ uses
-Python's ``setuptools`` to build the module, while `cmake_example`_ uses CMake
-(which may be preferable for existing C++ projects).
-
-.. _python_example: https://github.com/pybind/python_example
-.. _cmake_example: https://github.com/pybind/cmake_example
-
-Building the above C++ code will produce a binary module file that can be
-imported to Python. Assuming that the compiled module is located in the
-current directory, the following interactive Python session shows how to
-load and execute the example:
-
-.. code-block:: pycon
-
-    $ python
-    Python 2.7.10 (default, Aug 22 2015, 20:33:39)
-    [GCC 4.2.1 Compatible Apple LLVM 7.0.0 (clang-700.0.59.1)] on darwin
-    Type "help", "copyright", "credits" or "license" for more information.
-    >>> import example
-    >>> example.add(1, 2)
-    3L
-    >>>
-
-.. _keyword_args:
-
-Keyword arguments
-=================
-
-With a simple code modification, it is possible to inform Python about the
-names of the arguments ("i" and "j" in this case).
-
-.. code-block:: cpp
-
-    m.def("add", &add, "A function which adds two numbers",
-          py::arg("i"), py::arg("j"));
-
-:class:`arg` is one of several special tag classes which can be used to pass
-metadata into :func:`module_::def`. With this modified binding code, we can now
-call the function using keyword arguments, which is a more readable alternative
-particularly for functions taking many parameters:
-
-.. code-block:: pycon
-
-    >>> import example
-    >>> example.add(i=1, j=2)
-    3L
-
-The keyword names also appear in the function signatures within the documentation.
-
-.. code-block:: pycon
-
-    >>> help(example)
-
-    ....
-
-    FUNCTIONS
-        add(...)
-            Signature : (i: int, j: int) -> int
-
-            A function which adds two numbers
-
-A shorter notation for named arguments is also available:
-
-.. code-block:: cpp
-
-    // regular notation
-    m.def("add1", &add, py::arg("i"), py::arg("j"));
-    // shorthand
-    using namespace pybind11::literals;
-    m.def("add2", &add, "i"_a, "j"_a);
-
-The :var:`_a` suffix forms a C++11 literal which is equivalent to :class:`arg`.
-Note that the literal operator must first be made visible with the directive
-``using namespace pybind11::literals``. This does not bring in anything else
-from the ``pybind11`` namespace except for literals.
-
-.. _default_args:
-
-Default arguments
-=================
-
-Suppose now that the function to be bound has default arguments, e.g.:
-
-.. code-block:: cpp
-
-    int add(int i = 1, int j = 2) {
-        return i + j;
-    }
-
-Unfortunately, pybind11 cannot automatically extract these parameters, since they
-are not part of the function's type information. However, they are simple to specify
-using an extension of :class:`arg`:
-
-.. code-block:: cpp
-
-    m.def("add", &add, "A function which adds two numbers",
-          py::arg("i") = 1, py::arg("j") = 2);
-
-The default values also appear within the documentation.
-
-.. code-block:: pycon
-
-    >>> help(example)
-
-    ....
-
-    FUNCTIONS
-        add(...)
-            Signature : (i: int = 1, j: int = 2) -> int
-
-            A function which adds two numbers
-
-The shorthand notation is also available for default arguments:
-
-.. code-block:: cpp
-
-    // regular notation
-    m.def("add1", &add, py::arg("i") = 1, py::arg("j") = 2);
-    // shorthand
-    m.def("add2", &add, "i"_a=1, "j"_a=2);
-
-Exporting variables
-===================
-
-To expose a value from C++, use the ``attr`` function to register it in a
-module as shown below. Built-in types and general objects (more on that later)
-are automatically converted when assigned as attributes, and can be explicitly
-converted using the function ``py::cast``.
-
-.. code-block:: cpp
-
-    PYBIND11_MODULE(example, m) {
-        m.attr("the_answer") = 42;
-        py::object world = py::cast("World");
-        m.attr("what") = world;
-    }
-
-These are then accessible from Python:
-
-.. code-block:: pycon
-
-    >>> import example
-    >>> example.the_answer
-    42
-    >>> example.what
-    'World'
-
-.. _supported_types:
-
-Supported data types
-====================
-
-A large number of data types are supported out of the box and can be used
-seamlessly as functions arguments, return values or with ``py::cast`` in general.
-For a full overview, see the :doc:`advanced/cast/index` section.

xcoll/scattering_routines/geant4/collimasim/lib/pybind11/docs/benchmark.py

@@ -1,91 +0,0 @@
-# -*- coding: utf-8 -*-
-import datetime as dt
-import os
-import random
-
-nfns = 4  # Functions per class
-nargs = 4  # Arguments per function
-
-
-def generate_dummy_code_pybind11(nclasses=10):
-    decl = ""
-    bindings = ""
-
-    for cl in range(nclasses):
-        decl += "class cl%03i;\n" % cl
-    decl += "\n"
-
-    for cl in range(nclasses):
-        decl += "class cl%03i {\n" % cl
-        decl += "public:\n"
-        bindings += '    py::class_<cl%03i>(m, "cl%03i")\n' % (cl, cl)
-        for fn in range(nfns):
-            ret = random.randint(0, nclasses - 1)
-            params = [random.randint(0, nclasses - 1) for i in range(nargs)]
-            decl += "    cl%03i *fn_%03i(" % (ret, fn)
-            decl += ", ".join("cl%03i *" % p for p in params)
-            decl += ");\n"
-            bindings += '        .def("fn_%03i", &cl%03i::fn_%03i)\n' % (fn, cl, fn)
-        decl += "};\n\n"
-        bindings += "        ;\n"
-
-    result = "#include <pybind11/pybind11.h>\n\n"
-    result += "namespace py = pybind11;\n\n"
-    result += decl + "\n"
-    result += "PYBIND11_MODULE(example, m) {\n"
-    result += bindings
-    result += "}"
-    return result
-
-
-def generate_dummy_code_boost(nclasses=10):
-    decl = ""
-    bindings = ""
-
-    for cl in range(nclasses):
-        decl += "class cl%03i;\n" % cl
-    decl += "\n"
-
-    for cl in range(nclasses):
-        decl += "class cl%03i {\n" % cl
-        decl += "public:\n"
-        bindings += '    py::class_<cl%03i>("cl%03i")\n' % (cl, cl)
-        for fn in range(nfns):
-            ret = random.randint(0, nclasses - 1)
-            params = [random.randint(0, nclasses - 1) for i in range(nargs)]
-            decl += "    cl%03i *fn_%03i(" % (ret, fn)
-            decl += ", ".join("cl%03i *" % p for p in params)
-            decl += ");\n"
-            bindings += (
-                '        .def("fn_%03i", &cl%03i::fn_%03i, py::return_value_policy<py::manage_new_object>())\n'
-                % (fn, cl, fn)
-            )
-        decl += "};\n\n"
-        bindings += "        ;\n"
-
-    result = "#include <boost/python.hpp>\n\n"
-    result += "namespace py = boost::python;\n\n"
-    result += decl + "\n"
-    result += "BOOST_PYTHON_MODULE(example) {\n"
-    result += bindings
-    result += "}"
-    return result
-
-
-for codegen in [generate_dummy_code_pybind11, generate_dummy_code_boost]:
-    print("{")
-    for i in range(0, 10):
-        nclasses = 2 ** i
-        with open("test.cpp", "w") as f:
-            f.write(codegen(nclasses))
-        n1 = dt.datetime.now()
-        os.system(
-            "g++ -Os -shared -rdynamic -undefined dynamic_lookup "
-            "-fvisibility=hidden -std=c++14 test.cpp -I include "
-            "-I /System/Library/Frameworks/Python.framework/Headers -o test.so"
-        )
-        n2 = dt.datetime.now()
-        elapsed = (n2 - n1).total_seconds()
-        size = os.stat("test.so").st_size
-        print("   {%i, %f, %i}," % (nclasses * nfns, elapsed, size))
-    print("}")

xcoll/scattering_routines/geant4/collimasim/lib/pybind11/docs/benchmark.rst

@@ -1,95 +0,0 @@
-Benchmark
-=========
-
-The following is the result of a synthetic benchmark comparing both compilation
-time and module size of pybind11 against Boost.Python. A detailed report about a
-Boost.Python to pybind11 conversion of a real project is available here: [#f1]_.
-
-.. [#f1] http://graylab.jhu.edu/RosettaCon2016/PyRosetta-4.pdf
-
-Setup
------
-
-A python script (see the ``docs/benchmark.py`` file) was used to generate a set
-of files with dummy classes whose count increases for each successive benchmark
-(between 1 and 2048 classes in powers of two). Each class has four methods with
-a randomly generated signature with a return value and four arguments. (There
-was no particular reason for this setup other than the desire to generate many
-unique function signatures whose count could be controlled in a simple way.)
-
-Here is an example of the binding code for one class:
-
-.. code-block:: cpp
-
-    ...
-    class cl034 {
-    public:
-        cl279 *fn_000(cl084 *, cl057 *, cl065 *, cl042 *);
-        cl025 *fn_001(cl098 *, cl262 *, cl414 *, cl121 *);
-        cl085 *fn_002(cl445 *, cl297 *, cl145 *, cl421 *);
-        cl470 *fn_003(cl200 *, cl323 *, cl332 *, cl492 *);
-    };
-    ...
-
-    PYBIND11_MODULE(example, m) {
-        ...
-        py::class_<cl034>(m, "cl034")
-            .def("fn_000", &cl034::fn_000)
-            .def("fn_001", &cl034::fn_001)
-            .def("fn_002", &cl034::fn_002)
-            .def("fn_003", &cl034::fn_003)
-        ...
-    }
-
-The Boost.Python version looks almost identical except that a return value
-policy had to be specified as an argument to ``def()``. For both libraries,
-compilation was done with
-
-.. code-block:: bash
-
-    Apple LLVM version 7.0.2 (clang-700.1.81)
-
-and the following compilation flags
-
-.. code-block:: bash
-
-    g++ -Os -shared -rdynamic -undefined dynamic_lookup -fvisibility=hidden -std=c++14
-
-Compilation time
-----------------
-
-The following log-log plot shows how the compilation time grows for an
-increasing number of class and function declarations. pybind11 includes many
-fewer headers, which initially leads to shorter compilation times, but the
-performance is ultimately fairly similar (pybind11 is 19.8 seconds faster for
-the largest largest file with 2048 classes and a total of 8192 methods -- a
-modest **1.2x** speedup relative to Boost.Python, which required 116.35
-seconds).
-
-.. only:: not latex
-
-    .. image:: pybind11_vs_boost_python1.svg
-
-.. only:: latex
-
-    .. image:: pybind11_vs_boost_python1.png
-
-Module size
------------
-
-Differences between the two libraries become much more pronounced when
-considering the file size of the generated Python plugin: for the largest file,
-the binary generated by Boost.Python required 16.8 MiB, which was **2.17
-times** / **9.1 megabytes** larger than the output generated by pybind11. For
-very small inputs, Boost.Python has an edge in the plot below -- however, note
-that it stores many definitions in an external library, whose size was not
-included here, hence the comparison is slightly shifted in Boost.Python's
-favor.
-
-.. only:: not latex
-
-    .. image:: pybind11_vs_boost_python2.svg
-
-.. only:: latex
-
-    .. image:: pybind11_vs_boost_python2.png