14.8.6. steps.API_1.utilities.meshio

class ElementProxy(type, unitlength)[source]

Element Proxy Object

The Element Proxy object contains data imported from outside files (Abaqus, Tetgen), as well as the mapping from the element’s import id to its STEPS id, and vice versa. it also records block and/or group information contained in the imported file, which could be used for data tracing and compartment/patch creactions:

ElementProxy(type, unitlength)

Construct an empty ElementProxy object.

Parameters:

type (string): The type of the elements stored in this object.
unitlength (int): The length of vector units required for each element data. e.g. A node with 3 coordinates requires unitlength of 3, a tetrahedron with 4 nodes requires unitlength of 4. A triangle requires unitlength of 3.

Example:

nodeproxy = ElementProxy('node', 3)

insert(import_id, import_data)[source]

Insert an element to the Element Map object, a STEPS id will be assigned automatically.

Parameters:

import_id (int): The id of the element given by the importing file.
import_data (list): a list of data belongs to the element, e.g. for a node, a 3 units list of its coordinates.

Example:

nodeproxy.insert(1, [0.1, 0.2, 0.4])

Insert a node with import id 1 and coordinates x = 0.1, y = 0.2, z = 0.4 to nodeproxy. type nodeproxy.getSTEPSID(1) will return the STEPS id of this element.

getType()[source]: Return the type of elements stored in this Element Map object.

getSize()[source]: Return the number of elements stored in the Element Map object.

getDataFromSTEPSID(steps_id)[source]

Return the data of element with STEPS id steps_id.

Parameters:

steps_id (int): The STEPS id of the element, this id is automatically allocated when inserting the element to the Element Map (see insert() method).

getDataFromImportID(import_id)[source]

Return the data of element with import id import_id.

Parameters:

import_id (int): The import id of the element, this id is given by outside generator and contained in the imported file.

getAllData()[source]

Return all data as an one dimentional list. This list can be used to construct the Tetmesh.

Example:

nodedata = nodeproxy.getAllData()
tetdata = tetproxy.getAllData()
mesh = steps.geom.Tetmesh(nodedata, tetdata)

getSTEPSID(import_id)[source]

Return the STEPS id of a element from its import id.

Parameters:

import_id (int): The import id of the element.

getImportID(steps_id)[source]

Return the import id of a element from its STEPS id.

Parameters:

steps_id (int): The STEPS id of the element.

addGroup(group_name, group_ids)[source]

Add a group of elements in the Element Map object.

An group is defined as a list of element ids. Unlike blocks (see blockBegin() method), the ids of a group need not be continual. For this reason, user should provide a list which contains all ids of elements belong to this group. Each group has a unique name for data access.

No uniqueness or order is predefined for a group, this can be defined by the user for specific usage.

Groups can be used to construct compartments and patches in STEPS, please refer to the user manual for examples about using groups and blocks.

Parameters:

group_name (string): Name of the element group.
group_ids (list): A list of ids of elements belong to the group.

getGroups()[source]

Return all groups stored in the Element Map object.

Example:

The following group dictionary contains two groups:

"Group1" contains element ids 1,2,6,4,8
"Group2" contains element ids 3,1,2,1

groups = {"Group1":[1,2,6,4,8], "Group2":[3,1,2,1]}

Note that element 1 appears twice in “Group2”.

For meshes imported from Abaqus files, the keys of the groups are fetched from the ELSET id.

For meshes imported from Gmsh2.2 files, the keys of the groups are pairs of (tag_idx, tag_value), where tag_idx is the gmsh tag index position of the element, and tag_value is the tag value of the element. For example, if a tetrahedron is defined as below in Gmsh

1 4 2 2 3 16 17 13 18

It has two tags, tag[0] = 2 and tag[1] = 3, thus the element is contained in both groups[(0, 2)] and groups[(1, 3)]. Note that if a specfic name string is mapped to a value in the physical tag (tag[0]) in the file, the name string can also be used to access the same group, for example, if the following is defined in the file

$PhysicalNames 1 3 2 “inner” $EndPhysicalNames

groups[(0, 2)] can also be accessed using groups[(0, “inner”)]

getGroup(group_key)[source]

Return the group stored in the Element Map object with key = group_key. If the key is not present in the Element Map object, an empty list is returned.

Example:: g1 = getGroup(“Group1”) g2 = getGroup(“Group2”)

blockBegin(block_name)[source]

Notify the Element Map object that a new block with name block_name begins from the next element.

A block is a special type of group whose element’s STEPS ids is continual, i.e. can be represented by a begin id and an end id. An unique name should be given to each block, which can be used to access associated block information (i.e. a two unit list contains the block begin id and block end id).

If another block was initialized before calling the blockEnd() method, this method will also end the previous block and the its data will be stored.

A dictionary of blocks can be converted to a dictionary of group via the blocksToGroups() method.

Notice:

Although a block will be finished and stored when a new block is notified without calling the blockEnd() method, user is recommanded to call blockEnd() in the usual case.

