armi.utils.asciimaps module

ASCII maps are little grids of letters/numbers that represent some kind of a lattice.

These are commonly used in nuclear analysis to represent core maps, pin layouts, etc. in input files. This module reads various text and interprets them into meaningful data structures.

We make classes for different geometries to share code. This will eventually be expanded for various symmetries that are applicable to cores, assemblies, etc.

This is as attempted reimplementation of AsciiMaps aiming for simplicity, though inherently this work is complex.

Some vocabulary used here:

column, line

column and line numbers in the actual ascii text representation. What you would see in a text editor.

offset

The number of spaces needed at the beginning a line to properly orient the ascii representation.

i, j

Indices in the grid itself. For Cartesian, j is like the line number, but in other geometries (like hex), it is a totally different coordinate system.

See also

armi.reactor.grids

More powerful, nestable lattices with specific dimensions Most input lattices eventually end up as Grid objects.

armi.reactor.blueprints.latticeBlueprint

user input of generic lattices

armi.reactor.geometry

a specific usage of lattices, for core maps

class armi.utils.asciimaps.AsciiMap

Bases: object

Base class for maps.

These should be able to read and write ASCII maps loaded either from text or programatically with i,j / specifiers.

asciiLines = None

A list of lines, each containing a list of ascii labels for each column. No blanks.

asciiOffsets = None

A list of offset integers for each line above that will be prepended before the contents of asciiLines

asciiLabelByIndices = None

A mapping from grid location objects to ascii labels

_spacer = None

Individual spacing for one ‘item’ of ascii

_placeholder = None

Placeholder for blank data. Also holds the size of ascii window for each value

_asciiMaxCol = None

max number of text columns in text representation

_asciiMaxLine = None

max number of text lines in text representation

_ijMax = None

max num of i+j indices (max(i) + max(j)), needed mostly for hex

_asciiLinesOffCorner = None

Number of ascii lines chopped of corners

writeAscii(stream)

Write out the ascii representation

readAscii(text)

Read ascii representation from a stream.

Update placeholder size according to largest thing read.

_updateSlotSizeFromData()

After reading data, update slot size for writing.

_updateDimensionsFromAsciiLines()

When converting ascii to data we need to infer the ijMax before reading the ij indices.

See also

_updateDimensionsFromData()

used to infer this information when loading from i,j data

_updateDimensionsFromData()

Before converting data to ascii, inspect the data and set some map dimensions.

See also

_updateDimensionsFromAsciiLines()

used when reading info from ascii lines

static fromReactor(reactor)

Populate mapping from a reactor in preparation of writing out to ascii.

_getLineNumsToWrite()

Get order of lines to write.

Most maps index from bottom to top.

gridContentsToAscii()

Convert a prepared asciiLabelByIndices to ascii lines and offsets.

This is used when you have i,j/specifier data and want to create a ascii map from it as opposed to reading a ascii map from a stream.

As long as the map knows how to convert lineNum and colNums into ij indices, this is universal. In some implementations, this operation is in a different method for efficiency.

static _removeTrailingPlaceholders(line)

_asciiLinesToIndices()

Convert read in ASCII lines to a asciiLabelByIndices structure

_getIJFromColRow(columnNum: int, lineNum: int) → tuple

Get ij data indices from ascii map text coords.

_makeOffsets()

Build offsets

items()

keys()

class armi.utils.asciimaps.AsciiMapCartesian

Bases: armi.utils.asciimaps.AsciiMap

Cartesian ascii map.

Conveniently simple because offsets are always 0

i and j are equal to column, row

_asciiLinesToIndices()

Convert read in ASCII lines to a asciiLabelByIndices structure

_updateDimensionsFromData()

Before converting data to ascii, inspect the data and set some map dimensions.

See also

_updateDimensionsFromAsciiLines()

used when reading info from ascii lines

_getIJFromColRow(columnNum, lineNum)

Get ij data indices from ascii map text coords.

_makeOffsets()

Cartesian grids have 0 offset on all lines.

_updateDimensionsFromAsciiLines()

When converting ascii to data we need to infer the ijMax before reading the ij indices.

See also

_updateDimensionsFromData()

used to infer this information when loading from i,j data

class armi.utils.asciimaps.AsciiMapHexThirdFlatsUp

Bases: armi.utils.asciimaps.AsciiMap

Hex ascii map for 1/3 core flats-up map.

Indices start with (0,0) in the bottom left (origin). i increments on the 30-degree ray j increments on the 90-degree ray

In all flats-up hex maps, i increments by 2*col for each col and j decrements by col from the base.

These are much more complex maps than the tips up ones because there are 2 ascii lines for every j index (jaggedly).

Lines are read from the bottom of the ascii map up in this case.

_asciiLinesToIndices()

Convert read in ASCII lines to a asciiLabelByIndices structure

