Create an ab initio parse method to quickly make new objects from an MCNP string.

doc/source/changelog.rst

@@ -2,8 +2,8 @@
 MontePy Changelog
 *****************
 
-1.0.0 releases
-==============
+1.0 releases
+============
 
 #Next Version#
 --------------
@@ -20,8 +20,11 @@ MontePy Changelog
 * Made ``Material.is_atom_fraction`` settable (:issue:`511`). 
 * Made NumberedObjectCollections act like a set (:issue:`138`).
 * Automatically added children objects, e.g., the surfaces in a cell, to the problem when the cell is added to the problem (:issue:`63`).
+* Added ability to parse all MCNP objects from a string (:issue:`88`).
+* Added function: :func:`~montepy.mcnp_problem.MCNP_Problem.parse` to parse arbitrary MCNP object (:issue:`88`).
 * An error is now raised when typos in object attributes are used, e.g., ``cell.nubmer`` (:issue:`508`).
 
+
 **Bugs Fixed**
 
 * Made it so that a material created from scratch can be written to file (:issue:`512`).

doc/source/starting.rst

@@ -273,8 +273,7 @@ The ``NumberedObjectCollection`` has various mechanisms internally to avoid numb
 
         import montepy
         prob = montepy.read_input("tests/inputs/test.imcnp")
-        cell = montepy.Cell()
-        cell.number = 2
+        cell = montepy.Cell(number = 2)
         prob.cells.append(cell)
 
 .. testoutput::
@@ -340,21 +339,23 @@ Using the generators in this way does not cause any issues, but there are ways t
 by making "stale" information.
 This can be done by making a copy of it with ``list()``. 
 
->>> for num in problem.cells.numbers:
-...   print(num)
-1
-2
-3
-99
-5
->>> numbers = list(problem.cells.numbers)
->>> numbers
-[1, 2, 3, 99, 5]
->>> problem.cells[1].number = 1000
->>> 1000 in problem.cells.numbers
-True
->>> 1000 in numbers
-False
+.. doctest::
+
+        >>> for num in problem.cells.numbers:
+        ...   print(num)
+        1
+        2
+        3
+        99
+        5
+        >>> numbers = list(problem.cells.numbers)
+        >>> numbers
+        [1, 2, 3, 99, 5]
+        >>> problem.cells[1].number = 1000
+        >>> 1000 in problem.cells.numbers
+        True
+        >>> 1000 in numbers
+        False
 
 Oh no! When we made a list of the numbers we broke the link, and the new list won't update when the numbers of the cells change, 
 and you can cause issues this way.
@@ -370,6 +371,69 @@ If a ``Cell`` or a group of ``Cells`` are cloned their numbers will be to change
 However, if a whole :class:`~montepy.mcnp_problem.MCNP_Problem` is cloned these objects will not have their numbers changed.
 For an example for how to clone a numbered object see :ref:`Cloning a Cell`.
 
+Creating Objects from a String
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Sometimes its more convenient to create an MCNP object from its input string for MCNP, rather than setting a lot of properties,
+or the object you need isn't supported by MontePy yet.
+In this case there are a few ways to generate this object.
+First all :class:`~montepy.mcnp_object.MCNP_Object` constructors can take a string:
+
+.. doctest::
+
+   >>> cell = montepy.Cell("1 0 -2 imp:n=1")
+   >>> cell.number
+   1
+   >>> cell.importance[montepy.Particle.NEUTRON]
+   1.0
+   >>> # surfaces
+   >>> surf = montepy.AxisPlane("5 PZ 10")
+   >>> surf.number 
+   5
+   >>> surf.location
+   10.0
+   >>> # materials
+   >>> mat = montepy.Material("M1 1001.80c 2 8016.80c 1")
+   >>> mat.number
+   1
+   >>> thermal_scat = montepy.ThermalScatteringLaw("MT1 lwrt.40t")
+   >>> thermal_scat.old_number
+   1
+   >>> #object linking hasn't occuring
+   >>> print(thermal_scat.parent_material)
+   None
+
+For data inputs and surfaces there are some helper functions that help parse all objects of that type,
+and return the appropriate object.
+For surfaces this is: :func:`~montepy.surfaces.surface_builder.parse_surface`,
+and for data inputs this is :func:`~montepy.data_inputs.data_parser.parse_data`.
+
+.. doctest::
+   >>> surf = montepy.parse_surface("1 cz 5.0")
+   >>> type(surf)
+   foo
+   >>> surf.radius
+   5.0
+   >>> mat = montepy.parse_data("m1 1001.80c 1")
+   >>> type(mat)
+   foo
+
+
+This object is still unlinked from other objects, and won't be kept with a problem.
+So there is also :func:`~montepy.mcnp_problem.MCNP_Problem.parse`. 
+This takes a string, and then creates the MCNP object,
+links it to the problem,
+links it to its other objects (e.g., surfaces, materials, etc.),
+and appends it to necessary collections (if requested):
+
+.. testcode::
+
+   cell = problem.parse("123 0 -1005")
+   assert cell in problem.cells
+   assert cell.surfaces[1005] is problem.surfaces[1005]
+   cell = problem.parse("124 0 -1005", append=False)
+   assert cell not in problem.cells
+
 Surfaces
 --------
 
