Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Documentation improvements #190

Merged
merged 4 commits into from
Oct 21, 2024
Merged

Documentation improvements #190

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
b5e69ef
Update installation guide
gipert Oct 18, 2024
72ffc66
docs : move dev guide to dedicated page
gipert Oct 18, 2024
fd605de
docs : copy README introduction to RTD
gipert Oct 18, 2024
79fd6a3
docs : fix itemize indentation
gipert Oct 18, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 43 additions & 0 deletions docs/source/devmanual.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
===============
Developer notes
===============

Building the manual
^^^^^^^^^^^^^^^^^^^

To build the documentation ::

pip install '.[docs]' # to install docs building dependencies
cd pyg4ometry/docs
make
<your browser> build/html/index.html` # to view the docs

Running tests
^^^^^^^^^^^^^

Running tests ::

pip install '.[test]' # to install test running dependencies
pytest

Git
^^^

pre-commit::

pre-commit install # to setup pre-commit in source dir (only once)
pre-commit run --all-files # run pre-commit locally
pre-commit run --all-files black #run only black

Start commit message with the submodule or area changes::

submodule : (type of change) detailed notes

for example::

pycgal : (extra functionality) more 2d mesh processing

Pull requests. PR messages should just explain the change in a concise way as they will form part of the change log
e.g::

FLUKA region viewer
67 changes: 62 additions & 5 deletions docs/source/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,14 +1,70 @@
pyg4ometry Documentation
========================
pyg4ometry
==========

pyg4ometry is a package to create, load, write and visualise solid geometry for
particle tracking simulations.
Python code for rapid creation and conversion of radiation transport Monte
Carlo (Geant4 and Fluka) geometries.

.. figure:: manual/figures/banner2.png
:align: center

Example accelerator tunnel complex at CERN.
Quick start
-----------

pyg4ometry is a very capable package to do many tasks related
to Geant4/Fluka/MCNP geometry:

- Python scripting to create and assemble geometries
- Loading, editing and writing GDML
- Load and tessellate CAD geometry and export to GDML
- Load ROOT geometry and convert to GDML
- Powerful VTK viewer of geometries
- Converting from GDML to FLUKA and MCNP
- Exporting mesh geometries from GDML to VTP, OBJ, VRML etc.
- Python bindings to CGAL allowing complex mesh manipulation (e.g. hole filling, remeshing)

All with few lines of Python code!

.. code:: python

import pyg4ometry as pg4
from g4edgetestdata import G4EdgeTestData

g4data = G4EdgeTestData()
# define a geometry registry
reg = pg4.geant4.Registry()

# build the world volume
world_s = pg4.geant4.solid.Orb("WorldAir", 1.5, reg, lunit="cm")
world_l = pg4.geant4.LogicalVolume(world_s, "G4_AIR", "WorldAir", reg)
reg.setWorld(world_l)

# import an STL file
reader = pg4.stl.Reader(g4data["stl/utah_teapot.stl"], registry=reg)
teapot_s = reader.getSolid()

# place the teapot in the world
teapot_l = pg4.geant4.LogicalVolume(teapot_s, "G4_Cu", "UtahTeapot", reg)
pg4.geant4.PhysicalVolume([0, 0, 0], [0, 0, 0], teapot_l, "UtahTeapot", world_l, reg)

# export to GDML file "geometry.gdml"
writer = pg4.gdml.Writer()
writer.addDetector(reg)
writer.write("./geometry.gdml")

# start an interactive VTK viewer instance
viewer = pg4.visualisation.VtkViewer()
viewer.addLogicalVolume(reg.getWorldVolume())
viewer.view()

Check out our video tutorial for more:

.. image:: https://img.youtube.com/vi/OPvQFZsFvhs/maxresdefault.jpg
:alt: YouTube video thumbnail
:target: https://www.youtube.com/watch?v=OPvQFZsFvhs


Next steps
----------

.. toctree::
:maxdepth: 2
Expand All @@ -25,6 +81,7 @@ particle tracking simulations.
citation
Changelog <https://github.com/g4edge/pyg4ometry/releases>
version_history
devmanual


Indices and tables
Expand Down
205 changes: 59 additions & 146 deletions docs/source/manual/installation.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,175 +2,88 @@
Installation
============

Installing from PyPi
--------------------
Pre-built wheels
----------------

pyg4ometry runs on all mainstream platforms (Linux, MacOS and Windows) and
requires at least Python 3.7.

The easiest way to install pyg4ometry is to install from PyPi. Pyg4ometry
has many external requirements which need to be provided by a package
manager on your system. To install using PyPi::
The easiest and recommended way to install it is `from PyPI
<https://pypi.org/project/pyg4ometry/>`_: ::

