Merge pull request #38 from fusion-energy/develop

general updates
fusion-energy · Nov 17, 2021 · 5aeacb7 · 5aeacb7
2 parents 1520c35 + 2444931
commit 5aeacb7
Show file tree

Hide file tree

Showing 18 changed files with 604 additions and 164 deletions.
diff --git a/README.md b/README.md
@@ -11,7 +11,11 @@ pip install openmc_tally_unit_converter
 
 OpenMC tally results are save into a statepoint h5 file without units.
 
-This package ascertains the base units of common tallies by inspecting their tally filters and scores.
+This package ascertains the base units of common tallies by inspecting their
+tally filters and scores.
+
+The following worked example is for a heating tally. Flux, effective dose and
+DPA / damage-energy tallies are also supported.
 
 ```python
 import openmc_tally_unit_converter as otuc
@@ -24,25 +28,49 @@ my_tally = statepoint.get_tally(name="my_cell_heating_tally")
 # gets the base units of the tally
 tally = otuc.process_tally(tally=my_tally)
 print(tally)
->>> eV per source_particle
+>>> 218559.22320927 electron_volt / source_particle
 ```
 
 The package then allows users to scale the base tally units to different units. For example the package can easily convert cm to meters or electron volts to joules.
 
 ```python
 converted_tally = otuc.process_tally(
     tally=my_tally,
-    required_units = Joules / source_particle
+    required_units = "joules / source_particle"
 )
 
 print(converted_tally)
->>> 2.4e-12 Joules per source_particle
+>>> 3.50170481e-14 Joules / source_particle
 ```
 
-Additional inputs can be applied to normalize the the tallies and convert the units further:
+Additional inputs can be applied to normalize the the tallies and convert the
+units further:
+
+- The source strength of the source in particles per second can be specified with the ```strength_strength``` argument. This allows the tally results to be converted from the units of score per simulated particle to score per unit time (e.g seconds, hours, days etc).
 
-- The source strength of the source in particles per second can be specified with the ```strength_strength``` argument. This allows the tally results to be converted from the units of score per simulated particle to score per second.
+```python
+converted_tally = otuc.process_tally(
+    tally=my_tally,
+    source_strength=1e20,  # input units for this argument are particles per second
+    required_units = "joules / minute"
+)
+
+print(converted_tally)
+>>> 2.10102288e+08 joules / source_particle
+```
 
 - The volume of the cell in cm3 can also be specified with the ```volume``` argument. This allows the tally result to be converted from the base units to base units per unit volume.
 
