diff --git a/docs/conf.py b/docs/conf.py index 96212302..15a1f7a1 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -3,11 +3,13 @@ author = "Tom de Geus" extensions = [ + "sphinx_tabs.tabs", + "sphinx.ext.autosummary", "sphinx.ext.mathjax", "sphinx.ext.todo", - "sphinx_tabs.tabs", ] +autodoc_type_aliases = {"Iterable": "Iterable", "ArrayLike": "ArrayLike", "DTypeLike": "DTypeLike"} templates_path = ["_templates"] exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] html_theme = "furo" diff --git a/docs/python_install.rst b/docs/python_install.rst index 1386a8f8..6bcfa7e0 100644 --- a/docs/python_install.rst +++ b/docs/python_install.rst @@ -11,37 +11,30 @@ The quickest (but not the most efficient!) is to use *conda* to install *GooseEY .. warning:: - This package does not benefit from *xsimd* optimisation, as it is not compiled on your hardware. Therefore compiling by hand is recommended. + This package does not benefit from *xsimd* optimisation, as it is not compiled on your hardware. Therefore compiling by hand can be advantageous. From source ^^^^^^^^^^^ -Start by installing the dependencies, for example using *conda*:: +Start by downloading the package:: - conda install -c conda-forge pyxtensor xsimd - -Note that *xsimd* is optional, but recommended. - -.. note:: - - You can also use:: + git checkout https://github.com/tdegeus/GooseEYE.git + cd GooseEYE - python -m pip install pyxtensor pybind11 +Then, install the dependencies, for example using *conda*:: - for use without *conda*. Note that you install *xsimd* yourself in such a way that Python can find it in order to use it. + conda env update --file environment.yaml -Then, download the package:: +Finally, install the package using:: - git checkout https://github.com/tdegeus/GooseEYE.git - cd GooseEYE + python -m pip install . -v --no-build-isolation --no-deps -Install the package using:: +If you want to use hardware optimisations, you can use:: - python -m pip install . + SKBUILD_CONFIGURE_OPTIONS="-DUSE_SIMD=1" python -m pip install . -v --no-build-isolation --no-deps .. note:: - The following will give more readable output:: - - python setup.py build - python setup.py install + Since you are compiling a C++ extension, with C++ libraries as dependencies, you cannot rely solely on *pip* to install the dependencies. + As observed, *conda* does contain all the dependencies. + Alternatively, you can use whatever non-supported method you prefer. diff --git a/docs/python_usage.rst b/docs/python_usage.rst index 85de71d8..76752f63 100644 --- a/docs/python_usage.rst +++ b/docs/python_usage.rst @@ -2,9 +2,11 @@ Functions & Usage ################### -The Python interface is a simple wrapper around the C++ classes and -functions. In general the Python and C++ codes are almost identical, -with as only differences: +Syntax +====== + +The Python interface is mostly wrapper around the C++ classes and functions. +In general the Python and C++ codes are almost identical, with as only differences: - The C++ ``xt::xarray`` are ``numpy.ndarray`` in Python. - The syntax ``::`` in Python in simply a ``.``. @@ -20,3 +22,19 @@ In Python is .. code:: python ensemble = GooseEYE.Ensemble([51, 51]) + +Python only functions +===================== + +Overview +-------- + +.. autosummary:: + + GooseEYE.Structure + +Details +------- + +.. automodule:: GooseEYE + :members: diff --git a/docs/theory_heightheight.rst b/docs/theory_heightheight.rst index 3f6dbff7..071da689 100644 --- a/docs/theory_heightheight.rst +++ b/docs/theory_heightheight.rst @@ -14,6 +14,14 @@ The structure factor is defined as: S(\vec{q}) = \langle \hat{u}(\vec{q}) \hat{u}(\vec{q}) \rangle where :math:`\vec{q}` is the angular frequency. +It can be used to compute the roughness exponent :math:`\zeta`: + +.. math:: + + S(|q|) \sim |q|^{-(d + 2 \zeta)} + +where :math:`d` is the dimension of the image. +An example is shown below. .. image:: examples/structure.svg :width: 700px diff --git a/python/GooseEYE/__init__.py b/python/GooseEYE/__init__.py index 36f2e23c..25c93dd0 100644 --- a/python/GooseEYE/__init__.py +++ b/python/GooseEYE/__init__.py @@ -11,6 +11,7 @@ def ClusterLabeller(shape, periodic=True, **kwargs): """ Allocate a cluster labeller. + :param shape: The shape of the image. :param periodic: Whether the image is periodic. :return: A cluster labeller.