utilities#

Exceptions:

`BrokenObjectLinkError`(parent_type, ...)	Raised when the referenced object does not exist in the input file.
`IllegalState`(message)	Raised when an object can't be printed out due to an illegal state.
`LineExpansionWarning`	Warning for when a field or line expands that may damage user formatting.
`LineOverRunWarning`	Raised when non-comment inputs exceed the allowed line length in an input.
`MalformedInputError`(input, message)	Raised when there is an error with the MCNP input not related to the parser.
`MalformedInputWarning`	Raised when there is a possible, but not fatal error with the MCNP input not related to the parser.
`NumberConflictError`(message)	Raised when there is a conflict in number spaces
`ParsingError`(input, message, error_queue)	Raised when there is an error parsing the MCNP input at the SLY parsing layer.
`ParticleTypeNotInCell`(message)	Raised when data for importance data for a particle in the problem is not provided for a cell.
`ParticleTypeNotInProblem`(message)	Raised when data, such as cell importance or tally type, are set for a particle type not in the problem's mode.
`ParticleTypeWarning`(message)	Base class for incongruencies between particle types in problem mode, cell importances, and tallies
`RedundantParameterSpecification`(key, new_value)	Raised when multiple conflicting parameters are given.
`SurfaceConstantsWarning`(message)	Raised when the constants of a Surface are non-conform, but do not raise an error with MCNP.
`UndefinedBlock`	Raised when additional blocks exist after the default data block.
`UnknownElement`(missing_val)	Raised when an undefined element is used.
`UnsupportedFeature`(message[, input, error_queue])	Raised when MCNP syntax that is not supported is found

Functions:

`add_line_number_to_exception`(error, broken_robot)	Adds additional context to an Exception raised by an `MCNP_Object`.
`args_checked`(func)	A function decorator that enforces type annotations for the function when ran.
`fortran_float`(number_string)	Attempts to convert a FORTRAN formatted float string to a float.
`is_comment`(line)	Determines if the line is a `C comment` style comment.
`make_prop_pointer`(hidden_param[, types, ...])	A decorator function that makes a property based off of a pointer to another object.
`make_prop_val_node`(hidden_param[, types, ...])	A decorator function for making a property from a ValueNode.
`needs_full_ast`(func)	Marks a function as needed having the abstract syntax tree.
`needs_full_cst`(func)	Marks a function as needed having the concrete syntax tree.
`prop_pointer_collect_from_problem`(...[, ...])	Marks a function, and turns it into a property that is an object pointer to a collection (`make_prop_pointer()`), which can be pulled from the problem automatically.
`prop_pointer_from_problem`(hidden_param, ...)	Marks a function, and turns it into a property that is an object pointer (`make_prop_pointer()`), which can be pulled from the problem automatically.

exception montepy.utilities.BrokenObjectLinkError(parent_type, parent_number, child_type, child_number)#

Bases: MalformedInputError

Raised when the referenced object does not exist in the input file.

Methods:

`add_note`	Exception.add_note(note) -- add a note to the exception
`with_traceback`	Exception.with_traceback(tb) -- set self.__traceback__ to tb and return self.

Attributes:

args

add_note()#: Exception.add_note(note) – add a note to the exception

with_traceback()#: Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

args#

exception montepy.utilities.IllegalState(message)#

Bases: ValueError

Raised when an object can’t be printed out due to an illegal state.

Methods:

`add_note`	Exception.add_note(note) -- add a note to the exception
`with_traceback`	Exception.with_traceback(tb) -- set self.__traceback__ to tb and return self.

Attributes:

args

add_note()#: Exception.add_note(note) – add a note to the exception

with_traceback()#: Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

args#

exception montepy.utilities.LineExpansionWarning#

Bases: Warning

Warning for when a field or line expands that may damage user formatting.

Methods:

`add_note`	Exception.add_note(note) -- add a note to the exception
`with_traceback`	Exception.with_traceback(tb) -- set self.__traceback__ to tb and return self.

Attributes:

args

add_note()#: Exception.add_note(note) – add a note to the exception

with_traceback()#: Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

args#

exception montepy.utilities.LineOverRunWarning#

Bases: UserWarning

Raised when non-comment inputs exceed the allowed line length in an input.

Methods:

`add_note`	Exception.add_note(note) -- add a note to the exception
`with_traceback`	Exception.with_traceback(tb) -- set self.__traceback__ to tb and return self.

Attributes:

args

add_note()#: Exception.add_note(note) – add a note to the exception

with_traceback()#: Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

args#

exception montepy.utilities.MalformedInputError(input, message)#

Bases: ValueError

Raised when there is an error with the MCNP input not related to the parser.

Methods:

`add_note`	Exception.add_note(note) -- add a note to the exception
`with_traceback`	Exception.with_traceback(tb) -- set self.__traceback__ to tb and return self.

Attributes:

args

add_note()#: Exception.add_note(note) – add a note to the exception

with_traceback()#: Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

args#

exception montepy.utilities.MalformedInputWarning#

Bases: UserWarning

Raised when there is a possible, but not fatal error with the MCNP input not related to the parser.

Methods:

`add_note`	Exception.add_note(note) -- add a note to the exception
`with_traceback`	Exception.with_traceback(tb) -- set self.__traceback__ to tb and return self.

Attributes:

args

add_note()#: Exception.add_note(note) – add a note to the exception

with_traceback()#: Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

args#

exception montepy.utilities.NumberConflictError(message)#

Bases: Exception

Raised when there is a conflict in number spaces

Methods:

`add_note`	Exception.add_note(note) -- add a note to the exception
`with_traceback`	Exception.with_traceback(tb) -- set self.__traceback__ to tb and return self.

Attributes:

args

add_note()#: Exception.add_note(note) – add a note to the exception

with_traceback()#: Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

args#

exception montepy.utilities.ParsingError(input, message, error_queue)#

Bases: MalformedInputError

Raised when there is an error parsing the MCNP input at the SLY parsing layer.

Methods:

`add_note`	Exception.add_note(note) -- add a note to the exception
`with_traceback`	Exception.with_traceback(tb) -- set self.__traceback__ to tb and return self.

Attributes:

args

add_note()#: Exception.add_note(note) – add a note to the exception

with_traceback()#: Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

args#

exception montepy.utilities.ParticleTypeNotInCell(message)#

Bases: ParticleTypeWarning

Raised when data for importance data for a particle in the problem is not provided for a cell.

Methods:

`add_note`	Exception.add_note(note) -- add a note to the exception
`with_traceback`	Exception.with_traceback(tb) -- set self.__traceback__ to tb and return self.

Attributes:

args

add_note()#: Exception.add_note(note) – add a note to the exception

with_traceback()#: Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

args#

exception montepy.utilities.ParticleTypeNotInProblem(message)#

Bases: ParticleTypeWarning

Raised when data, such as cell importance or tally type, are set for a particle type not in the problem’s mode.

Methods:

`add_note`	Exception.add_note(note) -- add a note to the exception
`with_traceback`	Exception.with_traceback(tb) -- set self.__traceback__ to tb and return self.

Attributes:

args

add_note()#: Exception.add_note(note) – add a note to the exception

with_traceback()#: Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

args#

exception montepy.utilities.ParticleTypeWarning(message)#

Bases: Warning

Base class for incongruencies between particle types in problem mode, cell importances, and tallies

Methods:

`add_note`	Exception.add_note(note) -- add a note to the exception
`with_traceback`	Exception.with_traceback(tb) -- set self.__traceback__ to tb and return self.

Attributes:

args

add_note()#: Exception.add_note(note) – add a note to the exception

with_traceback()#: Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

args#

exception montepy.utilities.RedundantParameterSpecification(key, new_value)#

Bases: ValueError

Raised when multiple conflicting parameters are given.