pip install pyg4ometry

If installing for MacOS you will need to install (opencascade, cgal, gmp, mpfr, boost, vtk)::
All C++ libraries required by pyg4ometry at runtime are bundled with the Python
wheel.

brew install opencascade cgal gmp mpfr boost vtk
A Docker image with the latest stable version of pyg4ometry can be downloaded
`from Docker Hub <https://hub.docker.com/repository/docker/g4edge/pyg4ometry>`_

If installing for Windows you will need to install (opencascade, cgal)::
.. code:: console

conda install occt cgal-cpp
$ docker run g4edge/pyg4ometry:latest python
Python 3.10.12 (main, Jun 11 2023, 05:26:28) [GCC 11.4.0] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import pyg4ometry
>>>

Building from source
--------------------

Requirements
^^^^^^^^^^^^

pyg4ometry is developed exclusively for Python 3 (Python2 is deprecated). It is developed on Python 3.9 and 3.10.

* `VTK (Visualisation toolkit) <https://vtk.org>`_ (including Python bindings)
* `antlr4 <https://www.antlr.org>`_
* `cython <https://cython.org>`_
* `CGAL <https://www.cgal.org>`_
* pybind11
* cmake

Packages that are required but will be found through PIP automatically:
In case you need an unstable version of pyg4ometry or you are interested in
developing, some non-Python dependencies are required.

* `matplotlib <https://matplotlib.org>`_
* `GitPython <https://gitpython.readthedocs.io/en/stable/>`_
* pandas
* pypandoc
* networkx
* numpy
* sympy
The following C/C++ libraries (and headers) are required to build the package from source:

.. note:: A full list can be found in :code:`pyg4ometry/pyproject.toml`.
* `boost <https://www.boost.org/>`_
* `The GNU Multiple Precision Arithmetic Library (GMP) <https://gmplib.org/>`_
* `The GNU MPFR Library <https://www.mpfr.org/>`_
* `The Computational Geometry Algorithms Library (CGAL) <https://www.cgal.org>`_
* `The Visualisation toolkit (VTK) <https://vtk.org>`_ (including Python bindings)
* `OpenCascade <https://dev.opencascade.org/>`_

.. note:: if you are choosing a python version, it is worth choosing according to which
version VTK provides a python build of through PIP if you use that. See
https://pypi.org/project/vtk/#files For example, there are limited builds
for M1 Mac (ARM64).
Additionally, `CMake <https://cmake.org>`_ is required for building pyg4ometry's C++ extensions.

.. tip::
Check out the `platform-specific scripts
<https://github.com/g4edge/pyg4ometry/tree/main/.github/bin>`_ we use to
obtain dependencies in our CI/CD workflow.

Building
^^^^^^^^
If you want to save yourself the hassle of installing these dependencies, we
recommend building in our Ubuntu Docker image, available `on Docker Hub
<https://hub.docker.com/repository/docker/g4edge/ubuntu>`_:

To install pyg4ometry, simply run ``make install`` from the root pyg4ometry
directory::
.. code:: console

cd /my/path/to/repositories/
git clone https://github.com/g4edge/pyg4ometry
cd pyg4ometry
$ docker run -it g4edge/ubuntu:latest
root@b260417746a1:~#

pip install .

If you wish to develop an extension or modify pyg4ometry then run::

pip install -e .

as this will not install pyg4ometry, but the git repository directory will
be used for the package. To confirm the install location run::

pip list | grep pyg4ometry
All Python dependencies will be automatically obtained by pip.

.. note::
The building uses skikit-build which required cmake. Build errors
or warnings are typically from cmake and can help determining the
missing dependency

.. note::
If you are building for windows you are going to need Visual Studio and
the appropriate command line tools

Docker image (needs updating)
-----------------------------

