From 22533092ca60ddb2e93da69bb6de22fdd9bb8034 Mon Sep 17 00:00:00 2001 From: BitterB0NG0 <93603537+BitterB0NG0@users.noreply.github.com> Date: Tue, 10 Sep 2024 01:46:21 -0700 Subject: [PATCH] Added ptrac Docstrings --- docs/source/pymcnp-ptrac.rst | 2 +- src/pymcnp/files/ptrac/header.py | 252 +++++++++++++++++++++--------- src/pymcnp/files/ptrac/history.py | 150 +++++++++++++++--- src/pymcnp/files/ptrac/ptrac.py | 48 +++++- 4 files changed, 349 insertions(+), 103 deletions(-) diff --git a/docs/source/pymcnp-ptrac.rst b/docs/source/pymcnp-ptrac.rst index 9274253..297b25e 100644 --- a/docs/source/pymcnp-ptrac.rst +++ b/docs/source/pymcnp-ptrac.rst @@ -1,5 +1,5 @@ pymcnp.ptrac Subpackage -========================== +======================= Event Card ---------- diff --git a/src/pymcnp/files/ptrac/header.py b/src/pymcnp/files/ptrac/header.py index 2729a97..045bd0b 100644 --- a/src/pymcnp/files/ptrac/header.py +++ b/src/pymcnp/files/ptrac/header.py @@ -1,40 +1,70 @@ """ -'header' +``header`` contains classes representing PTRAC headers. + +``header`` packages the ``Header`` class, providing an object-oriented, +importable interface for PTRAC headers. """ from __future__ import annotations from enum import Enum -from .._utils import parser -from .._utils import types - - -class PtracKeywords(Enum): - BUFFER = 1 - CELL = 2 - EVENT = 3 - FILE = 4 - FILTER = 5 - MAX = 6 - MENP = 7 - NPS = 8 - SURFACE = 9 - TALLY = 10 - TYPE = 11 - VALUE = 12 - WRITE = 13 - UNKNOWN = 14 +from ..utils import _parser +from ..utils import types class Header: """ - 'Header' + ``Header`` represents PTRAC headers. + + ``Header`` implements PTRAC headers as a Python class. Its attributes store + PTRAC header parameters, and its methods provide entry points and endpoints + for working with PTRAC. It represents the PTRAC header syntax element. + + Attributes: + code: Simulation name. + code_date: Simulation compilation date. + version: Simulation version. + run_date: Simulation run date. + run_time: Simulation run time. + title: Simulation title. + settings: PTRAC input format. + numbers: PTRAC event variable counts by type. + ids: PTRAC event variable identifiers by type. """ + class PtracKeywords(Enum): + """ + ``PtracKeywords`` represents PTRAC input format index keywords. + + ``PtracKeywords`` implements PTRAC input format index keywords as a + Python inner class. It enumerates input format index keywords. It + represents the PTRAC input format index keywords syntax element, so + ``Header`` depends on ``PtracKeywords`` as an enum. + + Notes: + ``PtracKeywords`` does not currently implement a ``from_mcnp` + method because ``Header`` does not currently require it. + """ + + BUFFER = 1 + CELL = 2 + EVENT = 3 + FILE = 4 + FILTER = 5 + MAX = 6 + MENP = 7 + NPS = 8 + SURFACE = 9 + TALLY = 10 + TYPE = 11 + VALUE = 12 + WRITE = 13 + UNKNOWN = 14 + def __init__(self): """ - '__init__' + ``__init__`` initializes ``Header``. """ self.code: str = None @@ -43,7 +73,7 @@ def __init__(self): self.run_date: str = None self.run_time: str = None self.title: str = None - self.settings: dict[PtracKeywords, list[float]] = { + self.settings: dict[self.PtracKeywords, list[float]] = { PtracKeywords.BUFFER: None, PtracKeywords.CELL: None, PtracKeywords.EVENT: None, @@ -64,84 +94,154 @@ def __init__(self): def set_code(self, code: str) -> None: """ - 'set_code' + ``set_code`` stores PTRAC header code variable. + + ``set_code`` checks given arguments before assigning the given value + to ``code.code``. If given an unrecognized argument, it raises + semantic errors. + + Parameters: + code: Simulation name. + + Raises: + MCNPSemanticError: INVALID_HEADER_CODE. """ if code is None: - raise ValueError + raise errors.MCNPSemanticError(errors.MCNPSemanticCodes.INVALID_HEADER_CODE) self.code = code def set_code_date(self, code_date: str) -> None: """ - 'set_code_date' + ``set_code_date`` stores PTRAC header code date variable. + + ``set_code_date`` checks given arguments before assigning the given value + to ``Header.code_date``. If given an unrecognized argument, it raises + semantic errors. + + Parameters: + code_date: Simulation compilation date. + + Raises: + MCNPSemanticError: INVALID_HEADER_CODEDATE. """ if code_date is None: - raise ValueError + raise errors.MCNPSemanticError(errors.MCNPSemanticCodes.INVALID_HEADER_CODEDATE) self.code_date = code_date def set_version(self, version: str) -> None: """ - 'set_version' + ``set_version`` stores PTRAC header version variable. + + set_version`` checks given arguments before assigning the given value + to ``Header.version``. If given an unrecognized argument, it raises + semantic errors. + + Parameters: + version: Simulation version. + + Raises: + MCNPSemanticError: INVALID_HEADER_VERSION. """ if version is None: - raise ValueError + raise errors.MCNPSemanticError(errors.MCNPSemanticCodes.INVALID_HEADER_VERSION) self.version = version def set_run_date(self, run_date: str) -> None: """ - 'set_run_date' + ``set_run_date`` stores PTRAC header run date variable. + + ``set_run_date`` checks given arguments before assigning the given value + to ``Header.run_date``. If given an unrecognized argument, it raises + semantic errors. + + Parameters: + run_date: Simulation run date. + + Raises: + MCNPSemanticError: INVALID_HEADER_RUNDATE. """ if run_date is None: - raise ValueError + raise errors.MCNPSemanticError(errors.MCNPSemanticCodes.INVALID_HEADER_RUNDATE) self.run_date = run_date def set_run_time(self, run_time: str) -> None: """ - 'set_run_time' + ``set_run_time`` stores PTRAC header run time variable. + + ``set_run_time`` checks given arguments before assigning the given value + to ``Header.run_time``. If given an unrecognized argument, it raises + semantic errors. + + Parameters: + run_time: Simulation run time. + + Raises: + MCNPSemanticError: INVALID_HEADER_RUNTIME. """ if run_time is None: - raise ValueError + raise errors.MCNPSemanticError(errors.MCNPSemanticCodes.INVALID_HEADER_RUNTIME) self.run_time = run_time def set_title(self, title: str) -> None: """ - 'set_title' + ``set_title`` stores PTRAC header title variable. + + set_title`` checks given arguments before assigning the given value + to ``title.code``. If given an unrecognized argument, it raises + semantic errors. + + Parameters: + title: Simulation title. + + Raises: + MCNPSemanticError: INVALID_HEADER_TITLE. """ if title is None or not (len(title) < 80): - raise ValueError + raise errors.MCNPSemanticError(errors.MCNPSemanticCodes.INVALID_HEADER_TITLE) self.title = title @classmethod def from_mcnp(cls, source: str) -> tuple[Header, str]: """ - 'from_mcnp' + ``from_mcnp`` generates ``Header`` objects from PTRAC. + + ``from_mcnp`` constructs instances of ``Header`` from PTRAC source + strings, so it operates as a class constructor method and PTRAC parser + helper function. + + Parameters: + source: PTRAC for header. + + Returns: + ``Header`` object. + + Raises: + MCNPSyntaxError: TOOFEW_HEADER, TOOLONG_HEADER, KEYWORD_HEADER_MINUS1 """ header = cls() - source = parser.Preprocessor.process_ptrac(source) - lines = parser.Parser(source.split("\n"), SyntaxError) + source = _parser.Preprocessor.process_ptrac(source) + lines = _parser.Parser(source.split("\n"), errors.MCNPSyntaxError(errors.MCNPSyntaxCodes.TOOFEW_HEADER)) # Processing Magic Number if lines.popl() != "-1": - raise SyntaxError + raise errors.MCNPSyntaxError(errors.MCNPSyntaxCodes.KEYWORD_HEADER_MINUS1) # Processing Header - tokens = parser.Parser(lines.popl().split(" "), SyntaxError) - if len(tokens) != 5: - raise SyntaxError - + tokens = _parser.Parser(lines.popl().split(" "), errors.MCNPSyntaxError(errors.MCNPSyntaxCodes.TOOFEW_HEADER)) header.set_code(tokens.popl()) header.set_version(tokens.popl()) header.set_code_date(tokens.popl()) @@ -152,32 +252,36 @@ def from_mcnp(cls, source: str) -> tuple[Header, str]: header.set_title(lines.popl()) # Processing Settings Block - tokens = parser.Parser(lines.popl().strip().split(" "), SyntaxError) + tokens = _parser.Parser(lines.popl().strip().split(" "), errors.MCNPSyntaxError(errors.MCNPSyntaxCodes.TOOFEW_HEADER)) if len(tokens) != 10: - raise SyntaxError + raise errors.MCNPSyntaxError(errors.MCNPSyntaxCodes.TOOFEW_HEADER) m = types.cast_fortran_real(tokens.popl(), lambda f: f == 13 or f == 14) if m is None: - raise ValueError + raise errors.MCNPSemanticError(errors.MCNPSemanticCodes.INVALID_HEADER_SETTINGS) for i in range(0, int(m)): if not tokens: - tokens = parser.Parser(lines.popl().strip().split(" "), SyntaxError) + tokens = _parser.Parser( + lines.popl().strip().split(" "), errors.MCNPSyntaxError(errors.MCNPSyntaxCodes.TOOFEW_HEADER) + ) if len(tokens) != 10: - raise SyntaxError + raise errors.MCNPSyntaxError(errors.MCNPSyntaxCodes.TOOFEW_HEADER) n = types.cast_fortran_real(tokens.popl(), lambda f: f >= 0) if n is None: - raise ValueError + raise errors.MCNPSemanticError(errors.MCNPSemanticCodes.INVALID_HEADER_SETTINGS) values = [None] * int(n) for j in range(0, int(n)): if not tokens: - tokens = parser.Parser(lines.popl().strip().split(" "), SyntaxError) + tokens = _parser.Parser( + lines.popl().strip().split(" "), errors.MCNPSyntaxError(errors.MCNPSyntaxCodes.TOOFEW_HEADER) + ) if len(tokens) != 10: - raise SyntaxError + raise errors.MCNPSyntaxError(errors.MCNPSyntaxCodes.TOOFEW_HEADER) values[j] = tokens.popl() @@ -185,18 +289,18 @@ def from_mcnp(cls, source: str) -> tuple[Header, str]: while tokens: if types.cast_fortran_real(tokens.popl(), lambda f: f == 0) is None: - raise ValueError + raise errors.MCNPSemanticError(errors.MCNPSemanticCodes.INVALID_HEADER_SETTINGS) # Processing Numbers - tokens = parser.Parser(lines.popl().strip().split(" "), SyntaxError) + tokens = _parser.Parser(lines.popl().strip().split(" "), errors.MCNPSyntaxError(errors.MCNPSyntaxCodes.TOOFEW_HEADER)) if len(tokens) != 20: - raise SyntaxError + raise errors.MCNPSyntaxError(errors.MCNPSyntaxCodes.TOOFEW_HEADER) numbers = [] while tokens: n = types.cast_fortran_integer(tokens.peekl(), lambda i: i >= 0) if n is None: - raise SyntaxError + raise errors.MCNPSyntaxError(errors.MCNPSyntaxCodes.TOOFEW_HEADER) numbers.append(n) tokens.popl() @@ -209,21 +313,23 @@ def from_mcnp(cls, source: str) -> tuple[Header, str]: [6, 9, 7, 9, 7, 9, 7, 9, 7, 9], [7, 9, 8, 9, 8, 9, 8, 9, 8, 9], }: - raise SyntaxError + raise errors.MCNPSemanticError(errors.MCNPSemanticCodes.INVALID_HEADER_NUMBERS) # Processing Entry Counts - tokens = parser.Parser(lines.popl().stirp().split(" "), SyntaxError) + tokens = _parser.Parser(lines.popl().stirp().split(" "), errors.MCNPSyntaxError(errors.MCNPSyntaxCodes.TOOFEW_HEADER)) if len(tokens) > 30: - raise SyntaxError + raise errors.MCNPSyntaxError(errors.MCNPSyntaxCodes.TOOMANY_HEADER) total = sum(header.numbers[:10]) header.ids = [None] * total for i in range(0, total): if not tokens: - tokens = parser.Parser(lines.popl().strip().split(" "), SyntaxError) + tokens = _parser.Parser( + lines.popl().strip().split(" "), errors.MCNPSyntaxError(errors.MCNPSyntaxCodes.TOOFEW_HEADER) + ) if len(tokens) > 30: - raise SyntaxError + raise errors.MCNPSyntaxError(errors.MCNPSyntaxCodes.TOOMANY_HEADER) header.ids[i] = tokens.popl() @@ -231,17 +337,23 @@ def from_mcnp(cls, source: str) -> tuple[Header, str]: def to_arguments(self): """ - 'to_arguments' + ``to_arguments`` makes dictionaries from ``Header`` objects. + + ``to_arguments`` creates Python dictionaries from ``Header`` objects, + so it provides an MCNP endpoint. The dictionary keys follow the MCNP + manual. + + Returns: + Dictionary for ``Header`` object. """ return { - "code": self.code, - "code_date": self.code_date, - "version": self.version, - "run_date": self.run_date, - "run_time": self.run_time, - "title": self.title, - "settings": self.settings, - "numbers": self.numbers, - "ids": self.ids, + "kod": self.code, + "loddat": self.code_date, + "ver": self.version, + "idtm": (self.run_date, self.run_time), + "aid": self.title, + "m n v ... V ...": self.settings, + "N1 ... N20": self.numbers, + "L ... L": self.ids, } diff --git a/src/pymcnp/files/ptrac/history.py b/src/pymcnp/files/ptrac/history.py index 68ba1ea..18082cf 100644 --- a/src/pymcnp/files/ptrac/history.py +++ b/src/pymcnp/files/ptrac/history.py @@ -1,5 +1,8 @@ """ -'history' +``history`` contains classes representing PTRAC histories. + +``history`` packages the ``History`` class, providing an object-oriented, +importable interface for PTRAC event histories. """ @@ -7,23 +10,37 @@ from .event import Event from .header import Header -from .._utils import parser -from .._utils import types +from ..utils import _parser +from ..utils import types class History: """ - 'History' + ``History`` represents PTRAC event histories. + + ``History`` implements PTRAC event histories as a Python class. Its + attributes store PTRAC event hisotry metadata and data parameters, and its + methods provide entry points and endpoints for working with PTRAC. It + represents the PTRAC event history syntax element. + + Attributes: + header: History context, i.e. PTRAC header. + next_type: Event type of the next event. + nps: Count of source particles started. + ncl: Problem numbers of the cells. + nsf: Problem transformation of the surfaces. + jptal: Basic tally information. + tal: Tally scores accumulation. + events: List of events in the PTRAC history. """ def __init__(self): """ - '__init__' + ``__init__`` initializes ``History``. """ self.header: Header = None self.next_type: Event.EventTypes = None - self.nps: int = None self.ncl: int = None self.nsf: int = None @@ -34,78 +51,152 @@ def __init__(self): def set_nps(self, nps: int) -> None: """ - 'set_nps' + ``set_nps`` stores PTRAC history nps variable. + + ``set_code`` checks given arguments before assigning the given value + to ``code.nps``. If given an unrecognized argument, it raises + semantic errors. + + Parameters: + nps: Count of source particles started. + + Raises: + MCNPSemanticError: INVALID_HISTORY_NPS. """ if nps is None: - raise ValueError + raise error.MCNPSemanticError(error.MCNPSemanticCodes.INVALID_HISTORY_NPS) self.nps = nps def set_ncl(self, ncl: int) -> None: """ - 'set_ncl' + ``set_ncl`` stores PTRAC history ncl variable. + + ``set_ncl`` checks given arguments before assigning the given value + to ``code.ncl``. If given an unrecognized argument, it raises + semantic errors. + + Parameters: + ncl: Problem numbers of the cells. + + Raises: + MCNPSemanticError: INVALID_HISTORY_NCL. """ if ncl is None: - raise ValueError + raise error.MCNPSemanticError(error.MCNPSemanticCodes.INVALID_HISTORY_NCL) self.ncl = ncl - def set_nfs(self, nfs: int) -> None: + def set_nsf(self, nsf: int) -> None: """ - 'set_nfs' + ``set_nsf`` stores PTRAC history nsf variable. + + ``set_nsf`` checks given arguments before assigning the given value + to ``code.nsf``. If given an unrecognized argument, it raises + semantic errors. + + Parameters: + nsf: Problem transformation of the surfaces. + + Raises: + MCNPSemanticError: INVALID_HISTORY_NSF. """ if nfs is None: - raise ValueError + raise error.MCNPSemanticError(error.MCNPSemanticCodes.INVALID_HISTORY_NSF) - self.nfs = nfs + self.nsf = nsf def set_jptal(self, jptal: int) -> None: """ - 'set_jptal' + ``set_jptal`` stores PTRAC history jptal variable. + + ``set_jptal`` checks given arguments before assigning the given value + to ``code.jptal``. If given an unrecognized argument, it raises + semantic errors. + + Parameters: + jptal: Basic tally information. + + Raises: + MCNPSemanticError: INVALID_HISTORY_JPTAL. """ if jptal is None: - raise ValueError + raise error.MCNPSemanticError(error.MCNPSemanticCodes.INVALID_HISTORY_JPTAL) self.jptal = jptal def set_tal(self, tal: int) -> None: """ - 'set_tal' + ``set_tal`` stores PTRAC history tal variable. + + ``set_tal`` checks given arguments before assigning the given value + to ``code.tal``. If given an unrecognized argument, it raises + semantic errors. + + Parameters: + tal: Tally scores accumulation. + + Raises: + MCNPSemanticError: INVALID_HISTORY_TAL. """ if tal is None: - raise ValueError + raise error.MCNPSemanticError(error.MCNPSemanticCodes.INVALID_HISTORY_TAL) self.tal = tal def set_next_type(self, next_type: Event.EventTypes) -> None: """ - 'set_next_type' + ``set_next_type`` stores PTRAC history first event type variable. + + ``set_next_type`` checks given arguments before assigning the given + value to ``code.next_type``. If given an unrecognized argument, it + raises semantic errors. + + Parameters: + next_type: Event type of the next event. + + Raises: + MCNPSemanticError: INVALID_HISTORY_NEXTTYPE. """ if next_type is None: - return ValueError + return error.MCNPSemanticError(error.MCNPSemanticCodes.INVALID_HISTORY_NEXTTYPE) self.next_type = next_type @classmethod def from_mcnp(cls, source: str, header: Header) -> tuple[History, str]: """ - 'from_mcnp' + ``from_mcnp`` generates ``History`` objects from PTRAC. + + ``from_mcnp`` constructs instances of ``History`` from PTRAC source + strings, so it operates as a class constructor method and PTRAC parser + helper function. + + Parameters: + source: PTRAC for history. + header: PTRAC header. + + Returns: + ``History`` object. + + Raises: + MCNPSyntaxError: TOOFEW_HISTORY, TOOLONG_HISTORY. """ history = cls() history.header = header - source = parser.Preprocessor.process_ptrac(source) - lines = parser.Parser(source.split("\n"), EOFError) + source = _parser.Preprocessor.process_ptrac(source) + lines = _parser.Parser(source.split("\n"), error.MCNPSyntaxError(MCNPSyntaxError.TOFEW_HISTORY)) # Processing I Line - tokens = parser.Parser(lines.popl().strip().split(" "), SyntaxError) + tokens = _parser.Parser(lines.popl().strip().split(" "), error.MCNPSyntaxError(error.MCNPSyntaxCode.TOFEW_HISTORY)) if len(tokens) != header.numbers[0]: raise SyntaxError @@ -133,7 +224,7 @@ def from_mcnp(cls, source: str, header: Header) -> tuple[History, str]: # Processing J & P Lines events = [] - tokens = parser.Parser(lines.peekl().split(" "), SyntaxError) + tokens = _parser.Parser(lines.peekl().split(" "), error.MCNPSyntaxError(error.MCNPSyntaxCode.TOFEW_HISTORY)) next_type = history.next_type while next_type != Event.EventTypes.FLAG: @@ -147,7 +238,14 @@ def from_mcnp(cls, source: str, header: Header) -> tuple[History, str]: def to_arguments(self) -> dict: """ - 'to_arguments' + ``to_arguments`` makes dictionaries from ``History`` objects. + + ``to_arguments`` creates Python dictionaries from ``History`` objects, + so it provides an MCNP endpoint. The dictionary keys follow the MCNP + manual. + + Returns: + Dictionary for ``History`` object. """ return { diff --git a/src/pymcnp/files/ptrac/ptrac.py b/src/pymcnp/files/ptrac/ptrac.py index 6cfd2a8..4881b15 100644 --- a/src/pymcnp/files/ptrac/ptrac.py +++ b/src/pymcnp/files/ptrac/ptrac.py @@ -1,5 +1,8 @@ """ -'ptrac' +``ptrac`` contains classes representing PTRAC files. + +``ptrac`` packages the ``Ptrac`` class, providing an object-oriented, +importable interface for PTRAC files. """ @@ -9,12 +12,20 @@ class Ptrac: """ - 'Ptrac' + ``Ptrac`` represents PTRAC files. + + ``Ptrac`` implements PTRAC files as a Python class. Its attributes store + PTRAC file components, and its methods provide entry points and endpoints + for working with PTRAC. It represents the PTRAC files syntax element. + + Attributes: + header: PTRAC header. + history: PTRAC history. """ def __init__(self): """ - '__init__' + ``__init__`` initializes ``Ptrac``. """ self.header: Header = None @@ -23,7 +34,16 @@ def __init__(self): @classmethod def from_mcnp(cls, source: str): """ - 'from_mcnp' + ``from_mcnp`` generates ``Ptrac`` objects from PTRAC. + + ``from_mcnp`` constructs instances of ``Inp`` from PTRAC source + strings, so it operates as a class constructor method and PTRAC parser. + + Parameters: + source: Complete PTRAC source string. + + Returns: + ``Ptrac`` object. """ ptrac = cls() @@ -45,7 +65,16 @@ def from_mcnp(cls, source: str): @classmethod def from_mcnp_file(cls, filename: str): """ - 'from_mcnp_file' + ``from_mcnp_file`` generates ``Ptrac`` objects from PTRAC files. + + ``from_mcnp_file`` constructs instances of ``Ptrac`` from PTRAC files, + so it operates as a class constructor method and PTRAC parser. + + Parameters: + filename: Name of file to parse. + + Returns: + ``Ptrac`` object. """ with open(filename) as file: @@ -55,7 +84,14 @@ def from_mcnp_file(cls, filename: str): def to_arguments(self) -> dict: """ - 'to_arguments' + ``to_arguments`` makes dictionaries from ``Ptrac`` objects. + + ``to_arguments`` creates Python dictionaries from ``Ptrac`` objects, so + it provides an MCNP endpoint. The dictionary keys follow the MCNP + manual. + + Returns: + Dictionary for ``Ptrac`` object. """ return {