diff --git a/docs/source/pythonapi/index.rst b/docs/source/pythonapi/index.rst index 2d998c302..fec0ad767 100644 --- a/docs/source/pythonapi/index.rst +++ b/docs/source/pythonapi/index.rst @@ -115,16 +115,6 @@ Many of the above classes are derived from several abstract classes: openmc.Region openmc.Lattice -One function is also available to create a hexagonal region defined by the -intersection of six surface half-spaces. - -.. autosummary:: - :toctree: generated - :nosignatures: - :template: myfunction.rst - - openmc.make_hexagon_region - Constructing Tallies -------------------- diff --git a/openmc/mgxs/mgxs.py b/openmc/mgxs/mgxs.py index 7653deca4..fb871a4b0 100644 --- a/openmc/mgxs/mgxs.py +++ b/openmc/mgxs/mgxs.py @@ -5201,8 +5201,101 @@ class NuScatterProbabilityMatrix(ScatterProbabilityMatrix): @add_metaclass(ABCMeta) class ConvolvedMGXS(MGXS): + """An abstract convolution of multiple multi-group cross sections for some + energy group structure within some spatial domain. - # FIXME: Add docstring + This class can be used for both OpenMC input generation and tally data + post-processing to compute spatially-homogenized and energy-integrated + multi-group cross sections for multi-group neutronics calculations. + + NOTE: Users should instantiate the subclasses of this abstract class. + + Parameters + ---------- + domain : openmc.Material or openmc.Cell or openmc.Universe or openmc.Mesh + The domain for spatial homogenization + domain_type : {'material', 'cell', 'distribcell', 'universe', 'mesh'} + The domain type for spatial homogenization + energy_groups : openmc.mgxs.EnergyGroups + The energy group structure for energy condensation + by_nuclide : bool + If true, computes cross sections for each nuclide in domain + name : str, optional + Name of the multi-group cross section. Used as a label to identify + tallies in OpenMC 'tallies.xml' file. + num_polar : Integral, optional + Number of equi-width polar angle bins for angle discretization; + defaults to one bin + num_azimuthal : Integral, optional + Number of equi-width azimuthal angle bins for angle discretization; + defaults to one bin + + Attributes + ---------- + name : str, optional + Name of the multi-group cross section + rxn_type : str + Reaction type (e.g., 'total', 'nu-fission', etc.) + by_nuclide : bool + If true, computes cross sections for each nuclide in domain + domain : Material or Cell or Universe or Mesh + Domain for spatial homogenization + domain_type : {'material', 'cell', 'distribcell', 'universe', 'mesh'} + Domain type for spatial homogenization + energy_groups : openmc.mgxs.EnergyGroups + Energy group structure for energy condensation + num_polar : Integral + Number of equi-width polar angle bins for angle discretization + num_azimuthal : Integral + Number of equi-width azimuthal angle bins for angle discretization + tally_trigger : openmc.Trigger + An (optional) tally precision trigger given to each tally used to + compute the cross section + scores : list of str + The scores in each tally used to compute the multi-group cross section + filters : list of openmc.Filter + The filters in each tally used to compute the multi-group cross section + tally_keys : list of str + The keys into the tallies dictionary for each tally used to compute + the multi-group cross section + estimator : {'tracklength', 'collision', 'analog'} + The tally estimator used to compute the multi-group cross section + tallies : collections.OrderedDict + OpenMC tallies needed to compute the multi-group cross section + rxn_rate_tally : openmc.Tally + Derived tally for the reaction rate tally used in the numerator to + compute the multi-group cross section. This attribute is None + unless the multi-group cross section has been computed. + xs_tally : openmc.Tally + Derived tally for the multi-group cross section. This attribute + is None unless the multi-group cross section has been computed. + num_subdomains : int + The number of subdomains is unity for 'material', 'cell' and 'universe' + domain types. This is equal to the number of cell instances + for 'distribcell' domain types (it is equal to unity prior to loading + tally data from a statepoint file) and the number of mesh cells for + 'mesh' domain types. + num_nuclides : int + The number of nuclides for which the multi-group cross section is + being tracked. This is unity if the by_nuclide attribute is False. + nuclides : Iterable of str or 'sum' + The optional user-specified nuclides for which to compute cross + sections (e.g., 'U238', 'O16'). If by_nuclide is True but nuclides + are not specified by the user, all nuclides in the spatial domain + are included. This attribute is 'sum' if by_nuclide is false. + sparse : bool + Whether or not the MGXS' tallies use SciPy's LIL sparse matrix format + for compressed data storage + loaded_sp : bool + Whether or not a statepoint file has been loaded with tally data + derived : bool + Whether or not the MGXS is merged from one or more other MGXS + hdf5_key : str + The key used to index multi-group cross sections in an HDF5 data store + mgxs : list of openmc.mgxs.MGXS + A list of MGXS to combine to compute this multi-group cross section + + """ def __init__(self, domain=None, domain_type=None, groups=None, by_nuclide=False, name='', num_polar=1, num_azimuthal=1): @@ -5461,8 +5554,150 @@ class ConvolvedMGXS(MGXS): class ConsistentScatterMatrixXS(ConvolvedMGXS, ScatterMatrixXS): + r"""A scattering matrix multi-group cross section computed as the product + of the scatter cross section and group-to-group scattering probabilities. - # FIXME: Add docstring + This class is a variation of the :class:`ScatterMatrixXS` which computes + the scattering matrix as the convolution product of :class:`ScatterXS` and + :class:`ScatterProbabilityMatrix`. Unlike the :class:`ScatterMatrixXS`, + this scattering matrix is computed from the scattering cross section which + uses a tracklength estimator. This ensures that reaction rate balance is + exactly preserved with a :class:`TotalXS` computed using a tracklength + estimator. + + This class can be used for both OpenMC input generation and tally data + post-processing to compute spatially-homogenized and energy-integrated + multi-group cross sections for multi-group neutronics calculations. At a + minimum, one needs to set the + :attr:`ConsistentScatterMatrixXS.energy_groups` and + :attr:`ConsistentScatterMatrixXS.domain` properties. Tallies for the flux + and appropriate reaction rates over the specified domain are generated + automatically via the :attr:`ConsistentScatterMatrixXS.tallies` property, + which can then be appended to a :class:`openmc.Tallies` instance. + + For post-processing, the :meth:`MGXS.load_from_statepoint` will pull in the + necessary data to compute multi-group cross sections from a + :class:`openmc.StatePoint` instance. The derived multi-group cross section + can then be obtained from the :attr:`ConsistentScatterMatrixXS.xs_tally` + property. + + For a spatial domain :math:`V`, incoming energy group + :math:`[E_{g'},E_{g'-1}]`, and outgoing energy group :math:`[E_g,E_{g-1}]`, + the Legendre scattering moments are calculated as: + + .. math:: + + \langle \sigma_{s,g'\rightarrow g} \phi \rangle &= \int_{r \in V} dr + \int_{4\pi} d\Omega' \int_{E_{g'}}^{E_{g'-1}} dE' \int_{4\pi} d\Omega + \int_{E_g}^{E_{g-1}} dE \; \sigma_s (r, E' + \rightarrow E, \Omega' \cdot \Omega) \psi(r, E', \Omega')\\ + \langle \phi \rangle &= \int_{r \in V} dr \int_{4\pi} d\Omega + \int_{E_g}^{E_{g-1}} dE \; \psi (r, E, \Omega) \\ + \sigma_{s,g'\rightarrow g} &= \frac{\langle + \sigma_{s,,g'\rightarrow g} \phi \rangle}{\langle \phi \rangle} + + Parameters + ---------- + domain : openmc.Material or openmc.Cell or openmc.Universe or openmc.Mesh + The domain for spatial homogenization + domain_type : {'material', 'cell', 'distribcell', 'universe', 'mesh'} + The domain type for spatial homogenization + groups : openmc.mgxs.EnergyGroups + The energy group structure for energy condensation + by_nuclide : bool + If true, computes cross sections for each nuclide in domain + name : str, optional + Name of the multi-group cross section. Used as a label to identify + tallies in OpenMC 'tallies.xml' file. + num_polar : Integral, optional + Number of equi-width polar angle bins for angle discretization; + defaults to one bin + num_azimuthal : Integral, optional + Number of equi-width azimuthal angle bins for angle discretization; + defaults to one bin + + Attributes + ---------- + correction : 'P0' or None + Apply the P0 correction to scattering matrices if set to 'P0'; this is + used only if :attr:`ConsistentScatterMatrixXS.scatter_format` is + 'legendre' + scatter_format : {'legendre', or 'histogram'} + Representation of the angular scattering distribution (default is + 'legendre') + legendre_order : int + The highest Legendre moment in the scattering matrix; this is used if + :attr:`ConsistentScatterMatrixXS.scatter_format` is 'legendre'. + (default is 0) + histogram_bins : int + The number of equally-spaced bins for the histogram representation of + the angular scattering distribution; this is used if + :attr:`ConsistentScatterMatrixXS.scatter_format` is 'histogram'. + (default is 16) + name : str, optional + Name of the multi-group cross section + rxn_type : str + Reaction type (e.g., 'total', 'nu-fission', etc.) + by_nuclide : bool + If true, computes cross sections for each nuclide in domain + domain : Material or Cell or Universe or Mesh + Domain for spatial homogenization + domain_type : {'material', 'cell', 'distribcell', 'universe', 'mesh'} + Domain type for spatial homogenization + energy_groups : openmc.mgxs.EnergyGroups + Energy group structure for energy condensation + num_polar : Integral + Number of equi-width polar angle bins for angle discretization + num_azimuthal : Integral + Number of equi-width azimuthal angle bins for angle discretization + tally_trigger : openmc.Trigger + An (optional) tally precision trigger given to each tally used to + compute the cross section + scores : list of str + The scores in each tally used to compute the multi-group cross section + filters : list of openmc.Filter + The filters in each tally used to compute the multi-group cross section + tally_keys : list of str + The keys into the tallies dictionary for each tally used to compute + the multi-group cross section + estimator : 'analog' + The tally estimator used to compute the multi-group cross section + tallies : collections.OrderedDict + OpenMC tallies needed to compute the multi-group cross section. The keys + are strings listed in the :attr:`ConsistentScatterMatrixXS.tally_keys` + property + and values are instances of :class:`openmc.Tally`. + rxn_rate_tally : openmc.Tally + Derived tally for the reaction rate tally used in the numerator to + compute the multi-group cross section. This attribute is None + unless the multi-group cross section has been computed. + xs_tally : openmc.Tally + Derived tally for the multi-group cross section. This attribute + is None unless the multi-group cross section has been computed. + num_subdomains : int + The number of subdomains is unity for 'material', 'cell' and 'universe' + domain types. This is equal to the number of cell instances + for 'distribcell' domain types (it is equal to unity prior to loading + tally data from a statepoint file). + num_nuclides : int + The number of nuclides for which the multi-group cross section is + being tracked. This is unity if the by_nuclide attribute is False. + nuclides : Iterable of str or 'sum' + The optional user-specified nuclides for which to compute cross + sections (e.g., 'U238', 'O16'). If by_nuclide is True but nuclides + are not specified by the user, all nuclides in the spatial domain + are included. This attribute is 'sum' if by_nuclide is false. + sparse : bool + Whether or not the MGXS' tallies use SciPy's LIL sparse matrix format + for compressed data storage + loaded_sp : bool + Whether or not a statepoint file has been loaded with tally data + derived : bool + Whether or not the MGXS is merged from one or more other MGXS + hdf5_key : str + The key used to index multi-group cross sections in an HDF5 data store + + """ def __init__(self, domain=None, domain_type=None, groups=None, by_nuclide=False, name='', num_polar=1, num_azimuthal=1): @@ -5619,8 +5854,140 @@ class ConsistentScatterMatrixXS(ConvolvedMGXS, ScatterMatrixXS): class ConsistentNuScatterMatrixXS(ConsistentScatterMatrixXS): + r"""A scattering-production matrix multi-group cross section computed as + the product of the scattering-production cross section and group-to-group + scattering-production probabilities. - # FIXME: Add docstring + This class is a variation of the :class:`NuScatterMatrixXS` which computes + the scattering-production matrix as the convolution product of + :class:`NuScatterXS` and :class:`NuScatterProbabilityMatrix`. Unlike the + :class:`NuScatterMatrixXS`, this scattering-production matrix is computed + from the scattering-production cross section which uses a tracklength + estimator. This ensures that reaction rate balance is exactly preserved + with a :class:`TotalXS` computed using a tracklength estimator. + + This class can be used for both OpenMC input generation and tally data + post-processing to compute spatially-homogenized and energy-integrated + multi-group cross sections for multi-group neutronics calculations. At a + minimum, one needs to set the + :attr:`ConsistentNuScatterMatrixXS.energy_groups` and + :attr:`ConsistentNuScatterMatrixXS.domain` properties. Tallies for the flux + and appropriate reaction rates over the specified domain are generated + automatically via the :attr:`ConsistentNuScatterMatrixXS.tallies` property, + which can then be appended to a :class:`openmc.Tallies` instance. + + For post-processing, the :meth:`MGXS.load_from_statepoint` will pull in the + necessary data to compute multi-group cross sections from a + :class:`openmc.StatePoint` instance. The derived multi-group cross section + can then be obtained from the :attr:`ConsistentNuScatterMatrixXS.xs_tally` + property. + + The calculation of the scattering-production matrix is the same as that for + :class:`ConsistentScatterMatrixXS` except that the scattering multiplicity + is accounted for. + + Parameters + ---------- + domain : openmc.Material or openmc.Cell or openmc.Universe or openmc.Mesh + The domain for spatial homogenization + domain_type : {'material', 'cell', 'distribcell', 'universe', 'mesh'} + The domain type for spatial homogenization + groups : openmc.mgxs.EnergyGroups + The energy group structure for energy condensation + by_nuclide : bool + If true, computes cross sections for each nuclide in domain + name : str, optional + Name of the multi-group cross section. Used as a label to identify + tallies in OpenMC 'tallies.xml' file. + num_polar : Integral, optional + Number of equi-width polar angle bins for angle discretization; + defaults to one bin + num_azimuthal : Integral, optional + Number of equi-width azimuthal angle bins for angle discretization; + defaults to one bin + + Attributes + ---------- + correction : 'P0' or None + Apply the P0 correction to scattering matrices if set to 'P0'; this is + used only if :attr:`ConsistentNuScatterMatrixXS.scatter_format` is + 'legendre' + scatter_format : {'legendre', or 'histogram'} + Representation of the angular scattering distribution (default is + 'legendre') + legendre_order : int + The highest Legendre moment in the scattering matrix; this is used if + :attr:`ConsistentScatterNuMatrixXS.scatter_format` is 'legendre'. + (default is 0) + histogram_bins : int + The number of equally-spaced bins for the histogram representation of + the angular scattering distribution; this is used if + :attr:`ConsistentScatterNuMatrixXS.scatter_format` is 'histogram'. + (default is 16) + name : str, optional + Name of the multi-group cross section + rxn_type : str + Reaction type (e.g., 'total', 'nu-fission', etc.) + by_nuclide : bool + If true, computes cross sections for each nuclide in domain + domain : Material or Cell or Universe or Mesh + Domain for spatial homogenization + domain_type : {'material', 'cell', 'distribcell', 'universe', 'mesh'} + Domain type for spatial homogenization + energy_groups : openmc.mgxs.EnergyGroups + Energy group structure for energy condensation + num_polar : Integral + Number of equi-width polar angle bins for angle discretization + num_azimuthal : Integral + Number of equi-width azimuthal angle bins for angle discretization + tally_trigger : openmc.Trigger + An (optional) tally precision trigger given to each tally used to + compute the cross section + scores : list of str + The scores in each tally used to compute the multi-group cross section + filters : list of openmc.Filter + The filters in each tally used to compute the multi-group cross section + tally_keys : list of str + The keys into the tallies dictionary for each tally used to compute + the multi-group cross section + estimator : 'analog' + The tally estimator used to compute the multi-group cross section + tallies : collections.OrderedDict + OpenMC tallies needed to compute the multi-group cross section. The keys + are strings listed in the :attr:`ConsistentScatterNuMatrixXS.tally_keys` + property + and values are instances of :class:`openmc.Tally`. + rxn_rate_tally : openmc.Tally + Derived tally for the reaction rate tally used in the numerator to + compute the multi-group cross section. This attribute is None + unless the multi-group cross section has been computed. + xs_tally : openmc.Tally + Derived tally for the multi-group cross section. This attribute + is None unless the multi-group cross section has been computed. + num_subdomains : int + The number of subdomains is unity for 'material', 'cell' and 'universe' + domain types. This is equal to the number of cell instances + for 'distribcell' domain types (it is equal to unity prior to loading + tally data from a statepoint file). + num_nuclides : int + The number of nuclides for which the multi-group cross section is + being tracked. This is unity if the by_nuclide attribute is False. + nuclides : Iterable of str or 'sum' + The optional user-specified nuclides for which to compute cross + sections (e.g., 'U238', 'O16'). If by_nuclide is True but nuclides + are not specified by the user, all nuclides in the spatial domain + are included. This attribute is 'sum' if by_nuclide is false. + sparse : bool + Whether or not the MGXS' tallies use SciPy's LIL sparse matrix format + for compressed data storage + loaded_sp : bool + Whether or not a statepoint file has been loaded with tally data + derived : bool + Whether or not the MGXS is merged from one or more other MGXS + hdf5_key : str + The key used to index multi-group cross sections in an HDF5 data store + + """ def __init__(self, domain=None, domain_type=None, groups=None, by_nuclide=False, name='', num_polar=1, num_azimuthal=1): @@ -5630,7 +5997,7 @@ class ConsistentNuScatterMatrixXS(ConsistentScatterMatrixXS): self._rxn_type = 'nu-scatter' self._hdf5_key = 'consistent nu-scatter matrix' - self._mgxs = [NuScatterXS(), ScatterProbabilityMatrix()] + self._mgxs = [NuScatterXS(), NuScatterProbabilityMatrix()] # Assign parameters to each MGXS in the convlution for mgxs in self.mgxs: