Reading and writing¶

Read a numgeo input file into a :class:~pynumgeo.deck.Deck.

The reader interprets the input the way numgeo does (:mod:pynumgeo.io.lexer for preprocessing, the solver's option rules for the keywords modelled here) and reports everything that numgeo would reject or read differently than a user would expect as :class:~pynumgeo.validation.issue.Issue objects. Keywords that pynumgeo does not model are kept as generic :class:~pynumgeo.deck.keyword.Keyword objects.

Models with *Part / *Instance / *Assembly are flattened with numgeo's rules: instance-scoped set names become <instance>.<set>, node and element labels are offset per instance (each part must be numbered 1..n in input order, which is what numgeo needs anyway), instance translations and rotations are applied to the coordinates, and find queries inside an instance are evaluated in the instance's scope.

Examples:

>>> import pathlib, tempfile
>>> p = pathlib.Path(tempfile.mkdtemp()) / "job.inp"
>>> _ = p.write_text("*Node\n1, 0., 0.\n2, 1., 0.\n*Element, type=u2-truss\n1, 1, 2\n"
...                  "*Nset, nset=Fix\n1\n*Step, name=S1\n*Static\n1., 1., 1., 1.\n"
...                  "*Boundary\nFix, u1, 0.\n*End step\n")
>>> res = parse(p)
>>> res.deck.mesh.node_count, res.deck.steps[0].items[0].data
(2, [['Fix', 'u1', 0.0]])
>>> [i.id for i in res.issues]
[]

Write a :class:~pynumgeo.deck.Deck as a numgeo input file.

Spelling: never all capitals. Keywords are written in sentence case with the docs' word breaks (*Step, *Initial conditions, *Node output), option keys and enumerated values in lower case, names defined in the deck (sets, surfaces, materials, amplitudes, steps, ...) exactly as given. numgeo upper-cases every line and deletes blanks, so this is what it reads.

Canonical order: nodes, elements, sets, surfaces, amplitudes, materials, material assignments, other model keywords (in their original order), steps, *End input. Options are written in the order the solver's readers require (name= first and scalefactor= second on *Step, type= first on *Element). Reals are written as Python's shortest round-trip text. Lines never exceed 256 characters (:class:WriteError otherwise); element records that would are split over two lines with different field counts, which is what numgeo's pre-scan needs.

The output is byte-stable: the same deck always gives the same text.

Comments: the comment of a keyword, element block, set, surface, material, amplitude, section or step is written above it as ** lines (comments=False leaves them out). Include files: :func:write_texts and write(..., includes=...) put the mesh and the materials into files of their own that the main file includes, the numgeo-GiD layout.

Examples:

>>> from pynumgeo.deck import Deck, Keyword, Step
>>> d = Deck()
>>> _ = d.mesh.add_nodes([[0, 0], [1, 0]]); _ = d.mesh.add_elements("u2-truss", [[1, 2]])
>>> _ = d.mesh.add_nset("Fix", [1])
>>> d.steps.append(Step(name="Load", procedure=Keyword.make("*Static", data=[[0.1, 1.0, 1e-5, 0.5]]),
...     items=[Keyword.make("*Boundary", data=[["Fix", "U1", 0.0]])]))
>>> print(write_text(d, header=False))
*Node
1, 0.0, 0.0
2, 1.0, 0.0
*Element, type=u2-truss
1, 1, 2
*Nset, nset=Fix
1
*Step, name=Load
*Static
0.1, 1.0, 1e-05, 0.5
*Boundary
Fix, u1, 0.0
*End step
*End input

Emulation of numgeo's preprocessing of an input file.

numgeo first copies the input file into an internal file (<job>_internal.inp) and parses only that copy (src/input/input_create_internal_input_.f90). The rules, reproduced here one by one:

1. Every physical line is read into 256 characters; the rest is lost (:49, :58).
2. ** starts a comment anywhere in a line; blank lines are dropped (:64-68, :134-153).
3. A line whose upper-cased text contains INCLUDE is an include: the text after the first = (leading and trailing blanks removed) plus .inp is copied in; includes are not nested (:70-97).
4. Lines are upper-cased (ASCII letters only) (:127).
5. All blanks are deleted, except between the first and the last $ of a line (:156-160).
6. A comma at the end of a line is removed (:162-174).
7. The line *AMPLITUDE,NAME=DEFAULT,TYPE=RAMP is prepended (:55).

Every resulting :class:Line keeps the solver's text (text), the same text without upper-casing (cased, used to keep the user's spelling of names) and its source position. Deviations from what a careful user would expect (truncated lines, tabs, a line that is an include only because it contains the word INCLUDE, ...) are reported as :class:Quirk objects, never silently corrected.

Examples:

>>> pre = preprocess_text("*Step, name = Load 1  ** first step\n*Static\n0.1, 1., 1e-5, 1.,\n")
>>> [ln.text for ln in pre.lines][1:]
['*STEP,NAME=LOAD1', '*STATIC', '0.1,1.,1E-5,1.']
>>> pre.lines[1].cased
'*Step,name=Load1'

Keyword blocks: the internal lines grouped the way numgeo's readers consume them.

A :class:KeywordBlock is a keyword line, its data lines (the following lines that do not start with *) and, for container keywords, its child blocks:

===================== ============================================================================== container children ===================== ============================================================================== *STEP every block up to *ENDSTEP (src/input/read_step_.f90) *PART blocks up to *ENDPART; *INSTANCE / *ASSEMBLY likewise *MATERIAL the following material sub-keywords (src/input/read_material_.f90) *INTERACTION *NORMAL / *FRICTION lines that follow *OUTPUT *FREQUENCY, *NODE[OUTPUT], *ELEMENT[OUTPUT], *INTEGRATIONPOINT *DYNAMIC *HILBER-HUGHES-TAYLOR / *HHT / *BACKWARDEULER / *BWE *EXPLICITDYNAMIC *MASSSCALING *EQUATION *PENALTY (also under *RIGIDBODY) ===================== ==============================================================================

The grouping is purely syntactic; whether numgeo accepts a block is decided by the reader and the validator.

Examples:

>>> from pynumgeo.io.lexer import preprocess_text
>>> blocks = parse_blocks(preprocess_text(
...     "*Material, name=Soil\n*Density\n2.0\n*Step, name=S1\n*Static\n1,1,1,1\n*End step\n").lines)
>>> [(b.keyword, [c.keyword for c in b.children]) for b in blocks]
[('*AMPLITUDE', []), ('*MATERIAL', ['*DENSITY']), ('*STEP', ['*STATIC', '*ENDSTEP'])]
>>> blocks[1].option("NAME").value_cased
'Soil'

Numbers as numgeo reads and writes them.

numgeo reads values with Fortran list-directed input (read(line, *)). That accepts more spellings than Python's float: 210d6, 1.0D-3, 1.0+5 (exponent without letter), .5 and 5.. Result files contain numbers such as 0.123456-100 (three-digit exponent without E).

pynumgeo writes reals as Python's shortest round-trip representation, which numgeo reads back exactly, and never writes inf or nan.

Examples:

>>> parse_real("210d6")
210000000.0
>>> parse_real("1.0+5")
100000.0
>>> parse_real(".5")
0.5
>>> format_real(1e-5), format_real(210e6), format_real(-0.0)
('1e-05', '210000000.0', '-0.0')
>>> is_number("FIX")
False