e.g., 1 0 -1 imp:n=5 imp:n=0

Methods:

`add_note`	Exception.add_note(note) -- add a note to the exception
`with_traceback`	Exception.with_traceback(tb) -- set self.__traceback__ to tb and return self.

Attributes:

args

add_note()#: Exception.add_note(note) – add a note to the exception

with_traceback()#: Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

args#

exception montepy.utilities.SurfaceConstantsWarning(message)#

Bases: UserWarning

Raised when the constants of a Surface are non-conform, but do not raise an error with MCNP.

Methods:

`add_note`	Exception.add_note(note) -- add a note to the exception
`with_traceback`	Exception.with_traceback(tb) -- set self.__traceback__ to tb and return self.

Attributes:

args

add_note()#: Exception.add_note(note) – add a note to the exception

with_traceback()#: Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

args#

exception montepy.utilities.UndefinedBlock#

Bases: UserWarning

Raised when additional blocks exist after the default data block.

Methods:

`add_note`	Exception.add_note(note) -- add a note to the exception
`with_traceback`	Exception.with_traceback(tb) -- set self.__traceback__ to tb and return self.

Attributes:

args

add_note()#: Exception.add_note(note) – add a note to the exception

with_traceback()#: Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

args#

exception montepy.utilities.UnknownElement(missing_val)#

Bases: ValueError

Raised when an undefined element is used.

Methods:

`add_note`	Exception.add_note(note) -- add a note to the exception
`with_traceback`	Exception.with_traceback(tb) -- set self.__traceback__ to tb and return self.

Attributes:

args

add_note()#: Exception.add_note(note) – add a note to the exception

with_traceback()#: Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

args#

exception montepy.utilities.UnsupportedFeature(message, input=None, error_queue=None)#

Bases: ParsingError

Raised when MCNP syntax that is not supported is found

Methods:

`add_note`	Exception.add_note(note) -- add a note to the exception
`with_traceback`	Exception.with_traceback(tb) -- set self.__traceback__ to tb and return self.

Attributes:

args

add_note()#: Exception.add_note(note) – add a note to the exception

with_traceback()#: Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

args#

montepy.utilities.add_line_number_to_exception(error, broken_robot)#

Adds additional context to an Exception raised by an MCNP_Object.

This will add the line, file name, and the input lines to the error.

Parameters:

error (Exception) – The error that was raised.
broken_robot (MCNP_Object) – The parent object that had the error raised.

Raises:

Exception – … that’s the whole point.

montepy.utilities.args_checked(func: Callable)#

A function decorator that enforces type annotations for the function when ran.

This will read the type annotations for all arguments and enforce that the argument is of that type at run-time. Value restrictions can also be applied as well with typing.Annotated.

Examples

This will ensure that all arguments have to be an integer,

>>> from montepy.utilities import *
>>> import montepy.types as ty
>>>
>>> @args_checked
... def foo(a: int) -> int:
...    return a
>>> print(foo(1))
1
>>> print(foo("a"))
Traceback (most recent call last):
...
TypeError: Unable to set "a" for "foo" to "a" which is not of type "int"

Values can be checked as by using typing.Annotated to add an annotation of the values that are allowed (via a special value checking function),

>>> import typing
>>> import montepy.types as ty
>>>
>>> @args_checked
... def bar(a: typing.Annotated[int, ty.positive]) -> int:
...     return a
>>> print(bar(1))
1
>>> print(bar(0))
Traceback (most recent call last):
...
ValueError: Unable to set "a" for "bar" to "0" since it is less than or equal to "0"

Parameters:

func (Callable) – The function to decorate

Returns:

A decorated function that will do type and value checking at run time based on the annotation.

Return type:

Callable

Raises:

TypeError – If an argument of the wrong type is provided
ValueError – If an argument of the right type, but wrong value is given.

montepy.utilities.fortran_float(number_string: str | Real)#

Attempts to convert a FORTRAN formatted float string to a float.