@@ -596,24 +660,18 @@ Order of precedence and grouping is automatically handled by Python so you can e
 .. testcode::
 
    # build blank surfaces 
-   bottom_plane = montepy.AxisPlane()
+   bottom_plane = montepy.AxisPlane(number=1)
    bottom_plane.location = 0.0
-   top_plane = montepy.AxisPlane()
+   top_plane = montepy.AxisPlane(number=2)
    top_plane.location = 10.0
-   fuel_cylinder = montepy.CylinderOnAxis()
+   fuel_cylinder = montepy.CylinderOnAxis(number=3)
    fuel_cylinder.radius = 1.26 / 2
-   clad_cylinder = montepy.CylinderOnAxis()
+   clad_cylinder = montepy.CylinderOnAxis( number=4)
    clad_cylinder.radius = (1.26 / 2) + 1e-3 # fuel, gap, cladding
-   clad_od = montepy.surfaces.CylinderOnAxis()
+   clad_od = montepy.CylinderOnAxis(number=5)
    clad_od.radius = clad_cylinder.radius + 0.1 # add thickness
-   other_fuel = montepy.surfaces.CylinderOnAxis()
+   other_fuel = montepy.CylinderOnAxis(number=6)
    other_fuel.radius = 3.0
-   other_fuel.number = 10
-   bottom_plane.number = 1
-   top_plane.number = 2
-   fuel_cylinder.number = 3
-   clad_cylinder.number = 4
-   clad_od.number = 5
 
    #make weird truncated fuel sample
    slug_half_space = +bottom_plane & -top_plane & -fuel_cylinder
@@ -808,8 +866,7 @@ You can also easy apply a transform to the filling universe with:
 .. testcode::
 
    import numpy as np
-   transform = montepy.data_inputs.transform.Transform()
-   transform.number = 5
+   transform = montepy.data_inputs.transform.Transform(number=5)
    transform.displacement_vector = np.array([1, 2, 0])
    cell.fill.transform = transform
 

montepy/__init__.py