#. Download and install `Docker desktop <https://www.docker.com/products/docker-desktop>`_
#. open a terminal (linux) or cmd (windows)
#. (windows) Start `Xming <https://sourceforge.net/projects/xming/>`_ or `Vxsrv <https://sourceforge.net/projects/vcxsrv/>`_
#. Download the `pyg4ometry docker file <https://bitbucket.org/jairhul/pyg4ometry/raw/82373218033874607f682a77be33e03d5b6706aa/docker/Dockerfile-ubuntu-pyg4ometry>`_
#. ``docker build -t ubuntu-pyg4ometry -f Dockerfile-ubuntu-pyg4ometry .``

If you need to update increment the variable ``ARG PYG4OMETRY_VER=1``

To start the container

#. open a terminal (linux/mac) or cmd (windows)
#. get your IP address ``ifconfig`` (linux/mac) or ``ipconfig /all`` (windows)
#. Start XQuartz (mac) or Xming/Vxsrv (windows). For Xming/Vxsrv (might need to play with the settings when launching)
#. ``docker run -ti -v /tmp/.X11-unix:/tmp/.X11-unix -v YOURWORKDIR:/tmp/Physics -e DISPLAY=YOUR_IP ubuntu-pyg4ometry`` (the ``-v /tmp/.X11-unix:/tmp/.X11-unix`` is only required for mac/linux)

Test the installation

#. ``docker> cd pyg4ometry/pyg4ometry/test/pythonGeant4/``
#. ``docker> ipython``
#. ``python> import pyg4ometry``
#. ``python> import T001_Box``
#. ``python> T001_Box.Test(True,True)``

Linux installation
------------------
It is worth choosing a Python version for which VTK bindings are available
(see https://pypi.org/project/vtk/#files). For example, there are limited
builds for M1 Mac (ARM64).

There are docker files for Centos 7 and Ubuntu 20. The docker files can be used as list of instructions for
installation for each of these OSes.
To install the package, simply run ``pip install`` from the root directory

* `Ubuntu 20.02 <https://bitbucket.org/jairhul/pyg4ometry/raw/82373218033874607f682a77be33e03d5b6706aa/docker/Dockerfile-ubuntu-pyg4ometry>`_
* `Centos 7 <https://bitbucket.org/jairhul/pyg4ometry/raw/befcd36c1213670830b854d02c671ef14b3f0f5c/docker/Dockerfile-centos-pyg4ometry>`_
.. code:: console

Python 3.9
----------
$ git clone https://github.com/g4edge/pyg4ometry
$ cd pyg4ometry
$ pip install .

At the time of writing, there are limited VTK distributions for Python 3.9 on pypi (what
PIP uses when finding packages). However,
you can have VTK with Python 3.9 through say MacPorts or by compiling it yourself. In this
case, you can comment out the VTK requirement from the setup.py around line 86, as long
as you know you can :code:`import vtk` ok in your Python installation.
.. tip::
The building uses CMake through `scikit-build-core
<https://scikit-build-core.readthedocs.io>`_. Build errors or warnings are
typically from cmake and can help determining the missing dependency.

.. warning:: ANTLR will create an unbelievable amount of warnings when using a different
ANRLR version that the one the parser was generated with. It should work
though. We are trying to include multiple versions of the ANTLR parser
to avoid this in future.

Developer notes
---------------

Building the manual
^^^^^^^^^^^^^^^^^^^

To build the documentation ::

pip install '.[docs]' # to install docs building dependencies
cd pyg4ometry/docs
make
<your browser> build/html/index.html` # to view the docs

Running tests
^^^^^^^^^^^^^

Running tests ::

pip install '.[test]' # to install test running dependencies
pytest


Git
^^^

pre-commit::

pre-commit install # to setup pre-commit in source dir (only once)
pre-commit run --all-files # run pre-commit locally
pre-commit run --all-files black #run only black

Start commit message with the submodule or area changes::

submodule : (type of change) detailed notes

for example::

pycgal : (extra functionality) more 2d mesh processing

Pull requests. PR messages should just explain the change in a concise way as they will form part of the change log
e.g::

FLUKA region viewer
.. note::
If you are building for windows you are going to need Visual Studio and
the appropriate command line tools.

.. warning::
the package is built in parallel by default and is memory intensive! Make
sure you have enough computational resources. If not, consult the
scikit-build-core documentation to learn how to reduce the number of
threads.
Loading
Loading