+```python
+converted_tally = otuc.process_tally(
+    tally=my_tally,
+    source_strength=13458.3,  # input units for this argument are particles per second
+    volume=12,  # input units are in cm3
+    required_units = "joules / second / meter **3"
+)
+
+print(converted_tally)
+>>> 3.92724948e-05 Joules / meter ** 3 / second
+```
+
 :point_right: [Further examples](https://github.com/fusion-energy/openmc_tally_unit_converter/tree/main/examples)
diff --git a/examples/example_from_readme.ipynb b/examples/example_from_readme.ipynb
@@ -0,0 +1,296 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "75f5112e-c00d-4204-b620-1fb5135b2c94",
+   "metadata": {},
+   "source": []
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "a52c0a27-9dfb-4bcf-9620-9a4df61da1c3",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import openmc_tally_unit_converter as otuc\n",
+    "import openmc"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "529479a1-598b-454f-9fed-102e39194cf1",
+   "metadata": {},
+   "source": []
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "id": "b1934d79-befd-4c38-b693-725f5c09d6eb",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "{1: Tally\n",
+       " \tID             =\t1\n",
+       " \tName           =\t2_flux\n",
+       " \tFilters        =\tCellFilter\n",
+       " \tNuclides       =\ttotal\n",
+       " \tScores         =\t['flux']\n",
+       " \tEstimator      =\ttracklength,\n",
+       " 2: Tally\n",
+       " \tID             =\t2\n",
+       " \tName           =\t2_neutron_spectra\n",
+       " \tFilters        =\tParticleFilter, EnergyFilter, CellFilter\n",
+       " \tNuclides       =\ttotal\n",
+       " \tScores         =\t['flux']\n",
+       " \tEstimator      =\ttracklength,\n",
+       " 3: Tally\n",
+       " \tID             =\t3\n",
+       " \tName           =\t2_TBR\n",
+       " \tFilters        =\tCellFilter\n",
+       " \tNuclides       =\ttotal\n",
+       " \tScores         =\t['(n,Xt)']\n",
+       " \tEstimator      =\ttracklength,\n",
+       " 4: Tally\n",
+       " \tID             =\t4\n",
+       " \tName           =\t2_heating\n",
+       " \tFilters        =\tCellFilter\n",
+       " \tNuclides       =\ttotal\n",
+       " \tScores         =\t['heating']\n",
+       " \tEstimator      =\ttracklength,\n",
+       " 5: Tally\n",
+       " \tID             =\t5\n",
+       " \tName           =\t2_neutron_effective_dose\n",
+       " \tFilters        =\tParticleFilter, EnergyFunctionFilter, CellFilter\n",
+       " \tNuclides       =\ttotal\n",
+       " \tScores         =\t['flux']\n",
+       " \tEstimator      =\ttracklength,\n",
+       " 6: Tally\n",
+       " \tID             =\t6\n",
+       " \tName           =\t2_photon_effective_dose\n",
+       " \tFilters        =\tParticleFilter, EnergyFunctionFilter, CellFilter\n",
+       " \tNuclides       =\ttotal\n",
+       " \tScores         =\t['flux']\n",
+       " \tEstimator      =\ttracklength,\n",
+       " 7: Tally\n",
+       " \tID             =\t7\n",
+       " \tName           =\t2_neutron_fast_flux\n",
+       " \tFilters        =\tParticleFilter, EnergyFilter, CellFilter\n",
+       " \tNuclides       =\ttotal\n",
+       " \tScores         =\t['flux']\n",
+       " \tEstimator      =\ttracklength,\n",
+       " 8: Tally\n",
+       " \tID             =\t8\n",
+       " \tName           =\t2_photon_fast_flux\n",
+       " \tFilters        =\tParticleFilter, EnergyFilter, CellFilter\n",
+       " \tNuclides       =\ttotal\n",
+       " \tScores         =\t['flux']\n",
+       " \tEstimator      =\ttracklength,\n",
+       " 9: Tally\n",
+       " \tID             =\t9\n",
+       " \tName           =\t2_neutron_spectra\n",
+       " \tFilters        =\tParticleFilter, EnergyFilter, CellFilter\n",
+       " \tNuclides       =\ttotal\n",
+       " \tScores         =\t['flux']\n",
+       " \tEstimator      =\ttracklength,\n",
+       " 10: Tally\n",
+       " \tID             =\t10\n",
+       " \tName           =\t2_neutron_spectra\n",
+       " \tFilters        =\tParticleFilter, EnergyFilter, CellFilter\n",
+       " \tNuclides       =\ttotal\n",
+       " \tScores         =\t['flux']\n",
+       " \tEstimator      =\ttracklength,\n",
+       " 11: Tally\n",
+       " \tID             =\t11\n",
+       " \tName           =\t3_neutron_spectra\n",
+       " \tFilters        =\tParticleFilter, EnergyFilter, CellFilter\n",
+       " \tNuclides       =\ttotal\n",
+       " \tScores         =\t['flux']\n",
+       " \tEstimator      =\ttracklength,\n",
+       " 12: Tally\n",
+       " \tID             =\t12\n",
+       " \tName           =\t2_photon_spectra\n",
+       " \tFilters        =\tParticleFilter, EnergyFilter, CellFilter\n",
+       " \tNuclides       =\ttotal\n",
+       " \tScores         =\t['flux']\n",
+       " \tEstimator      =\ttracklength,\n",
+       " 13: Tally\n",
+       " \tID             =\t13\n",
+       " \tName           =\t2_(n,total)\n",
+       " \tFilters        =\tCellFilter\n",
+       " \tNuclides       =\ttotal\n",
+       " \tScores         =\t['total']\n",
+       " \tEstimator      =\ttracklength,\n",
+       " 14: Tally\n",
+       " \tID             =\t14\n",
+       " \tName           =\t2_damage-energy\n",
+       " \tFilters        =\tCellFilter\n",
+       " \tNuclides       =\ttotal\n",
+       " \tScores         =\t['damage-energy']\n",
+       " \tEstimator      =\ttracklength,\n",
+       " 15: Tally\n",
+       " \tID             =\t15\n",
+       " \tName           =\tneutron_effective_dose_on_2D_mesh_xy\n",
+       " \tFilters        =\tParticleFilter, EnergyFunctionFilter, MeshFilter\n",
+       " \tNuclides       =\ttotal\n",
+       " \tScores         =\t['flux']\n",
+       " \tEstimator      =\ttracklength,\n",
+       " 16: Tally\n",
+       " \tID             =\t16\n",
+       " \tName           =\tneutron_effective_dose_on_3D_mesh\n",
+       " \tFilters        =\tParticleFilter, EnergyFunctionFilter, MeshFilter\n",
+       " \tNuclides       =\ttotal\n",
+       " \tScores         =\t['flux']\n",
+       " \tEstimator      =\ttracklength,\n",
+       " 17: Tally\n",
+       " \tID             =\t17\n",
+       " \tName           =\theating_on_2D_mesh_xy\n",
+       " \tFilters        =\tMeshFilter\n",
+       " \tNuclides       =\ttotal\n",
+       " \tScores         =\t['heating']\n",
+       " \tEstimator      =\ttracklength,\n",
+       " 18: Tally\n",
+       " \tID             =\t18\n",
+       " \tName           =\theating_on_3D_mesh\n",
+       " \tFilters        =\tMeshFilter\n",
+       " \tNuclides       =\ttotal\n",
+       " \tScores         =\t['heating']\n",
+       " \tEstimator      =\ttracklength}"
+      ]
+     },
+     "execution_count": 3,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "statepoint = openmc.StatePoint(filepath=\"statepoint.2.h5\")\n",
+    "statepoint.tallies"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "74f0a45c-b104-4341-a22a-898a9447e83e",
+   "metadata": {},
+   "source": []
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "8105aaca-2571-4259-90b6-d3379ed89fcb",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "my_tally = statepoint.get_tally(name=\"2_heating\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "738a890b-a0ae-4f87-8546-195973918e25",
+   "metadata": {},
+   "source": []
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "57d63abe-329d-4bc4-903d-3c123b98fee3",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "tally = otuc.process_tally(\n",
+    "    tally=my_tally,\n",
+    "    # required_units='eV / source_particle'\n",
+    ")\n",
+    "print(tally)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "18fe4d99-8dd6-4fae-be50-f7a39653d4f5",
+   "metadata": {},
+   "source": []
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "78144320-72aa-4bac-b293-063afe44692e",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "converted_tally = otuc.process_tally(\n",
+    "    tally=my_tally,\n",
+    "    required_units = \"joules / source_particle\"\n",
+    ")\n",
+    "\n",
+    "print(converted_tally)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "ba340dcc-ad73-4594-bc47-d186ff3723e2",
+   "metadata": {},
+   "source": []
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "060131bb-2c02-4fad-bdf9-2efabd05a988",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "converted_tally = otuc.process_tally(\n",
+    "    tally=my_tally,\n",
+    "    source_strength=1e20,  # input units for this argument are particles per second\n",
+    "    required_units = \"joules / minute\"\n",
+    ")\n",
+    "\n",
+    "print(converted_tally)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "12c72c7c-e255-4565-92a9-825c468ca716",
+   "metadata": {},
+   "source": []
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "36846a7b-af7a-4e6b-bb4e-58017f80ecee",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "converted_tally = otuc.process_tally(\n",
+    "    tally=my_tally,\n",
+    "    source_strength=13458.3,  # input units for this argument are particles per second\n",
+    "    volume=12,  # input units are in cm3\n",
+    "    required_units = \"joules / second / meter **3\"\n",
+    ")\n",
+    "converted_tally"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.8.12"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}
diff --git a/examples/processing_2d_mesh_effective_dose_tally.py b/examples/processing_2d_mesh_effective_dose_tally.py
@@ -17,7 +17,7 @@
 
 # scaled from picosievert to sievert
 tally_result, std_dev_result = otuc.process_dose_tally(
-    tally=my_tally, required_units="sievert / simulated_particle"
+    tally=my_tally, required_units="sievert / source_particle"
 )
 # the tally result with required units
 print(f"converted mesh tally results {tally_result}")
diff --git a/examples/processing_cell_damage-energy_tally.py b/examples/processing_cell_damage-energy_tally.py
@@ -10,15 +10,15 @@
 
 # returns the tally with base units
 result = otuc.process_damage_energy_tally(
-    tally=my_tally, required_units="eV / simulated_particle"
+    tally=my_tally, required_units="eV / source_particle"
 )
 print(f"damage-energy base units = {result}", end="\n\n")
 
 
 # returns the tally with scalled based units (MeV instead of eV)
 result, std_dev = otuc.process_damage_energy_tally(
     tally=my_tally,
-    required_units="MeV / simulated_particle"
+    required_units="MeV / source_particle"
     # required_units="displacements per atoms"
 )
 print(f"damage-energy scaled base units = {result}", end="\n\n")