@@ -7,6 +7,7 @@
 You will receive an MCNP_Problem object that you will interact with.
 """
 
+from . import data_inputs
 from . import input_parser
 from . import constants
 import importlib.metadata
@@ -17,6 +18,8 @@
 from montepy.data_inputs.transform import Transform
 from montepy.data_inputs.nuclide import Library, Nuclide
 from montepy.data_inputs.element import Element
+from montepy.data_inputs.thermal_scattering import ThermalScatteringLaw
+from montepy.data_inputs.data_parser import parse_data
 
 # geometry
 from montepy.geometry_operators import Operator

montepy/cell.py

@@ -1,18 +1,19 @@
-# 2024, Battelle Energy Alliance, LLC All Rights Reserved.
+# Copyright 2024, Battelle Energy Alliance, LLC All Rights Reserved.
 from __future__ import annotations
-
 import copy
 import itertools
 import numbers
+from typing import Union
 
+import montepy
 from montepy.cells import Cells
 from montepy.constants import BLANK_SPACE_CONTINUE
 from montepy.data_inputs import importance, fill, lattice_input, universe_input, volume
 from montepy.data_inputs.data_parser import PREFIX_MATCHES
 from montepy.input_parser.cell_parser import CellParser
 from montepy.input_parser import syntax_node
 from montepy.errors import *
-from montepy.numbered_mcnp_object import Numbered_MCNP_Object
+from montepy.numbered_mcnp_object import Numbered_MCNP_Object, InitInput
 from montepy.data_inputs.material import Material
 from montepy.geometry_operators import Operator
 from montepy.surfaces.half_space import HalfSpace, UnitHalfSpace
@@ -64,15 +65,20 @@ class Cell(Numbered_MCNP_Object):
 
         complement = ~cell
 
-
     .. seealso::
 
             * :manual63sec:`5.2`
             * :manual62:`55`
 
-    :param input: the input for the cell definition
-    :type input: Input
+    .. versionchanged:: 1.0.0
+
+        Added number parameter
 
+
+    :param input: The Input syntax object this will wrap and parse.
+    :type input: Union[Input, str]
+    :param number: The number to set for this object.
+    :type number: int
     """
 
     _ALLOWED_KEYWORDS = {
@@ -105,7 +111,12 @@ class Cell(Numbered_MCNP_Object):
 
     _parser = CellParser()
 
-    def __init__(self, input: montepy.input_parser.mcnp_input.Input = None):
+    def __init__(
+        self,
+        input: InitInput = None,
+        number: int = None,
+    ):
+        self._BLOCK_TYPE = montepy.input_parser.block_type.BlockType.CELL
         self._CHILD_OBJ_MAP = {
             "material": Material,
             "surfaces": Surface,
@@ -119,10 +130,9 @@ def __init__(self, input: montepy.input_parser.mcnp_input.Input = None):
         self._density_node = self._generate_default_node(float, None)
         self._surfaces = Surfaces()
         self._complements = Cells()
-        self._number = self._generate_default_node(int, -1)
-        super().__init__(input, self._parser)
+        super().__init__(input, self._parser, number)
         if not input:
-            self._generate_default_tree()
+            self._generate_default_tree(number)
         self._old_number = copy.deepcopy(self._tree["cell_num"])
         self._number = self._tree["cell_num"]
         mat_tree = self._tree["material"]
@@ -371,9 +381,6 @@ def geometry(self):
         """
         The Geometry for this problem.
 
-        .. versionadded:: 0.2.0
-            Added with the new ability to represent true CSG geometry logic.
-
         The HalfSpace tree that is able to represent this cell's geometry.
         MontePy's geometry is based upon dividers, which includes both Surfaces, and cells.
         A half-space is created by choosing one side of the divider.
@@ -607,7 +614,7 @@ def _update_values(self):
         for input_class, (attr, _) in self._INPUTS_TO_PROPERTY.items():
             getattr(self, attr)._update_values()
 
-    def _generate_default_tree(self):
+    def _generate_default_tree(self, number: int = None):
         material = syntax_node.SyntaxNode(
             "material",
             {
@@ -619,7 +626,7 @@ def _generate_default_tree(self):
         self._tree = syntax_node.SyntaxNode(
             "cell",
             {
-                "cell_num": self._generate_default_node(int, None),
+                "cell_num": self._generate_default_node(int, number),
                 "material": material,
                 "geometry": None,
                 "parameters": syntax_node.ParametersNode(),

montepy/data_inputs/cell_modifier.py

@@ -1,7 +1,7 @@
 # Copyright 2024, Battelle Energy Alliance, LLC All Rights Reserved.
 from abc import abstractmethod
 import montepy
-from montepy.data_inputs.data_input import DataInputAbstract
+from montepy.data_inputs.data_input import DataInputAbstract, InitInput
 from montepy.input_parser import syntax_node
 from montepy.input_parser.block_type import BlockType
 from montepy.input_parser.mcnp_input import Input, Jump
@@ -15,7 +15,7 @@ class CellModifierInput(DataInputAbstract):
     Examples: IMP, VOL, etc.
 
     :param input: the Input object representing this data input
-    :type input: Input
+    :type input: Union[Input, str]
     :param in_cell_block: if this card came from the cell block of an input file.
     :type in_cell_block: bool
     :param key: the key from the key-value pair in a cell
@@ -24,7 +24,13 @@ class CellModifierInput(DataInputAbstract):
     :type value: SyntaxNode
     """
 
-    def __init__(self, input=None, in_cell_block=False, key=None, value=None):
+    def __init__(
+        self,
+        input: InitInput = None,
+        in_cell_block: bool = False,
+        key: str = None,
+        value: syntax_node.SyntaxNode = None,
+    ):
         fast_parse = False
         if key and value:
             input = Input([key], BlockType.DATA)
@@ -178,8 +184,6 @@ def _tree_value(self):
         """
         The ValueNode that holds the information for this instance, that should be included in the data block.
 
-        .. versionadded:: 0.2.0
-
         :returns: The ValueNode to update the data-block syntax tree with.
         :rtype: ValueNode
         """
@@ -191,8 +195,6 @@ def _collect_new_values(self):
 
         This will be a list in the same order as :func:`montepy.mcnp_problem.MCNP_Problem.cells`.
 
-        .. versionadded:: 0.2.0
-
         :returns: a list of the ValueNodes to update the data block syntax tree with
         :rtype: list
         """
@@ -207,8 +209,6 @@ def _collect_new_values(self):
     def _update_cell_values(self):
         """
         Updates values in the syntax tree when in the cell block.
-
-        .. versionadded:: 0.2.0
         """
         pass