|
| 1 | +.. _getting_started: |
| 2 | + |
| 3 | +Getting Started |
| 4 | +--------------- |
| 5 | + |
| 6 | +What is :mod:`watts`? |
| 7 | ++++++++++++++++++++++ |
| 8 | + |
| 9 | +WATTS (Workflow and Template Toolkit for Simulation) consists of a set of Python |
| 10 | +classes that can manage simulation workflows for one or multiple codes. It |
| 11 | +provides the following capabilities: |
| 12 | + |
| 13 | +- An isolated execution environment when running a code; |
| 14 | +- The ability to use placeholder values in input files that are filled in |
| 15 | + programmatically; |
| 16 | +- Seamless :ref:`unit conversions <units>` when working with multiple codes; |
| 17 | +- A managed database that simulation inputs and outputs are automatically saved |
| 18 | + to; and |
| 19 | +- Python classes that provide extra post-processing and analysis capabilities |
| 20 | + for each code. |
| 21 | + |
| 22 | +Basic Execution |
| 23 | ++++++++++++++++ |
| 24 | + |
| 25 | +There are four major types of classes within :mod:`watts`. The |
| 26 | +:class:`~watts.Plugin` class (and its subclasses) provide the main interface to |
| 27 | +codes. As an example, let's say we have the following input file for MCNP that |
| 28 | +we want to run: |
| 29 | + |
| 30 | +.. code-block:: text |
| 31 | +
|
| 32 | + Bare sphere of plutonium |
| 33 | + 1 1 0.04 -1 imp:n=1 |
| 34 | + 2 0 1 imp:n=0 |
| 35 | +
|
| 36 | + 1 so 6.5 |
| 37 | +
|
| 38 | + m1 94239.70c 0.04 |
| 39 | + kcode 10000 1.0 50 150 |
| 40 | + ksrc 0 0 0 |
| 41 | +
|
| 42 | +If the filename of the input file is ``sphere_model``, we start by creating a |
| 43 | +:class:`watts.PluginMCNP` object:: |
| 44 | + |
| 45 | + plugin_mcnp = watts.PluginMCNP("sphere_model") |
| 46 | + |
| 47 | +Calling the plugin class then executes the code:: |
| 48 | + |
| 49 | + result = plugin_mcnp() |
| 50 | + |
| 51 | +When a plugin is called, any input files are copied to a temporary directory to |
| 52 | +create an isolated execution environment. Once the code is finished executing, |
| 53 | +all input and output files are moved to a database, and you are provided a |
| 54 | +:class:`~watts.Results` object that provides an interface to the simulation |
| 55 | +artifacts and methods for common post-processing tasks. In the example above, |
| 56 | +calling the :class:`~watts.PluginMCNP` instance returns a |
| 57 | +:class:`~watts.ResultsMCNP` object, which we can use to get a list of the output |
| 58 | +files or determine the resulting :math:`k_\text{eff}` value: |
| 59 | + |
| 60 | +.. code-block:: pycon |
| 61 | +
|
| 62 | + >>> result.outputs |
| 63 | + [PosixPath('MCNP_log.txt'), |
| 64 | + PosixPath('srctp') |
| 65 | + PosixPath('outp') |
| 66 | + PosixPath('runtpe')] |
| 67 | + >>> result.keff |
| 68 | + 1.0007+/-0.00053 |
| 69 | +
|
| 70 | +Templates and Parameters |
| 71 | +++++++++++++++++++++++++ |
| 72 | + |
| 73 | +The input file shown above is just a normal MCNP input file. However, you can |
| 74 | +also put placeholders in an input file and have :mod:`watts` fill them in using |
| 75 | +the :class:`~watts.Parameters` class. Let's say we change the input file as |
| 76 | +follows: |
| 77 | + |
| 78 | +.. code-block:: jinja |
| 79 | +
|
| 80 | + Bare sphere of plutonium |
| 81 | + 1 1 0.04 -1 imp:n=1 |
| 82 | + 2 0 1 imp:n=0 |
| 83 | +
|
| 84 | + 1 so {{ radius }} |
| 85 | +
|
| 86 | + m1 94239.70c 0.04 |
| 87 | + kcode 10000 1.0 50 {{ cycles }} |
| 88 | + ksrc 0 0 0 |
| 89 | +
|
| 90 | +We've added two placeholders, ``{{ radius }}`` and ``{{ cycles }}``, that will |
| 91 | +be filled in. Before creating and calling our plugin, we now need to specify |
| 92 | +these parameters:: |
| 93 | + |
| 94 | + params = watts.Parameters() |
| 95 | + params['radius'] = 6.0 |
| 96 | + params['cycles'] = 200 |
| 97 | + |
| 98 | +As before, we create an instance of :class:`~watts.PluginMCNP` but instead of |
| 99 | +calling it with no arguments, we pass it the :class:`~watts.Parameters` |
| 100 | +instance:: |
| 101 | + |
| 102 | + plugin_mcnp = watts.PluginMCNP("sphere_model") |
| 103 | + result = plugin_mcnp(params) |
| 104 | + |
| 105 | +If we wanted to run this model with a series of different radii, it's now as |
| 106 | +simple as changing the corresponding parameter and calling the plugin:: |
| 107 | + |
| 108 | + for r in [2.0, 4.0, 6.0, 8.0, 10.0]: |
| 109 | + params['radius'] = r |
| 110 | + result = plugin_mcnp(params) |
| 111 | + |
| 112 | +Results Database |
| 113 | +++++++++++++++++ |
| 114 | + |
| 115 | +Results are automatically added to a database and persist between invocations of |
| 116 | +Python. For the example above, we may want to look at the last five results to |
| 117 | +see how :math:`k_\text{eff}` varies with the radius. The |
| 118 | +:class:`~watts.Database` class provides a list-like object that contains all |
| 119 | +previously generated :class:`~watts.Results` objects: |
| 120 | + |
| 121 | +.. code-block:: pycon |
| 122 | +
|
| 123 | + >>> database = watts.Database() |
| 124 | + >>> database |
| 125 | + [<ResultsMCNP: 2022-06-01 13:21:44.713942>, |
| 126 | + <ResultsMCNP: 2022-06-01 13:23:12.410774>, |
| 127 | + <ResultsMCNP: 2022-06-02 07:46:05.463723>, |
| 128 | + <ResultsMCNP: 2022-06-02 07:46:10.996932>, |
| 129 | + <ResultsMCNP: 2022-06-02 07:46:17.487411>, |
| 130 | + <ResultsMCNP: 2022-06-02 07:46:24.964455>, |
| 131 | + <ResultsMCNP: 2022-06-02 07:46:33.426781>] |
| 132 | +
|
| 133 | +This enables us to easily look at the :math:`k_\text{eff}` value for the last |
| 134 | +five MCNP simulations: |
| 135 | + |
| 136 | +.. code-block:: pycon |
| 137 | +
|
| 138 | + >>> [result.keff for result in database[-5:]] |
| 139 | + [0.3523+/-0.00021, |
| 140 | + 0.68017+/-0.00042, |
| 141 | + 0.97663+/-0.00063, |
| 142 | + 1.24086+/-0.00075, |
| 143 | + 1.47152+/-0.00081] |
0 commit comments