Mesh Entities¶

The following classes are Python object representations of 2DM geometries.

They are retrieved directly via the py2dm.Reader class, or can be converted manually by passing a line into their from_line() factory method.

To convert an instance back into its 2DM text representation, use the to_line() method. It returns a list of strings that can be formatted to match fixed-width columns if desired.

Nodes¶

class py2dm.Node¶

A unique, numbered point in space.

Nodes are the only geometries that define position in a mesh. Other objects like elements or node strings reference them by ID to position themselves.

Base classes: py2dm.Entity

__init__(id_: int, x: float, y: float, z: float) → None ¶

Create a new node.

See also

You can also create new nodes directly through the py2dm.Writer.node() method.

Parameters

id_ (int) – The unique ID of the node.
x (float) – X position of the node.
y (float) – Y position of the node.
z (float) – Z position of the node.

id¶

Unique identifier of the node.

Type: int

x¶

X coordinate of the node.

Type: float

See also

pos returns the node position as a tuple of floats.

y¶

Y coordinate of the node.

Type: float

See also

pos returns the node position as a tuple of floats.

z¶: Z coordinate of the node.

See also

pos returns the node position as a tuple of floats.

property pos¶

The 3D position of the node as a tuple of three floats.

Type: tuple [float, float, float]

__eq__(other: object) → bool ¶

Custom instance equality check.

This check passes whenever the two nodes with identical ID and coordiates are passed.

classmethod from_line(line: str, **kwargs) → py2dm.Node ¶

Instantiate a new Node from the given line.

Any extraneous keyword arguments are silently ignored.

Parameters

line (str) – The line to parse.
allow_zero_index (bool, optional) – Whether to allow a node ID of zero.

Returns

A node representing the given line.

Return type

Node

to_line(**kwargs) → list[str]¶

Generate the canonical 2DM representation of this entity.

This is returned as a list of strings to facilitate formatting into constant-width columns.

Returns: A list of words to write to disk.
Return type: list [str]

Elements¶

Base classes¶

class py2dm.Element¶

Base class for all mesh Elements.

This implements all of the abstract methods required to parse the element. The actual element classes themselves mostly serve to specify the 2DM card and number of nodes.

Base classes: py2dm.Entity

__init__(id_: int, *nodes: int, materials: Union[tuple[Union[int, float], …], None] = None) → None ¶

Create a new element.

See also

You can also create new elements directly through the py2dm.Writer.element() method.

Parameters

id_ (int) – The unique ID of the element
*nodes (int) – Any number of nodes making up the element
materials (tuple [int | float], optional) – Any number of material IDs for the element, defaults to None

id¶

The unique ID of the element.

Type: int

nodes¶

The defining nodes for this element.

Type: tuple [int, …]

materials¶

Material IDs assigned to this element.

Depending on the 2DM-like format used, this could be a floating point value used to store e.g. element centroid elevation.

Type: tuple [int | float, …]

property num_materials¶

The number of materials defined for this element.

Type: int

__eq__(other: object) → bool ¶

Custom instance equality check.

This check passes whenever the two elements with identical ID, node ID list and materials are passed.

classmethod from_line(line: str, **kwargs) → py2dm.Element ¶

Create a new instance from the given line.

Parameters

line (str) – The line to parse.
allow_float_matid (bool, optional) – Whether to allow floating point values as material indices. This is used by BASEMENT 3.x to store element centroid elevation.
allow_zero_index (bool, optional) – Whether to allow a node ID of zero.

to_line(**kwargs)¶

Generate the canonical 2DM representation of this entity.

This is returned as a list of strings to facilitate formatting into constant-width columns.

Returns: A list of words to write to disk.
Return type: list [str]

class py2dm.LinearElement¶

Base class for linear mesh elements.

Base classes: py2dm.Element

This is exclusively provided to group related element types together and to allow checking for element type via their shared base class:

if isinstance(obj, py2dm.LinearElement):
    ...

class py2dm.TriangularElement¶

Base class for triangular mesh elements.

Base classes: py2dm.Element

This is exclusively provided to group related element types together and to allow checking for element type via their shared base class:

if isinstance(obj, py2dm.TriangularElement):
    ...

class py2dm.QuadrilateralElement¶