_getIJBaseByAsciiLine(asciiLineNum)

Get i,j base (starting point) for a row from bottom.

These are the indices of the far-left item in a row as a function of line number from the bottom. These are used in the process of computing the indices of items while reading the ascii map.

For 1/3 symmetric cases, the base is a constant pattern vs. row number at least until the top section where the hexagon comes off the 1/3 symmetry line.

The base hexes (LHS) as a function of rows from bottom are:

Row: 0 1 2 3 4 5 6 7 8 9 10 11 12 Base: (0,0), (1,0) (0,1), (1,1), (0,2), (-1,3), (0,3), (-1,4), (-2,5), (-1,5), (-2,6), (-3,7) (-2,7)

Looking graphically, there are basically 3 rays going up at 120 degrees. So we can find a consistent pattern for each ray and use a modulus to figure out which ray we’re on.

_getIJFromColAndBase(columnNum, iBase, jBase)

Map ascii column and base to i,j hex indices.

_getIJFromColRow(columnNum, lineNum)

Map ascii column and row to i,j hex indices.

Notes

Not used in reading from file b/c too many calls to base but convenient for writing from ij data

_makeOffsets()

One third hex grids have larger offsets at the bottom so the overhanging top fits.

_updateDimensionsFromAsciiLines()

Update some dimension metadata by looking at the ascii lines.

In this case, asciiMaxCol actually represents the max i index.

_updateDimensionsFromData()

Set map dimension metadata based on populated data structure.

Used before writing the asciimap from data.

Add flat-hex specific corner truncation detection that allows some positions to be empty near the corners of the full hex, as is typical for hexagonal core maps.

For 1/3 hex, _ijMax represents the outer outline

class armi.utils.asciimaps.AsciiMapHexFullFlatsUp

Bases: armi.utils.asciimaps.AsciiMapHexThirdFlatsUp

Full core flats up ascii map.

Notes

Rather than making a consistent base, we switch base angles with this one because otherwise there would be a ridiculous number of placeholders on the left. This makes this one’s base computation more complex.

We also allow all corners to be cut off on these, further complicating things.

_getIJBaseByAsciiLine(asciiLineNum)

Get i,j base (starting point) for a row from bottom.

Starts out in simple pattern and then shifts.

Recall that there are 2 ascii lines per j index because jagged.

If hex corners are omitted, we must offset the line num to get the base right (complexity!)

In this orientation, we need the _ijMax to help orient us. This represents the number of ascii lines between the center of the core and the top (or bottom)

_makeOffsets()

Handle offsets for full-hex flat grids.

Due to the staggered nature, these have 0 or 1 offsets on top and then 0 or 1 + an actual offset on the bottom.

_updateDimensionsFromData()

Set map dimension metadata based on populated data structure.

Used before writing the asciimap from data.

Add flat-hex specific corner truncation detection that allows some positions to be empty near the corners of the full hex, as is typical for hexagonal core maps.

For 1/3 hex, _ijMax represents the outer outline

class armi.utils.asciimaps.AsciiMapHexFullTipsUp

Bases: armi.utils.asciimaps.AsciiMap

Full hex with tips up of the smaller cells.

I axis is pure horizontal here J axis is 60 degrees up. (upper right corner)

(0,0) is in the center of the hexagon.

Frequently used for pins inside hex assemblies.

This does not currently support omitted positions on the hexagonal corners.

In this geometry, the outline-defining _ijMax is equal to I at the far right of the hex. Thus, ijMax represents the number of positions from the center to the outer edge towards any of the 6 corners.

_asciiLinesToIndices()

Read lines in from top to bottom.

_getIJFromColAndBase(columnNum, iBase, jBase)

Map ascii column and base to i,j hex indices.

Indices simply increment from the base across the rows.

_getIJFromColRow(columnNum, lineNum)

Map indices from ascii.

Notes

Not used in reading from file b/c inefficient/repeated base calc but required for writing from ij data

_getIJBaseByAsciiLine(asciiLineNum)

Get i,j base (starting point) for a row counting from the top.

Upper left is shifted by (size-1)//2

for a 19-line grid, we have the top left as (-18,9) and then: (-17, 8), (-16, 7), …

_updateDimensionsFromAsciiLines()

Update dimension metadata when reading ascii.

_updateDimensionsFromData()

Update asciimap dimensions from data before writing ascii.

_getLineNumsToWrite()

Get order of lines to write.

This map indexes lines from top to bottom.

_makeOffsets()

Full hex tips-up grids have linearly incrementing offset.

armi.utils.asciimaps.asciiMapFromGeomAndDomain(geomType: Union[str, armi.reactor.geometry.GeomType], domain: Union[str, armi.reactor.geometry.DomainType]) → armi.utils.asciimaps.AsciiMap

Get a ascii map class from a geometry and domain type.