FORTRAN allows silly things for scientific notation like 6.02+23 to represent Avogadro’s Number.

Parameters:: number_string (str | Real) – the string that will be converted to a float
Raises:: ValueError – If the string can not be parsed as a float.
Returns:: the parsed float of the this string
Return type:: float

montepy.utilities.is_comment(line: str)#

Determines if the line is a C comment style comment.

Parameters:: line (str) – the line to analyze
Returns:: True if the line is a comment
Return type:: bool

montepy.utilities.make_prop_pointer(hidden_param, types=None, base_type=None, validator=None, deletable=False)#

A decorator function that makes a property based off of a pointer to another object.

Note this can also be used for almost any circumstance as everything in python is a pointer.

Parameters:

hidden_param (str) – The string representing the parameter name of the internally stored ValueNode.
types (type, tuple) – the acceptable types for the settable, which is passed to isinstance, if an empty tuple is provided the type will be self.
validator (collections.abc.Callable) – A validator function to run on values before setting. Must accept func(self, value).
deletable (bool) – If true make this property deletable. When deleted the value will be set to None.

montepy.utilities.make_prop_val_node(hidden_param, types=None, base_type=None, validator=None, deletable=False)#

A decorator function for making a property from a ValueNode.

This decorator is meant to handle all boiler plate. It will get and set the value property of the underlying ValueNode. By default the property is not settable unless types is set.

Parameters:

hidden_param (str) – The string representing the parameter name of the internally stored ValueNode.
types (type, tuple) – the acceptable types for the settable, which is passed to isinstance. If an empty tuple will be type(self).
validator (collections.abc.Callable) – A validator function to run on values before setting. Must accept func(self, value).
deletable (bool) – If true make this property deletable. When deleted the value will be set to None.

montepy.utilities.needs_full_ast(func)#

Marks a function as needed having the abstract syntax tree.

Calling a marked function will lead to a full (abstract) parse.

montepy.utilities.needs_full_cst(func)#

Marks a function as needed having the concrete syntax tree.

Calling a marked function will lead to a full parse.

montepy.utilities.prop_pointer_collect_from_problem(hidden_param: str, ids_param: str, prob_collection_param: str, collect_type: type, types: tuple[type] = None, base_type: type = None, validator: Callable = None, deletable: bool = False)#

Marks a function, and turns it into a property that is an object pointer to a collection (make_prop_pointer()), which can be pulled from the problem automatically.

When this property is not populated, and a problem is linked, the object is fetched from the problem. This differs from prop_pointer_from_problem() because this stores multiple objects.

Parameters:

hidden_param (str) – the _private attribute where the object is stored.
id_param (str) – the parameter of the ID number for the object to pull.
prob_collection_param (str) – the parameter of the problem of the collection, from which to grab this object from.
types (tuple[type]) – the allowed types for making this property settable.
base_type (type) – the type to coerce all other types to.
validator (Callable) – A function to call on setting for additional validation
deletable (bool) – Whether deletion should be allowed.
ids_param (str)
collect_type (type)

Raises:

BrokenObjectLinkError – When the object can not be found.

montepy.utilities.prop_pointer_from_problem(hidden_param: str, id_param: str, prob_collection_param: str, types: tuple[type] = None, base_type: type = None, validator: Callable = None, deletable: bool = False)#

Marks a function, and turns it into a property that is an object pointer (make_prop_pointer()), which can be pulled from the problem automatically.

When this property is not populated, and a problem is linked, the object is fetched from the problem.

Parameters:

hidden_param (str) – the _private attribute where the object is stored.
id_param (str) – the parameter of the ID number for the object to pull.
prob_collection_param (str) – the parameter of the problem of the collection, from which to grab this object from.
types (tuple[type]) – the allowed types for making this property settable.
base_type (type) – the type to coerce all other types to.
validator (Callable) – A function to call on setting for additional validation
deletable (bool) – Whether deletion should be allowed.

Raises:

BrokenObjectLinkError – When the object can not be found.