Base class for quadrilateral mesh elements.

Base classes: py2dm.Element

This is exclusively provided to group related element types together and to allow checking for element type via their shared base class:

if isinstance(obj, py2dm.QuadrilateralElement):
    ...

Element types¶

class py2dm.Element2L¶

Two-noded, linear element (E2L).

Base classes: py2dm.LinearElement

class py2dm.Element3L¶

Three-noded, linear element (E3L).

Base classes: py2dm.LinearElement

class py2dm.Element3T¶

Three-noded, triangular mesh element (E3T).

Base classes: py2dm.TriangularElement

class py2dm.Element4Q¶

Four-noded, quadrilateral mesh element (E4Q).

Base classes: py2dm.QuadrilateralElement

class py2dm.Element6T¶

Six-noded, triangular mesh element (E6T).

Base classes: py2dm.TriangularElement

class py2dm.Element8Q¶

Eight-noded, quadrilateral mesh element (E8Q).

Base classes: py2dm.QuadrilateralElement

class py2dm.Element9Q¶

Nine-noded, quadrilateral mesh element (E9Q).

Base classes: py2dm.QuadrilateralElement

Node strings¶

class py2dm.NodeString¶

A polyline represented by a string of nodes (NS).

This differs from the other mesh entity classes in that the from_line() method features an optional parameter that allows specification of an existing node string to extend.

This is necessary as node strings may be split across multiple lines in a 2DM file as lines may not exceed 10 tags.

Important

While this class implements most of the py2dm.Entity interface, it does not inherit from it. isinstance() or issubclass() checks will fail for node strings.

__init__(self, *nodes: int, name: Union[str, None] = None) → None ¶

Create a new node string.

See also

You can also create new nodes directly through the py2dm.Writer.node_string() method.

Parameters

*nodes (int) – A list of node IDs making up the node string
name (str, optional) – An optional name to give to a particular node string, defaults to None

nodes¶

The defining nodes of the node strings.

Type: tuple [int]

name¶

An optional name used to identify the node string.

Type: str | None

property num_nodes¶

Return the number of nodes in the node string.

Type: int

__eq__(other: object) → bool ¶

Custom instance equality check.

This check passes whenever the two nodes with identical ID and coordiates are passed.

classmethod from_line(line: str, node_string: Union[py2dm.NodeString, None] = None, **kwargs) → tuple[py2dm.NodeString, bool]¶

Create a new instance from the given line.

This returns a tuple consisting of the NodeString instance generated, as well as a flag indicating whether the node string is complete, which is indicated by a negative node ID.

Parameters

line – The line to parse
node_string (NodeString, optional) – An existing node string to append, defaults to None

Returns

The created node string and the final flag

Return type

tuple [NodeString, bool]

to_line(**kwargs) → list[str]¶

Generate the canonical 2DM representation of this entity.

The returned list should be written as a whitespace-separated list with irregular line width. It may also contain newline characters. No whitespace should be inserted around newlines.

Returns: A list of words to write to disk
Return type: list [str]

Entity interface¶

class py2dm.Entity¶

Base class for geometries defined in the 2DM specification.

This includes Node, NodeString, and subclasses of Element like Element3T.

This is an abstract class, subclasses must implement the from_line() and to_line() methods, as well as provide a card class attribute associating them with their corresponding 2DM card.

__eq__(other: object) → bool ¶

Custom instance equality check.

This reimplements the equality check operator and only compares the object type and card identifier. Subclasses must extend this method to include checks for attributes; as-is this is equivalent to type(a) == type(b).

Warning

Subclassing this base without properly extending this method could lead to unexpected behaviour.

abstract classmethod from_line(line: str, **kwargs) → py2dm.Entity ¶

Create a new instance from the given line.

Lines passed into this element must start with the appropriate card identifier; trailing whitespace is allowed.

If any bad data is encountered, a FormatError should be raised by the implementation.

Parameters: line (str) – The line to parse.
Returns: An instance as described by the provided line.
Return type: Entity

abstract to_line(**kwargs) → list[str]¶

Generate the canonical 2DM representation of this entity.

The line is returned as a list of strings to facilitate formatting into constant-width columns if requested.

Returns: A list of words to write to disk.
Return type: list [str]