******** Lattices ******** Introduction to lattices ======================== Lattices create repeated structures on a mesh defined with a rectangular or triangular pitch. .. note:: At most **one lattice is allowed per module**. However, it is possible to describe lattices of lattices by combining multiple modules. .. note:: In addition to simplifying the modeling, using a lattice is also CPU time efficient. A lattice consists of two components: - a **mesh volume** - a **lattice volume** The **mesh volume** is the repeated unit. It is specified once in the data-set and the code will replicate it as many times as necessary. Note that a mesh volume is strictly prohibited from: - intersecting or being intersected by another volume (no use of the ``INTE`` keyword); - overwriting or being overwritten by another volume (no use of the ``SUPE`` or ``INFE`` keywords); - being in union with another volume (no use of the ``UNIO`` keyword); - being truncated (no use of the ``TRUN`` keyword) - but it is allowed to truncate a volume. The **lattice volume** is the volume that encompasses the entire lattice and contains all the mesh volumes. The lattice volume can: - have any finite shape; - overwrite or be overwritten by another volume (use of the ``SUPE`` or ``INFE`` keywords); - truncate or be truncated by another volume (use of the ``TRUN`` keyword); - be intersected (use of the ``INTE`` keyword) but cannot intersect another volume. However, a lattice volume cannot be in union with another volume (no use of the ``UNIO`` keyword). The mesh volume must be either fully or partially contained in the lattice volume. Geometrical operations such as overwriting, truncation or intersection on a lattice volume are automatically applied to its mesh volumes. .. note:: Volumes other than mesh volumes are allowed inside the lattice volume, provided they are directly contained within it. In this case, they replace the mesh volumes they interact with, as demonstrated in the following example: .. collapse:: Example of other volumes inside the Lattice volume In this example two spheres (in orange and green) overwrite the lattice in two different ways: - Volume 5 has the lattice volume as its parent (it is directly included in the lattice); - Volume 6 does not have the lattice volume as its parent but uses the ``SUPE`` keyword to overwrite the lattice. .. literalinclude :: examples/04_lattice-generality.m6 :language: m6geo .. image:: resources/lattice-generality.png :width: 300px :align: center Lattice creation ================ The creation of a lattice requires at least the definition of: - a rectangular or triangular lattice pitch (``LATS`` or ``LATH`` keywords); - a main mesh volume (``MPRI`` keyword); - the dimensions of the lattice (``DIML`` keyword). Lattice type ------------ .. code-block:: :caption: Block syntax (LATS | LATH ) (..) ENDL Use the ``LATS`` keyword to define a rectangular pitch. In this case, the mesh volumes must be parallelepipeds (``BOX`` or ``LBOX`` keywords). These mesh volumes are then juxtaposed to form a larger rectangular parallelepiped; Use the ``LATH`` keyword to define a triangular pitch. In this case, mesh volumes must be hexagons aligned with the Z-axis (using the ``HEXZ`` keyword). These mesh volumes are then juxtaposed to form several rings of hexagons along the X-axis and Y-axis, and several layers along the Z-axis. The following figures illustrate the two types of lattices: .. drawio-image:: resources/lattice_two-kind.drawio.svg .. The mesh volume is repeated within the boundaries defined by the lattice volume. .. Any mesh volumes extending beyond these boundaries are removed, while those overlapping the lattice volume are truncated to fit within it. .. To remove these truncated mesh volumes, the user can employ the ``DISB`` keyword. Main mesh volume ----------------- The ``MPRI`` keyword defines the main mesh volume of the lattice. .. code-block:: :caption: Block syntax MPRI id-mesh The initial position of this main mesh volume is determined by the index [0, 0, 0] (which corresponds to the first element of the main mesh volume). This “origin” index can be adjusted using the ``INDP`` keyword. Regardless of the mesh volume's position, the lattice is constructed by replicating the main mesh volume, starting from its defined location within the module. Lattice dimensions ------------------ The ``DIML`` keyword defines the size of the lattice. .. code-block:: :caption: Block syntax DIML ( nx ny nz | nc nz ) ================= ============= =========== Input parameter Lattice pitch Description ================= ============= =========== nx ny nz Rectangular Lattice size along the three axes. nc Triangular Lattice radial size (i.e. the number or rings) nz Triangular Lattice size along the Z-axis ================= ============= =========== A negative value means that volumes are replicated up to the limits of the lattice volume. A positive value with a rectangular lattice indicate the number of mesh volumes in the growth direction. The volume defined as the main mesh volume has the minimum coordinates in the corresponding direction. In case of a triangular lattice, a positive value means: - horizontal axis: number of rings around the main mesh volume. The central mesh is considered the first ring. - vertical axis: number of layers in the growth direction Z. The main mesh volume has the [ 0, 0, 0 ] index and the other mesh volumes are numbered according to this origin and to the type of lattice. .. rubric:: Numbering of a rectangular lattice For a rectangular pitch, each index increases along its respective reference axis. .. code-block:: m6geo LATS MPRI … DIML 3 2 3 ENDL .. drawio-image:: resources/lattice_rectangular-numbering.drawio.svg .. rubric:: Numbering of triangular lattice For a triangular pitch, the mesh volumes are numbered using another set of reference axes (O; X', Y', Z): - the (OX') axis is perpendicular to sides 1 and 4 of the main mesh volume; - the (OY') axis is perpendicular to sides 3 and 6 of the main mesh volume; - the (OZ) axis remains unchanged. .. code-block:: m6geo LATH MPRI … DIML ENDL .. drawio-image:: resources/lattice_triangular-numbering.drawio.svg .. collapse:: Example of lattice with negative DIML values .. literalinclude :: examples/04_lattice-infinite.m6 :language: m6geo .. image:: resources/lattice_infinite.png :width: 300px :align: center | Properties of the mesh volume ============================= Mesh indices ------------ The ``INDP`` keyword redefines the mesh volumes numbering. .. code-block:: :caption: Block syntax INDP ix iy iz ================= =========== Input parameter Description ================= =========== ix iy iz Indices of the main mesh volume (default 0, 0, 0) ================= =========== The first main mesh volume will be positioned at the [ix, iy, iz] index as specified by the user. Subsequent mesh volumes will be numbered based on this new origin. .. note:: The ``INDP`` keyword must be placed after the mandatory keywords and before any optional keywords. .. rubric:: Example of INDP .. code-block:: m6geo LATS MPRI … DIML 3 2 3 INDP 3 4 5 ENDL .. drawio-image:: resources/lattice_indp.drawio.svg Secondary mesh volumes ----------------------- The ``MSEC`` keyword allows the replacement of mesh volumes with alternative ones. This keyword must be repeated for every different secondary mesh volume with alternative patterns. .. code-block:: :caption: Block syntax MSEC id p ix(1) iy(1) iz(1) (…) ix(j) iy(j) iz(j) (…) ix(p) iy(p) iz(p) =================== =========== Input parameter Description =================== =========== id Volume identifier of the secondary mesh volume p Number of mesh volumes containing the volume id-msec ix(j) iy(j) iz(j) Indices of the mesh volume *j* for which a secondary mesh volume is used instead of the main mesh volume =================== =========== The following constraints apply to the secondary mesh volume: - its parent volume must be the lattice volume; - its type identifier (``TYPE`` keyword) must be the same as the main mesh volume; - its position in the geometry must be the same as the main mesh volume. .. note:: This keyword must appear both after the lattice mandatory keywords and after the ``INDP`` keyword (if defined). .. collapse:: Example for a rectangular lattice .. literalinclude :: examples/04_lattice-MSEC-rectangular.m6 :language: m6geo .. drawio-image:: resources/lattice_MSEC_rectangular.drawio.svg :width: 300px :align: center | .. collapse:: Example for a triangular lattice pitch .. literalinclude :: examples/04_lattice-MSEC-triangular.m6 :language: m6geo The resulting plot, with the lattice axes indicated by dashed lines, is shown below: .. drawio-image:: resources/lattice_msec-triangular-pitch.drawio.svg :width: 300px :align: center | Secondary mesh as layers ------------------------ The ``LAYE`` keyword provides an alternative method for defining mesh volumes. It allows the user to specify the volume identifiers of each mesh volume for a given layer along the Z-axis. To use this keyword, lattice dimensions (``DIML`` keyword) must be positive values for the horizontal directions (i.e. directions parallel to the (O; X; Y) plane of the reference frame). .. code-block:: :caption: Block syntax LAYE k id(i-min, j-min, k) (..) id(i-max, j-max, k) (..) id(i-min, j-min, k) (..) id(i-max, j-max, k) =================== =========== Input parameter Description =================== =========== k Index of the layer to be modified along the Z-axis id(i, j, k) Identifier of the Volume used for the mesh volume (either main or secondary) with indices [ i, j, k ]. The indices i and j vary from their minimum to maximum value. The k index is a constant value equal to the first argument of the keyword =================== =========== .. note:: This keyword must appear both after the lattice mandatory keywords and after the ``INDP`` keyword (if defined). The following constraints apply to each secondary mesh volume used in the layer: - its parent volume must be the lattice volume; - its type identifier (``TYPE`` keyword) must be the same as the main mesh volume; - its position in the geometry must be the same as the main mesh volume. The following figure illustrates the order of volume identifiers for mesh volumes in the case of a triangular lattice. .. image:: resources/lattice_laye_00.png :width: 300px :align: center .. collapse:: Example for a rectangular lattice .. literalinclude :: examples/04_lattice-LAYE-rectangular.m6 :language: m6geo .. image:: resources/lattice_laye_rectangular.png :width: 300px :align: center | .. collapse:: Example for a triangular lattice pitch .. literalinclude :: examples/04_lattice-LAYE-triangular.m6 :language: m6geo .. image:: resources/lattice_laye_triangular.png :width: 300px :align: center | Discarding or keeping mesh volumes ================================== The mesh volume is repeated within the space defined by the lattice volume. Any mesh volumes that overlap the lattice volume are truncated by the lattice volume itself. However, optional keywords enable the discarding or retention of specified mesh volumes: - ``DISM`` removes a mesh volume from the lattice; - ``DISB`` removes a truncated mesh volume; - ``KEEP`` retains a removed mesh volume (located within the lattice volume). To illustrate these keywords, the following configuration will be considered in the next paragraphs. It is composed of a lattice with rectangular meshes inside a cylinder (the lattice volume): .. image:: resources/lattice_discarding_generality.png .. literalinclude :: examples/04_lattice-discarding_generality.m6 :language: m6geo The ``DIML`` keyword configures the lattice such that: - it is bounded by the cylinder along the X-axis (in both directions), resulting in truncated mesh volumes; - it is bounded by the cylinder along the Y-axis (in both directions), resulting in truncated mesh volumes; - the lattice contains only one layer along the Z-axis. Discarding mesh ---------------- The ``DISM`` keyword removes a mesh volume from the lattice and replaces it with the material composition of the lattice volume containing it. .. code-block:: :caption: Block syntax DISM p ix(1) iy(1) iz(1) (..) ix(j) iy(j) iz(j) (..) ix(p) iy(p) iz(p) =================== =========== Input parameter Description =================== =========== p Number of mesh volumes to remove ix(j) iy(j) iz(j) Indices of the j\ :sup:`th` mesh volume to remove =================== =========== .. rubric:: Example of the `DISM`: .. image:: resources/lattice_DISM.png :width: 300px :align: center .. literalinclude :: examples/04_lattice-DISM.m6 :language: m6geo Discarding truncated mesh -------------------------- The ``DISB`` keyword removes truncated mesh volumes located on the sides of a lattice. A removed mesh volume is replaced by the material composition of the lattice volume. By default, all truncated mesh volumes on the sides of the lattice are removed. .. code-block:: :caption: Block syntax DISB [ BORD id-vol [ FACE p if(1) (..) if(p) ] ] =================== =========== Input parameter Description =================== =========== ``BORD`` id-vol Volume identifier from which incomplete mesh volumes located on its sides are to be removed. ``FACE`` List of faces whose incomplete mesh volumes must be removed p Number of faces of the Volume to be treated if(1) (..) if(p) Volume faces identifiers =================== =========== Optional keywords allow to select more precisely the mesh volumes to remove: - The ``BORD`` keyword, without any options, removes all truncated mesh volumes on the sides of the lattice for which the volume characterized by the *id-vol* identifier is the neighboring volume. This neighboring volume should be either the lattice volume or any volume that truncates or intersects the lattice volume. This keyword must be repeated for each different Volume to be considered. - The ``FACE`` keyword specifies the faces of the neighboring Volume *id-vol* that are common with the sides of the lattice, where the code should remove the truncated mesh volumes. - The identifiers used for the Volume faces are defined in the paragraphs describing the Volume shapes. .. rubric:: Example with DISB keyword only .. image:: resources/lattice_DISB.png :width: 300px :align: center .. literalinclude :: examples/04_lattice-DISB.m6 :language: m6geo .. rubric:: Example with precise selection of discarded mesh .. image:: resources/lattice_DISB-BORD.png :width: 300px :align: center .. literalinclude :: examples/04_lattice-DISB-BORD.m6 :language: m6geo Keeping mesh volumes -------------------- The ``KEEP`` keyword retains the truncated mesh volumes that were previously removed, especially those removed using the DISB keyword. .. code-block:: :caption: Block syntax KEEP p ix(1) iy(1) iz(1) (..) ix(j) iy(j) iz(j) (..) ix(p) iy(p) iz(p) =================== =========== Input parameter Description =================== =========== p Number of mesh volumes to keep ix(j) iy(j) iz(j) Indices of the mesh volume j to keep =================== =========== .. image:: resources/lattice_KEEP.png :width: 300px :align: center .. literalinclude :: examples/04_lattice-KEEP.m6 :language: m6geo Lattices examples ================== Definition of the configuration --------------------------------- In the following sections, we will explore four alternative methods for modeling the configuration depicted below. .. image:: resources/lattice_example_configuration.png :width: 600px :align: center The configuration consists of a storage area containing 16 cylindrical drums stored in air (material 1). These drums form a lattice and contain fissile material (material 5) in spherical form. The details of the different components are as follows: - the storage area is a parallelepiped room filled with air; - each cylinder is filled with air and has a wall consisting of two layers: an outer steel layer (material 2) and an inner lead layer (material 3); - the fissile material is modeled as a sphere of fissile material surrounded by water (material 4). The following modules represent the drum and the fissile sphere. They are described here to simplify the dataset used for modeling. .. image:: resources/lattice_example_modules.png :width: 300px :align: center First modeling: no lattice definition -------------------------------------- One straightforward approach is to describe this geometry without using lattice functions. In this example, four modules are used as follows: - module 0 consists of 12 Holes (module 10); - module 10 is a parallelepiped containing a cylindrical Hole (module 1); - module 1 represents a cell containing cylindrical volumes, which, in turn, includes a Hole (module 2). - module 2 represents the fissile material in the form of a sphere surrounded by water. .. collapse:: Input file: No lattice definition .. literalinclude :: examples/04_lattice-example-first.m6 :language: m6geo .. image:: resources/lattice_example_first.png :width: 500px :align: center | Second modeling: definition of a single lattice ------------------------------------------------- An alternative method involves using a lattice whose dimensions are [4, 3, 1], where the main mesh volume is a box containing the cylinders and the spheres. In this example, only one module is used. .. collapse:: Input file: Definition of a single lattice .. literalinclude :: examples/04_lattice-example-second.m6 :language: m6geo .. image:: resources/lattice_example_second.png :width: 500px :align: center | Third modeling: definition of a single lattice using the modular geometry -------------------------------------------------------------------------- The third version includes a lattice in the main module and two additional modules as follows: - module 0 consists of a lattice with dimensions [4, 3, 1] and a mesh volume that contains module 1; - module 1 represents a cell containing cylindrical volumes, which in turn contain a Hole (module 2); - module 2 represents the fissile material in the form of a sphere surrounded by water. .. collapse:: Input file: Definition of a single lattice using the modular geometry .. literalinclude :: examples/04_lattice-example-third.m6 :language: m6geo .. image:: resources/lattice_example_third.png :width: 500px :align: center |