xcoll 0.3.6__py3-none-any.whl → 0.5.0__py3-none-any.whl

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

@@ -0,0 +1,343 @@
+Frequently asked questions
+##########################
+
+"ImportError: dynamic module does not define init function"
+===========================================================
+
+1. Make sure that the name specified in PYBIND11_MODULE is identical to the
+filename of the extension library (without suffixes such as ``.so``).
+
+2. If the above did not fix the issue, you are likely using an incompatible
+version of Python (for instance, the extension library was compiled against
+Python 2, while the interpreter is running on top of some version of Python
+3, or vice versa).
+
+"Symbol not found: ``__Py_ZeroStruct`` / ``_PyInstanceMethod_Type``"
+========================================================================
+
+See the first answer.
+
+"SystemError: dynamic module not initialized properly"
+======================================================
+
+See the first answer.
+
+The Python interpreter immediately crashes when importing my module
+===================================================================
+
+See the first answer.
+
+.. _faq_reference_arguments:
+
+Limitations involving reference arguments
+=========================================
+
+In C++, it's fairly common to pass arguments using mutable references or
+mutable pointers, which allows both read and write access to the value
+supplied by the caller. This is sometimes done for efficiency reasons, or to
+realize functions that have multiple return values. Here are two very basic
+examples:
+
+.. code-block:: cpp
+
+    void increment(int &i) { i++; }
+    void increment_ptr(int *i) { (*i)++; }
+
+In Python, all arguments are passed by reference, so there is no general
+issue in binding such code from Python.
+
+However, certain basic Python types (like ``str``, ``int``, ``bool``,
+``float``, etc.) are **immutable**. This means that the following attempt
+to port the function to Python doesn't have the same effect on the value
+provided by the caller -- in fact, it does nothing at all.
+
+.. code-block:: python
+
+    def increment(i):
+        i += 1  # nope..
+
+pybind11 is also affected by such language-level conventions, which means that
+binding ``increment`` or ``increment_ptr`` will also create Python functions
+that don't modify their arguments.
+
+Although inconvenient, one workaround is to encapsulate the immutable types in
+a custom type that does allow modifications.
+
+An other alternative involves binding a small wrapper lambda function that
+returns a tuple with all output arguments (see the remainder of the
+documentation for examples on binding lambda functions). An example:
+
+.. code-block:: cpp
+
+    int foo(int &i) { i++; return 123; }
+
+and the binding code
+
+.. code-block:: cpp
+
+   m.def("foo", [](int i) { int rv = foo(i); return std::make_tuple(rv, i); });
+
+
+How can I reduce the build time?
+================================
+
+It's good practice to split binding code over multiple files, as in the
+following example:
+
+:file:`example.cpp`:
+
+.. code-block:: cpp
+
+    void init_ex1(py::module_ &);
+    void init_ex2(py::module_ &);
+    /* ... */
+
+    PYBIND11_MODULE(example, m) {
+        init_ex1(m);
+        init_ex2(m);
+        /* ... */
+    }
+
+:file:`ex1.cpp`:
+
+.. code-block:: cpp
+
+    void init_ex1(py::module_ &m) {
+        m.def("add", [](int a, int b) { return a + b; });
+    }
+
+:file:`ex2.cpp`:
+
+.. code-block:: cpp
+
+    void init_ex2(py::module_ &m) {
+        m.def("sub", [](int a, int b) { return a - b; });
+    }
+
+:command:`python`:
+
+.. code-block:: pycon
+
+    >>> import example
+    >>> example.add(1, 2)
+    3
+    >>> example.sub(1, 1)
+    0
+
+As shown above, the various ``init_ex`` functions should be contained in
+separate files that can be compiled independently from one another, and then
+linked together into the same final shared object.  Following this approach
+will:
+
+1. reduce memory requirements per compilation unit.
+
+2. enable parallel builds (if desired).
+
+3. allow for faster incremental builds. For instance, when a single class
+   definition is changed, only a subset of the binding code will generally need
+   to be recompiled.
+
+"recursive template instantiation exceeded maximum depth of 256"
+================================================================
+
+If you receive an error about excessive recursive template evaluation, try
+specifying a larger value, e.g. ``-ftemplate-depth=1024`` on GCC/Clang. The
+culprit is generally the generation of function signatures at compile time
+using C++14 template metaprogramming.
+
+.. _`faq:hidden_visibility`:
+
+"‘SomeClass’ declared with greater visibility than the type of its field ‘SomeClass::member’ [-Wattributes]"
+============================================================================================================
+
+This error typically indicates that you are compiling without the required
+``-fvisibility`` flag.  pybind11 code internally forces hidden visibility on
+all internal code, but if non-hidden (and thus *exported*) code attempts to
+include a pybind type (for example, ``py::object`` or ``py::list``) you can run
+into this warning.
+
+To avoid it, make sure you are specifying ``-fvisibility=hidden`` when
+compiling pybind code.
+
+As to why ``-fvisibility=hidden`` is necessary, because pybind modules could
+have been compiled under different versions of pybind itself, it is also
+important that the symbols defined in one module do not clash with the
+potentially-incompatible symbols defined in another.  While Python extension
+modules are usually loaded with localized symbols (under POSIX systems
+typically using ``dlopen`` with the ``RTLD_LOCAL`` flag), this Python default
+can be changed, but even if it isn't it is not always enough to guarantee
+complete independence of the symbols involved when not using
+``-fvisibility=hidden``.
+
+Additionally, ``-fvisibility=hidden`` can deliver considerably binary size
+savings. (See the following section for more details.)
+
+
+.. _`faq:symhidden`:
+
+How can I create smaller binaries?
+==================================
+
+To do its job, pybind11 extensively relies on a programming technique known as
+*template metaprogramming*, which is a way of performing computation at compile
+time using type information. Template metaprogramming usually instantiates code
+involving significant numbers of deeply nested types that are either completely
+removed or reduced to just a few instructions during the compiler's optimization
+phase. However, due to the nested nature of these types, the resulting symbol
+names in the compiled extension library can be extremely long. For instance,
+the included test suite contains the following symbol:
+
+.. only:: html
+
+    .. code-block:: none
+
+        _​_​Z​N​8​p​y​b​i​n​d​1​1​1​2​c​p​p​_​f​u​n​c​t​i​o​n​C​1​I​v​8​E​x​a​m​p​l​e​2​J​R​N​S​t​3​_​_​1​6​v​e​c​t​o​r​I​N​S​3​_​1​2​b​a​s​i​c​_​s​t​r​i​n​g​I​w​N​S​3​_​1​1​c​h​a​r​_​t​r​a​i​t​s​I​w​E​E​N​S​3​_​9​a​l​l​o​c​a​t​o​r​I​w​E​E​E​E​N​S​8​_​I​S​A​_​E​E​E​E​E​J​N​S​_​4​n​a​m​e​E​N​S​_​7​s​i​b​l​i​n​g​E​N​S​_​9​i​s​_​m​e​t​h​o​d​E​A​2​8​_​c​E​E​E​M​T​0​_​F​T​_​D​p​T​1​_​E​D​p​R​K​T​2​_
+
+.. only:: not html
+
+    .. code-block:: cpp
+
+        __ZN8pybind1112cpp_functionC1Iv8Example2JRNSt3__16vectorINS3_12basic_stringIwNS3_11char_traitsIwEENS3_9allocatorIwEEEENS8_ISA_EEEEEJNS_4nameENS_7siblingENS_9is_methodEA28_cEEEMT0_FT_DpT1_EDpRKT2_
+
+which is the mangled form of the following function type:
+
+.. code-block:: cpp
+
+    pybind11::cpp_function::cpp_function<void, Example2, std::__1::vector<std::__1::basic_string<wchar_t, std::__1::char_traits<wchar_t>, std::__1::allocator<wchar_t> >, std::__1::allocator<std::__1::basic_string<wchar_t, std::__1::char_traits<wchar_t>, std::__1::allocator<wchar_t> > > >&, pybind11::name, pybind11::sibling, pybind11::is_method, char [28]>(void (Example2::*)(std::__1::vector<std::__1::basic_string<wchar_t, std::__1::char_traits<wchar_t>, std::__1::allocator<wchar_t> >, std::__1::allocator<std::__1::basic_string<wchar_t, std::__1::char_traits<wchar_t>, std::__1::allocator<wchar_t> > > >&), pybind11::name const&, pybind11::sibling const&, pybind11::is_method const&, char const (&) [28])
+
+The memory needed to store just the mangled name of this function (196 bytes)
+is larger than the actual piece of code (111 bytes) it represents! On the other
+hand, it's silly to even give this function a name -- after all, it's just a
+tiny cog in a bigger piece of machinery that is not exposed to the outside
+world. So we'll generally only want to export symbols for those functions which
+are actually called from the outside.
+
+This can be achieved by specifying the parameter ``-fvisibility=hidden`` to GCC
+and Clang, which sets the default symbol visibility to *hidden*, which has a
+tremendous impact on the final binary size of the resulting extension library.
+(On Visual Studio, symbols are already hidden by default, so nothing needs to
+be done there.)
+
+In addition to decreasing binary size, ``-fvisibility=hidden`` also avoids
+potential serious issues when loading multiple modules and is required for
+proper pybind operation.  See the previous FAQ entry for more details.
+
+Working with ancient Visual Studio 2008 builds on Windows
+=========================================================
+
+The official Windows distributions of Python are compiled using truly
+ancient versions of Visual Studio that lack good C++11 support. Some users
+implicitly assume that it would be impossible to load a plugin built with
+Visual Studio 2015 into a Python distribution that was compiled using Visual
+Studio 2008. However, no such issue exists: it's perfectly legitimate to
+interface DLLs that are built with different compilers and/or C libraries.
+Common gotchas to watch out for involve not ``free()``-ing memory region
+that that were ``malloc()``-ed in another shared library, using data
+structures with incompatible ABIs, and so on. pybind11 is very careful not
+to make these types of mistakes.
+
+How can I properly handle Ctrl-C in long-running functions?
+===========================================================
+
+Ctrl-C is received by the Python interpreter, and holds it until the GIL
+is released, so a long-running function won't be interrupted.
+
+To interrupt from inside your function, you can use the ``PyErr_CheckSignals()``
+function, that will tell if a signal has been raised on the Python side.  This
+function merely checks a flag, so its impact is negligible. When a signal has
+been received, you must either explicitly interrupt execution by throwing
+``py::error_already_set`` (which will propagate the existing
+``KeyboardInterrupt``), or clear the error (which you usually will not want):
+
+.. code-block:: cpp
+
+    PYBIND11_MODULE(example, m)
+    {
+        m.def("long running_func", []()
+        {
+            for (;;) {
+                if (PyErr_CheckSignals() != 0)
+                    throw py::error_already_set();
+                // Long running iteration
+            }
+        });
+    }
+
+CMake doesn't detect the right Python version
+=============================================
+
+The CMake-based build system will try to automatically detect the installed
+version of Python and link against that. When this fails, or when there are
+multiple versions of Python and it finds the wrong one, delete
+``CMakeCache.txt`` and then add ``-DPYTHON_EXECUTABLE=$(which python)`` to your
+CMake configure line. (Replace ``$(which python)`` with a path to python if
+your prefer.)
+
+You can alternatively try ``-DPYBIND11_FINDPYTHON=ON``, which will activate the
+new CMake FindPython support instead of pybind11's custom search. Requires
+CMake 3.12+, and 3.15+ or 3.18.2+ are even better. You can set this in your
+``CMakeLists.txt`` before adding or finding pybind11, as well.
+
+Inconsistent detection of Python version in CMake and pybind11
+==============================================================
+
+The functions ``find_package(PythonInterp)`` and ``find_package(PythonLibs)``
+provided by CMake for Python version detection are modified by pybind11 due to
+unreliability and limitations that make them unsuitable for pybind11's needs.
+Instead pybind11 provides its own, more reliable Python detection CMake code.
+Conflicts can arise, however, when using pybind11 in a project that *also* uses
+the CMake Python detection in a system with several Python versions installed.
+
+This difference may cause inconsistencies and errors if *both* mechanisms are
+used in the same project. Consider the following CMake code executed in a
+system with Python 2.7 and 3.x installed:
+
+.. code-block:: cmake
+
+    find_package(PythonInterp)
+    find_package(PythonLibs)
+    find_package(pybind11)
+
+It will detect Python 2.7 and pybind11 will pick it as well.
+
+In contrast this code:
+
+.. code-block:: cmake
+
+    find_package(pybind11)
+    find_package(PythonInterp)
+    find_package(PythonLibs)
+
+will detect Python 3.x for pybind11 and may crash on
+``find_package(PythonLibs)`` afterwards.
+
+There are three possible solutions:
+
+1. Avoid using ``find_package(PythonInterp)`` and ``find_package(PythonLibs)``
+   from CMake and rely on pybind11 in detecting Python version. If this is not
+   possible, the CMake machinery should be called *before* including pybind11.
+2. Set ``PYBIND11_FINDPYTHON`` to ``True`` or use ``find_package(Python
+   COMPONENTS Interpreter Development)`` on modern CMake (3.12+, 3.15+ better,
+   3.18.2+ best). Pybind11 in these cases uses the new CMake FindPython instead
+   of the old, deprecated search tools, and these modules are much better at
+   finding the correct Python.
+3. Set ``PYBIND11_NOPYTHON`` to ``TRUE``. Pybind11 will not search for Python.
+   However, you will have to use the target-based system, and do more setup
+   yourself, because it does not know about or include things that depend on
+   Python, like ``pybind11_add_module``. This might be ideal for integrating
+   into an existing system, like scikit-build's Python helpers.
+
+How to cite this project?
+=========================
+
+We suggest the following BibTeX template to cite pybind11 in scientific
+discourse:
+
+.. code-block:: bash
+
+    @misc{pybind11,
+       author = {Wenzel Jakob and Jason Rhinelander and Dean Moldovan},
+       year = {2017},
+       note = {https://github.com/pybind/pybind11},
+       title = {pybind11 -- Seamless operability between C++11 and Python}
+    }

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

@@ -0,0 +1,48 @@
+.. only:: latex
+
+   Intro
+   =====
+
+.. include:: readme.rst
+
+.. only:: not latex
+
+    Contents:
+
+.. toctree::
+   :maxdepth: 1
+
+   changelog
+   upgrade
+
+.. toctree::
+   :caption: The Basics
+   :maxdepth: 2
+
+   installing
+   basics
+   classes
+   compiling
+
+.. toctree::
+   :caption: Advanced Topics
+   :maxdepth: 2
+
+   advanced/functions
+   advanced/classes
+   advanced/exceptions
+   advanced/smart_ptrs
+   advanced/cast/index
+   advanced/pycpp/index
+   advanced/embedding
+   advanced/misc
+
+.. toctree::
+   :caption: Extra Information
+   :maxdepth: 1
+
+   faq
+   benchmark
+   limitations
+   reference
+   cmake/index

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

@@ -0,0 +1,105 @@
+.. _installing:
+
+Installing the library
+######################
+
+There are several ways to get the pybind11 source, which lives at
+`pybind/pybind11 on GitHub <https://github.com/pybind/pybind11>`_. The pybind11
+developers recommend one of the first three ways listed here, submodule, PyPI,
+or conda-forge, for obtaining pybind11.
+
+.. _include_as_a_submodule:
+
+Include as a submodule
+======================
+
+When you are working on a project in Git, you can use the pybind11 repository
+as a submodule. From your git repository, use:
+
+.. code-block:: bash
+
+    git submodule add -b stable ../../pybind/pybind11 extern/pybind11
+    git submodule update --init
+
+This assumes you are placing your dependencies in ``extern/``, and that you are
+using GitHub; if you are not using GitHub, use the full https or ssh URL
+instead of the relative URL ``../../pybind/pybind11`` above. Some other servers
+also require the ``.git`` extension (GitHub does not).
+
+From here, you can now include ``extern/pybind11/include``, or you can use
+the various integration tools (see :ref:`compiling`) pybind11 provides directly
+from the local folder.
+
+Include with PyPI
+=================
+
+You can download the sources and CMake files as a Python package from PyPI
+using Pip. Just use:
+
+.. code-block:: bash
+
+    pip install pybind11
+
+This will provide pybind11 in a standard Python package format. If you want
+pybind11 available directly in your environment root, you can use:
+
+.. code-block:: bash
+
+    pip install "pybind11[global]"
+
+This is not recommended if you are installing with your system Python, as it
+will add files to ``/usr/local/include/pybind11`` and
+``/usr/local/share/cmake/pybind11``, so unless that is what you want, it is
+recommended only for use in virtual environments or your ``pyproject.toml``
+file (see :ref:`compiling`).
+
+Include with conda-forge
+========================
+
+You can use pybind11 with conda packaging via `conda-forge
+<https://github.com/conda-forge/pybind11-feedstock>`_:
+
+.. code-block:: bash
+
+    conda install -c conda-forge pybind11
+
+
+Include with vcpkg
+==================
+You can download and install pybind11 using the Microsoft `vcpkg
+<https://github.com/Microsoft/vcpkg/>`_ dependency manager:
+
+.. code-block:: bash
+
+    git clone https://github.com/Microsoft/vcpkg.git
+    cd vcpkg
+    ./bootstrap-vcpkg.sh
+    ./vcpkg integrate install
+    vcpkg install pybind11
+
+The pybind11 port in vcpkg is kept up to date by Microsoft team members and
+community contributors. If the version is out of date, please `create an issue
+or pull request <https://github.com/Microsoft/vcpkg/>`_ on the vcpkg
+repository.
+
+Global install with brew
+========================
+
+The brew package manager (Homebrew on macOS, or Linuxbrew on Linux) has a
+`pybind11 package
+<https://github.com/Homebrew/homebrew-core/blob/master/Formula/pybind11.rb>`_.
+To install:
+
+.. code-block:: bash
+
+    brew install pybind11
+
+.. We should list Conan, and possibly a few other C++ package managers (hunter,
+.. perhaps). Conan has a very clean CMake integration that would be good to show.
+
+Other options
+=============
+
+Other locations you can find pybind11 are `listed here
+<https://repology.org/project/python:pybind11/versions>`_; these are maintained
+by various packagers and the community.

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

@@ -0,0 +1,72 @@
+Limitations
+###########
+
+Design choices
+^^^^^^^^^^^^^^
+
+pybind11 strives to be a general solution to binding generation, but it also has
+certain limitations:
+
+- pybind11 casts away ``const``-ness in function arguments and return values.
+  This is in line with the Python language, which has no concept of ``const``
+  values. This means that some additional care is needed to avoid bugs that
+  would be caught by the type checker in a traditional C++ program.
+
+- The NumPy interface ``pybind11::array`` greatly simplifies accessing
+  numerical data from C++ (and vice versa), but it's not a full-blown array
+  class like ``Eigen::Array`` or ``boost.multi_array``. ``Eigen`` objects are
+  directly supported, however, with ``pybind11/eigen.h``.
+
+Large but useful features could be implemented in pybind11 but would lead to a
+significant increase in complexity. Pybind11 strives to be simple and compact.
+Users who require large new features are encouraged to write an extension to
+pybind11; see `pybind11_json <https://github.com/pybind/pybind11_json>`_ for an
+example.
+
+
+Known bugs
+^^^^^^^^^^
+
+These are issues that hopefully will one day be fixed, but currently are
+unsolved. If you know how to help with one of these issues, contributions
+are welcome!
+
+- Intel 20.2 is currently having an issue with the test suite.
+  `#2573 <https://github.com/pybind/pybind11/pull/2573>`_
+
+- Debug mode Python does not support 1-5 tests in the test suite currently.
+  `#2422 <https://github.com/pybind/pybind11/pull/2422>`_
+
+- PyPy3 7.3.1 and 7.3.2 have issues with several tests on 32-bit Windows.
+
+Known limitations
+^^^^^^^^^^^^^^^^^
+
+These are issues that are probably solvable, but have not been fixed yet. A
+clean, well written patch would likely be accepted to solve them.
+
+- Type casters are not kept alive recursively.
+  `#2527 <https://github.com/pybind/pybind11/issues/2527>`_
+  One consequence is that containers of ``char *`` are currently not supported.
+  `#2245 <https://github.com/pybind/pybind11/issues/2245>`_
+
+- The ``cpptest`` does not run on Windows with Python 3.8 or newer, due to DLL
+  loader changes. User code that is correctly installed should not be affected.
+  `#2560 <https://github.com/pybind/pybind11/issue/2560>`_
+
+Python 3.9.0 warning
+^^^^^^^^^^^^^^^^^^^^
+
+Combining older versions of pybind11 (< 2.6.0) with Python on exactly 3.9.0
+will trigger undefined behavior that typically manifests as crashes during
+interpreter shutdown (but could also destroy your data. **You have been
+warned**).
+
+This issue was `fixed in Python <https://github.com/python/cpython/pull/22670>`_.
+As a mitigation for this bug, pybind11 2.6.0 or newer includes a workaround
+specifically when Python 3.9.0 is detected at runtime, leaking about 50 bytes
+of memory when a callback function is garbage collected.  For reference, the
+pybind11 test suite has about 2,000 such callbacks, but only 49 are garbage
+collected before the end-of-process. Wheels (even if built with Python 3.9.0)
+will correctly avoid the leak when run in Python 3.9.1, and this does not
+affect other 3.X versions.