Parameters:

block_name (string): Name of the element block.

blockEnd()[source]

Notify the Element Map object that the current element block should be ended. Block information (i.e. a dictionary element blockname:[begin_id, end_id]) will be added to the ElementProxy object.

Notice:

If the blockEnd() method is called before any block begins, or a block has been ended and there is no new block started, no information will be added to the block dictionary.

getBlocks()[source]

Return the block dictionary stored in the Element Map object.

A block dictionary uses the unique block names as keys, and a list of the start and end ids as values.

Example:

The following block dictionary contains two blocks: “Block1” starts from element with id of 0 and end at element 100, “Block2” starts from element 101 and ends at element 110:

blocks = { "Block1":[0, 100], "Block2":[100, 110] }

To access individual blocks, for example “Block1”, type:

block1 = blocks["Block1"]

User is recommanded to check Python’s manual for the usage of dictionary.

blocksToGroups()[source]

Convert the block dictionary to a group dictionary.

Return:

A dictionary of groups.

importTetGen(pathroot, scale, verbose=False)[source]

Read a TetGen-generated or refined mesh from a set of files.

The TetGen file format for describing a mesh actually consists of multiple files with varying suffixes. Currently, this routine only reads meshes consisting of three files:

<input>.node: describing the tetrahedral mesh node points.

<input>.ele: describing tetrahedral elements, each of which consists of 4 pointers into the <input>.node file. (TetGen also supports 10-node elements; these 6 extra nodes are obviously not read by STEPS.)

<input>.face: describing triangular faces, each of which consists of 3 pointers into the <input>.node file. This file is optional.

Other files are .vol (list of maximum volumes), .var (variant constraints) .neigh (list of neighbours), .smesh (simple PLC descriptions) and .edge (list of boundary edges) files. None of these seem relevant for our use cases, so we don’t load them even when they are there. In particular, the .neigh file is computed by STEPS itself.

Please refer to the TetGen manual (pages 31-40 in the last edition) for more information on these file formats

tetgen.berlios.de/files/tetgen-manual.pdf

(See the documentation for steps.geom.tetmesh for details about the mesh object.)

PARAMETERS:

pathroot The root of the path name. E.g. mesh/torus would make this routine try to read files mesh/torus.node, mesh/torus.ele and optionally for mesh/torus.face

scale: LENGTH scale from the importing mesh to real geometry. e.g. a radius of 10 in the importing file to a radius of 1 micron in STEPS, scale is 1e-7.

RETURNS:

mesh, nodeproxy, tetproxy, triproxy

mesh: The STEPS TetMesh object nodeproxy: Element Map for nodes tetproxy: Element Map for tetrahedrons triproxy: Element Map for triangles

IMPORTANT NOTICE:

User is recommanded to save the tetmesh objects using the saveTetmesh() method and recreate the objects from the saved files, instead of creating the objects via the importing functions each time, if the tetmesh objects are intented to be used in multiple simulations. Since the importing functions require a massive amount of time to create the Tetmesh object, comparing to the loadTetmesh() method.

importAbaqus(filename, scale, ebs=None, shadow_mesh=None, verbose=False)[source]

Read a ABAQUS-formated mesh file, return the created steps.geom.Tetmesh object, the element mapping for nodes, tetraedrons and triangles.

PARAMETERS:

filename: the Abaqus filename (or path) including any suffix.

scale: LENGTH scale from the importing mesh to real geometry. e.g. a radius of 10 in the importing file to a radius of 1 micron in STEPS, scale is 1e-7.

ebs: specify the names of selected element blocks which are included in the mesh.

shadow_mesh: name of the ShadowMesh file exported using the STEPS-CUBIT supporting toolkit, can also be the ShadowMesh object itself.

RETURNS:

mesh, nodeproxy, tetproxy, triproxy

mesh: The STEPS TetMesh object

nodeproxy: Element Map for nodes

tetproxy: Element Map for tetrahedrons

triproxy: Element Map for triangles

IMPORTANT NOTICE:

User is recommanded to save the tetmesh objects using the saveTetmesh() method and recreate the objects from the saved files, instead of creating the objects via the importing functions each time, if the tetmesh objects are intented to be used in multiple simulations. Since the importing functions require a massive amount of time to create the Tetmesh object, comparing to the loadTetmesh() method.

importAbaqus2(tetfilename, trifilename, scale, shadow_mesh=None, verbose=False)[source]

Read two ABAQUS-formated mesh files, one with tetrahedron data and the other with triangle data, return the created steps.geom.Tetmesh object, the element mapping for nodes, tetraedrons and triangles.

PARAMETERS:

tetfilename: the Abaqus filename for tetrahedron data including any suffix.
trifilename: the Abaqus filename for triangle data including any suffix.
scale: LENGTH scale from the importing mesh to real geometry. e.g. a radius of 10 in the importing file to a radius of 1 micron in STEPS, scale is 1e-7.
shadow_mesh: name of the ShadowMesh file exported using the STEPS-CUBIT supporting toolkit, can also be the ShadowMesh object itself.

