Search
-------------------------

Functions to assist with optimization problems, like a search for critical. To use ``mcnpy.search.search_for_keff``, the user must provide callable functions for creating an MCNP deck, running MCNP, and extracting the simulation outputs. To make these functions less ambiguous, some examples are provided.

.. important:: To use ``search_for_keff``, `SciPy <https://scipy.org/>`_ must be installed. Try running ``pip install scipy`` to install the package.

Building a deck requires a function which accepts an optimization parameter and optional keyword arguments. For instance, we could optimize control rod bank height of the MCNPy RCF model (``mcnpy.example.RCF``).

.. code-block:: python

    def make_deck(h, **kwargs):
        """Create RCF model with at rod height `h`.

        Parameters
        ----------
        h : float
            RCF control rod bank height.
        **kwargs : dict
            Additional keyword arguments.

        Returns
        -------
        filename : str
            Name of the serialized MCNP deck.

        """
        
        name = 'rcf_rods_' + str(height) + '.mcnp'
        # RCF model at 68in water height, bank height h
        rcf = mp.RCF(name, 68, h)
        # Produce an MCTAL file
        rcf.deck += mp.PrintDump(print_mctal=1)

        # Write the deck to file
        filename = 'optimization/' + name
        rcf.deck.write(filename)

        # Return name of deck file
        return filename

While MCNPy does offer the ``mcnpy.run_mcnp`` and ``mcnpy.run_script`` functions to execute an MCNP simulation, ``mcnpy.search.search_for_keff`` requires a run function which only accepts an MCNP file name. However, the included MCNPy run functions can still be utilized.

.. code-block:: python

    def run_mcnp(file):
        mp.run_mcnp(file, inp=False, threads=6)

.. note:: Setting ``inp=False`` is useful for producing outputs with predicable names such as ``my_deck.mcnpm`` for a MCTAL file.

After a simulation completes, the results must be extracted. A basic function for this is included as ``mcnpy.search.get_keff`` which utilizes MCNPTools.

.. code-block:: python

    def get_keff(file:str):
        """Get final keff from an MCTAL file.

        Parameters
        ----------
        file : str
            Name of MCTAL file with keff outputs.

        Returns
        -------
        keff_value : float
            Final keff value.
        keff_std : float
            Final keff standard deviation.
        """

        from mcnptools import Mctal, MctalKcode

        m = Mctal(file+'m')
        kc = m.GetKcode()
        keff = MctalKcode.AVG_COMBINED_KEFF
        keff_std = MctalKcode.AVG_COMBINED_KEFF_STD

        return (kc.GetValue(keff, kc.GetCycles()-1), 
                kc.GetValue(keff_std, kc.GetCycles()-1))

.. note:: This is the default ``get_keff`` function chosen if a user-define option is not sepcified.

Using the previous example functions, executing a |keff| search then becomes

.. code-block:: python

    from mcnpy.search import search_for_keff, get_keff

    crit_height, guesses, keffs = search_for_keff(make_deck, run_mcnp, get_keff, 
                                                  bracket=[0.0, 36.0], 
                                                  tol=1e-5, 
                                                  print_iterations=True, 
                                                  bracketed_method='brentq')

.. automodule:: mcnpy.search
   :members:
   :undoc-members:
   :show-inheritance:

.. |keff| replace:: k\ :sub:`eff`