*****************
Hole creation
*****************

Modules can be inserted into each other using holes.
Holes allow to duplicate modules and then to duplicate parts of the geometry without the need to copy-past the duplicated geometry description.


.. code-block:: m6geo
  :caption: Block syntax

  HOLE id cont type modu x y z

The ``HOLE`` keyword is used to create a hole that will contain a module.
Module and hole must have the same shape and size. 
In general, it is defined by:


===============     ===========
Input parameter     Description
===============     ===========
id                  Unique identifier within its module
cont                A parent volume, i.e. a volume in which it is completely included
type                Enclosed shape
modu                module to insert into the hole
x y z               Position within the module:

                      - the center of the Hole if it has a finite shape;
                      - the interior point specified in the description of the ``MPLA`` keyword.
===============     ===========


.. note::
  - The identifier of the module to be inserted must not be 0 (the main module refered as module 0 and cannot be inserted into another module);
  - As a hole cannot be an external volume, *cont* = 0 is not allowed;

.. rubric:: Example n°1 using HOLE

Here is the schematic description of a system's geometry:

- Volumes (not Hole) defined in Module 0 are in black;
- Volumes (not Hole) defined in Module 1 are in blue;
- Volumes (not Hole) defined in Module 2 are in green;
- Volumes (not Hole) defined in Module 3 are in red.

.. drawio-image:: resources/example01.drawio.svg
  


The corresponding dataset is:

.. code-block:: m6geo

  GEOM
    MODU  0                               * Module 0 forms the basis of the geometry
      TYPE  t1  BOX  30.  30.  30.
      TYPE  t2  BOX  10.  10.  10.
      VOLU  v1  0  t1   m1  0.  0.  0.    * Volume 1 is external Volume (black)
      HOLE  h1  v1  t2  1  -17.  12. 0.   * Hole 1 is filled with Module 1
      HOLE  h2  v1  t2  1   17.  12. 0.   * Hole 2 is filled with Module 1
      HOLE  h3  v1  t2  1   17  -12. 0.   * Hole 3 is filled with Module 1
      HOLE  h4  v1  t2  3  -17. -12. 0.   * Hole 4 is filled with Module 3
    ENDM

    MODU  1                               * Module 1 contains a Volume and a Hole
      TYPE  t1  BOX  10.  10.  10.
      TYPE  t2  SPHE  7.
      VOLU   v1   0  t1  m3  0.  0.  0.   * External Volume of the Module (blue)
      HOLE   h1  v1  t2   2  3.  0.  0.   * Hold the two green spheres defined in Module 2
    ENDM

    MODU  2
      TYPE  t1  SPHE  7.
      TYPE  t2  SPHE  3.
      VOLU  v1   0  t1  m4  0.  0.  0.    * Outer green sphere (and external Volume of the Module)
      VOLU  v2  v1  t2  m5  0.  0.  0.    * Inner green sphere
    ENDM

    MODU  3
      TYPE  t1  BOX  10.  10.  10.
      TYPE  t2  BOX  1.  5.  1.
      TYPE  t3  SPHE  7.
      VOLU  v1   0  t1  m3   0  0  0      * This is the external Volume (not shown)
      VOLU  v2  v1  t2  m6   7  0  0      * This is the red box
      HOLE  h1  v1  t3  2   -3  0  0      * This hold the two green spheres
    ENDM
  ENDG


As the naming of material compositions is common across all modules, Material 3 of Module 1 and Material 3 of Module 3 refer to the same material composition.


.. rubric:: Example n°2 using HOLE

The following are two different modeling of modular geometries, which use three common modules:

- Module 1 is composed of two Volumes;
- Module 2 uses Module 1 within the main mesh of a 2 x 2 x 1 lattice;
- Module 3 is composed of three Volumes.

.. drawio-image:: resources/example02-00.drawio.svg
  


Considering these modules, the main module of the following geometry utilizes:

- Module 1 in six positions;
- Module 2 in only one position;
- Module 3 in two positions.

.. drawio-image:: resources/example02-01.drawio.svg
  


In the same manner, the main module of the following geometry utilizes:

- Module 1 in two positions;
- Module 2 within the main mesh of a 2 x 1 x 1 lattice;
- Module 3 in only one position.

.. drawio-image:: resources/example02-02.drawio.svg