RETURNS:

mesh, nodeproxy, tetproxy, triproxy

mesh: The STEPS TetMesh object
nodeproxy: Element Map for nodes
tetproxy: Element Map for tetrahedrons
triproxy: Element Map for triangles

IMPORTANT NOTICE:

User is recommanded to save the tetmesh objects using the saveTetmesh() method and recreate the objects from the saved files, instead of creating the objects via the importing functions each time, if the tetmesh objects are intented to be used in multiple simulations. Since the importing functions require a massive amount of time to create the Tetmesh object, comparing to the loadTetmesh() method.

importGmsh(filename, scale, verbose=False)[source]

Read a Gmsh-formated mesh file, return the created steps.geom.Tetmesh object, the element mapping for nodes, tetraedrons and triangles.

PARAMETERS:

filename: the Abaqus filename (or path) including any suffix.

scale: LENGTH scale from the importing mesh to real geometry. e.g. a radius of 10 in the importing file to a radius of 1 micron in STEPS, scale is 1e-7.

RETURNS:

mesh, nodeproxy, tetproxy, triproxy

mesh: The STEPS TetMesh object

nodeproxy: Element Map for nodes

tetproxy: Element Map for tetrahedrons

triproxy: Element Map for triangles

IMPORTANT NOTICE:

User is recommanded to save the tetmesh objects using the saveTetmesh() method and recreate the objects from the saved files, instead of creating the objects via the importing functions each time, if the tetmesh objects are intented to be used in multiple simulations. Since the importing functions require a massive amount of time to create the Tetmesh object, comparing to the loadTetmesh() method.

importVTK(filename, scale, verbose=False)[source]

Read a VTK-formated mesh file, return the created steps.geom.Tetmesh object, the element mapping for nodes, tetraedrons and triangles.

PARAMETERS:

filename: the VTK filename (or path) including any suffix.

scale: LENGTH scale from the importing mesh to real geometry. e.g. a radius of 10 in the importing file to a radius of 1 micron in STEPS, scale is 1e-7.

RETURNS:

mesh, nodeproxy, tetproxy, triproxy

mesh: The STEPS TetMesh object

nodeproxy: Element Map for nodes

tetproxy: Element Map for tetrahedrons

triproxy: Element Map for triangles

IMPORTANT NOTICE:

User is recommanded to save the tetmesh objects using the saveTetmesh() method and recreate the objects from the saved files, instead of creating the objects via the importing functions each time, if the tetmesh objects are intented to be used in multiple simulations. Since the importing functions require a massive amount of time to create the Tetmesh object, comparing to the loadTetmesh() method.

saveMesh(pathname, tetmesh)[source]

Save a STEPS Tetmesh in an XML file

This file stores the basic information about the mesh which tends to be common information for any software that supports tetrahedral meshes.

NODES are stored by cartesian coordinates.
TRIANGLES are stored by the indices of their 3 nodes.
TETRAHEDRONS are stored by the indices of their 4 nodes.

The XML file also stores infomation about any compartments or patches created in STEPS (class steps.geom.TmComp steps.geom.TmPatch respectively).

COMPARTMENT(S) are stored by:
- their string identification.
- a list of any volume systems added to the compartment at time of saving.
- a list of tetrahedrons belonging to the compartment
PATCH(ES) are stored by:
- their string identification.
- a list of any surface systems added to the patch at time of saving.
- the inner compartment id.
- the outer compartment id (if it exists).
- a list of trianlges belonging to this patch.

PARAMETERS:
pathname:

the root of the path to store the files.

e.g. ‘meshes/spine1’ will save data in /meshes/spine1.xml
tetmesh:

A valid STEPS Tetmesh object (of class steps.geom.Tetmesh). This mesh can be made in a variety of ways, e.g. to save a mesh loaded from tetgen:
>>> import meshio
>>> ### Use cubit script to create steps.geom.Tetmesh object from tetgen output file ###
>>> mymesh = meshio.readTetgen(tetgenfilename)
>>> ### Save this mesh in XML (and ASCII) format for quick-loading in future ###
>>> meshio.saveMesh('/meshes/spine1', mymesh[0])

loadMesh(pathname, scale=1, strict=False)[source]

Load a mesh in STEPS from the XML file.

PARAMETERS:

pathname: the root of the path where the file(s) are stored. e.g. with ‘meshes/spine1’ this function will look for the file /meshes/spine1.xml
scale: optionally rescale the mesh on loading by given factor.
strict: apply strict(-er) checking to the input XML.

RETURNS: A tuple (mesh, comps, patches)

mesh The STEPS Tetmesh object (steps.geom.Tetmesh)
comps A list of any compartment objects (steps.geom.TmComp) from XML file
patches A list of any patches objects (steps.geom.TmPatch) from XML file