From df786664a855329fc0cec74ad7a54795fcc10f27 Mon Sep 17 00:00:00 2001 From: Paul Romano Date: Mon, 27 Mar 2017 21:05:47 -0500 Subject: [PATCH] Finish geometry section --- docs/source/usersguide/basics.rst | 2 +- docs/source/usersguide/geometry.rst | 156 ++++++++++++++++++++++++++- docs/source/usersguide/index.rst | 1 + docs/source/usersguide/materials.rst | 28 ++--- docs/source/usersguide/tallies.rst | 5 + 5 files changed, 171 insertions(+), 21 deletions(-) create mode 100644 docs/source/usersguide/tallies.rst diff --git a/docs/source/usersguide/basics.rst b/docs/source/usersguide/basics.rst index 3383cb9fc8..5a2772da91 100644 --- a/docs/source/usersguide/basics.rst +++ b/docs/source/usersguide/basics.rst @@ -25,7 +25,7 @@ described below. :ref:`io_geometry` This file describes how the materials defined in ``materials.xml`` occupy regions of space. Physical volumes are defined using constructive solid - geometry, described in detail in FIXME. + geometry, described in detail in :ref:`usersguide_geometry`. :ref:`io_settings` This file indicates what mode OpenMC should be run in, how many particles diff --git a/docs/source/usersguide/geometry.rst b/docs/source/usersguide/geometry.rst index 8a21e4d742..300aad93e6 100644 --- a/docs/source/usersguide/geometry.rst +++ b/docs/source/usersguide/geometry.rst @@ -4,6 +4,8 @@ Defining Geometry ================= +.. currentmodule:: openmc + -------------------- Surfaces and Regions -------------------- @@ -137,6 +139,8 @@ Reflective and periodic boundary conditions can be set with the strings applied to any type of surface. Periodic boundary conditions can only be applied to pairs of axis-aligned planar surfaces. +.. _usersguide_cells: + ----- Cells ----- @@ -152,18 +156,26 @@ the :class:`openmc.Cell` class:: fuel.fill = uo2 fuel.region = pellet +In this example, an instance of :class:`openmc.Material` is assigned to the +:attr:`Cell.fill` attribute. One can also fill a cell with a :ref:`universe +` or :ref:`lattice `. + The classes :class:`Halfspace`, :class:`Intersection`, :class:`Union`, and :class:`Complement` and all instances of :class:`openmc.Region` and can be assigned to the :attr:`Cell.region` attribute. +.. _usersguide_universes: + --------- Universes --------- Similar to MCNP and Serpent, OpenMC is capable of using *universes*, collections of cells that can be used as repeatable units of geometry. At a minimum, there -must be one "root" universe present in the model. To create a universe, the -:class:`openmc.Universe` is used:: +must be one "root" universe present in the model. To define a universe, an +instance of :class:`openmc.Universe` is created and then cells can be added +using the :meth:`Universe.add_cells` or :meth:`Universe.add_cell` +methods. Alternatively, a list of cells can be specified in the constructor:: universe = openmc.Universe(cells=[cell1, cell2, cell3]) @@ -181,17 +193,141 @@ Universes are generally used in three ways: 3. To be used in a regular arrangement of universes in a :ref:`lattice `. +Note that as you are building a geometry, it is possible to display a plot of +single universe using the :meth:`Universe.plot` method. This method requires +that you have `matplotlib `_ installed. + .. _usersguide_lattices: -------- Lattices -------- +Many particle transport models involve repeated structures that occur in a +regular pattern such as a rectangular or hexagonal lattice. In such a case, it +would be cumbersome to have to define the boundaries of each of the cells to be +filled with a universe. OpenMC provides a means to define lattice structures +through the :class:`openmc.RectLattice` and :class:`openmc.HexLattice` classes. + +Rectangular Lattices +-------------------- + +A rectangular lattice defines a two-dimension or three-dimensional array of +universes that are filled into rectangular prisms (lattice elements) each of +which has the same width, length, and height. To completely define a rectangular +lattice, one needs to specify + +- The coordinates of the lower-left corner of the lattice + (:attr:`RectLattice.lower_left`), +- The pitch of the lattice, i.e., the distance between the center of adjacent + lattice elements (:attr:`RectLattice.pitch`), +- What universes should fill each lattice element + (:attr:`RectLattice.universes`), and +- A universe that is used to fill any lattice position outside the well-defined + portion of the lattice (:attr:`RectLattice.outer`). + +For example, to create a 3x3 lattice centered at the origin in which each +lattice element is 5cm by 5cm and is filled by a universe ``u``, one could run:: + + lattice = openmc.RectLattice() + lattice.lower_left = (-7.5, -7.5) + lattice.pitch = (5.0, 5.0) + lattice.universes = [[u, u, u], + [u, u, u], + [u, u, u]] + +Note that because this is a two-dimensional lattice, the lower-left coordinates +and pitch only need to specify the :math:`x,y` values. The order that the +universes appear is such that the first row corresponds to lattice elements with +the highest y-value. Note that the :attr:`RectLattice.universes` attribute +expects a doubly-nested iterable of type :class:`openmc.Universe` --- this can +be normal Python lists, as shown above, or a NumPy array can be used as well:: + + lattice.universes = np.tile(u, (3, 3)) + +For a three-dimensional lattice, the :math:`x,y,z` coordinates of the lower-left +coordinate need to be given and the pitch should also give dimensions for all +three axes. For example, to make a 3x3x3 lattice where the bottom layer is +universe ``u``, the middle layer is universe ``q`` and the top layer is universe +``z`` would look like:: + + lat3d = openmc.RectLattice() + lat3d.lower_left = (-7.5, -7.5, -7.5) + lat3d.pitch = (5.0, 5.0, 5.0) + lat3d.universes = [ + [[u, u, u], + [u, u, u], + [u, u, u]], + [[q, q, q], + [q, q, q], + [q, q, q]], + [[z, z, z], + [z, z, z] + [z, z, z]]] + +Again, using NumPy can make things easier:: + + lat3d.universes = np.empty((3, 3, 3), dtype=openmc.Universe) + lat3d.universes[0, ...] = u + lat3d.universes[1, ...] = q + lat3d.universes[2, ...] = z + +Finally, it's possible to specify that lattice positions that aren't normally +without the bounds of the lattice be filled with an "outer" universe. This +allows one to create a truly infinite lattice if desired. An outer universe is +set with the :attr:`RectLattice.outer` attribute. ------------------- Hexagonal Lattices ------------------ +OpenMC also allows creationg of 2D and 3D hexagonal lattices. Creating a +hexagonal lattice is similar to creating a rectangular lattice with a few +differences: + +- The center of the lattice must be specified (:attr:`HexLattice.center`). +- For a 2D hexagonal lattice, a single value for the pitch should be specified, + although it still needs to appear in a list. For a 3D hexagonal lattice, the + pitch in the radial and axial directions should be given. +- As with rectangular lattices, the :attr:`HexLattice.outer` attribute will + specify an outer universe. + +For a 2D hexagonal lattice, the :attr:`HexLattice.universes` attribute should be +set to a two-dimensional list of universes filling each lattice element. Each +sub-list corresponds to one ring of universes and is ordered from the outermost +ring to the innermost ring. The universes within each sub-list are ordered from +the "top" (position with greatest y value) and proceed in a clockwise fashion +around the ring. The :meth:`HexLattice.show_indices` static method can be used +to help figure out how to place universes:: + + >>> print(openmc.HexLattice.show_indices(3)) + (0, 0) + (0,11) (0, 1) + (0,10) (1, 0) (0, 2) + (1, 5) (1, 1) + (0, 9) (2, 0) (0, 3) + (1, 4) (1, 2) + (0, 8) (1, 3) (0, 4) + (0, 7) (0, 5) + (0, 6) + + +Note that by default, hexagonal lattices are positioned such that each lattice +element has two faces that are parallel to the y-axis. As one example, to create +a three-ring lattice centered at the origin with a pitch of 10 cm where all the +lattice elements centered along the y-axis are filled with universe ``u`` and +the remainder and filled with universe ``q``, the following code would work:: + + hexlat = openmc.HexLattice() + hexlat.center = (0, 0) + hexlat.pitch = [10] + + outer_ring = [u, q, q, q, q, q, u, q, q, q, q, q] + middle_ring = [u, q, q, u, q, q] + inner_ring = [u] + hexlat.universes = [outer_ring, middle_ring, inner_ring] + +If you need to create a hexagonal boundary (composed of six planar surfaces) for +a hexagonal lattice, :func:`openmc.get_hexagonal_prism` can be used. .. _usersguide_geom_export: @@ -199,5 +335,19 @@ Hexagonal Lattices Exporting a Geometry Model -------------------------- +Once you have finished building your geometry by creating surfaces, cell, and, +if needed, lattices, the last step is to create an instance of +:class:`openmc.Geometry` and export it to an XML file that the +:ref:`scripts_openmc` executable can read using the +:meth:`Geometry.export_to_xml` method. This can be done as follows:: + + geom = openmc.Geometry(root_univ) + geom.export_to_xml() + + # ..or.. + geom = openmc.Geometry() + geom.root_universe = root_univ + geom.export_to_xml() + .. _constructive solid geometry: http://en.wikipedia.org/wiki/Constructive_solid_geometry .. _quadratic surfaces: http://en.wikipedia.org/wiki/Quadric diff --git a/docs/source/usersguide/index.rst b/docs/source/usersguide/index.rst index 53818941d9..a3f23dd86a 100644 --- a/docs/source/usersguide/index.rst +++ b/docs/source/usersguide/index.rst @@ -17,6 +17,7 @@ essential aspects of using OpenMC to perform simulations. materials geometry settings + tallies scripts processing troubleshoot diff --git a/docs/source/usersguide/materials.rst b/docs/source/usersguide/materials.rst index ed742171e7..a9d66b7cdc 100644 --- a/docs/source/usersguide/materials.rst +++ b/docs/source/usersguide/materials.rst @@ -12,9 +12,7 @@ material has been instantiated, nuclides can be added with :meth:`Material.add_nuclide` and elements can be added with :meth:`Material.add_element`. Densities can be specified using atom fractions or weight fractions. For example, to create a material and add Gd152 at 0.5 atom -percent, you'd run: - -:: +percent, you'd run:: mat = openmc.Material() mat.add_nuclide('Gd152', 0.5, 'ao') @@ -65,9 +63,7 @@ If you have a moderating material in your model like water or graphite, you should assign thermal scattering data (so-called :math:`S(\alpha,\beta)`) using the :meth:`Material.add_s_alpha_beta` method. For example, to model light water, you would need to add hydrogen and oxygen to a material and then assign the -``c_H_in_H2O`` thermal scattering data: - -:: +``c_H_in_H2O`` thermal scattering data:: water = openmc.Material() water.add_nuclide('H1', 2.0) @@ -106,14 +102,14 @@ Temperature Some Monte Carlo codes define temperature implicitly through the cross section data, which is itself given only at a particular temperature. In OpenMC, the material definition is decoupled from the specification of temperature. Instead, -temperatures are assigned to cells (FIXME add link) directly. Alternatively, a -default temperature can be assigned to a material that is to be applied to any -cell where the material is used. In the absence of any cell or material -temperature specification, a global default temperature can be set that is -applied to all cells and materials. Anytime a material temperature is specified, -it will override the global default temperature. Similarly, anytime a cell -temperatures is specified, it will override the material or global default -temperatures. +temperatures are assigned to :ref:`cells ` +directly. Alternatively, a default temperature can be assigned to a material +that is to be applied to any cell where the material is used. In the absence of +any cell or material temperature specification, a global default temperature can +be set that is applied to all cells and materials. Anytime a material +temperature is specified, it will override the global default +temperature. Similarly, anytime a cell temperatures is specified, it will +override the material or global default temperatures. To assign a default material temperature, one should use the ``temperature`` attribute, e.g., @@ -164,9 +160,7 @@ found in FIXME. Once you have a cross sections file that has been generated, you can tell OpenMC to use this file either by setting :attr:`Materials.cross_sections` or by setting the :envvar:`OPENMC_CROSS_SECTIONS` environment variable to the path of the -``cross_sections.xml`` file. The former approach would look like: - -:: +``cross_sections.xml`` file. The former approach would look like:: materials.cross_sections = '/path/to/cross_sections.xml' diff --git a/docs/source/usersguide/tallies.rst b/docs/source/usersguide/tallies.rst new file mode 100644 index 0000000000..2b277601af --- /dev/null +++ b/docs/source/usersguide/tallies.rst @@ -0,0 +1,5 @@ +.. _usersguide_tallies: + +================== +Specifying Tallies +==================