API

The user interface of Paraqus is documented here as a reference for users who want to write their own scripts. Only public classes/methods are documented here.

ParaqusModel

class paraqus.ParaqusModel(element_tags, connectivity, element_types, node_tags, node_coords, **kwargs)

Paraqus representation of a finite element model.

The Paraqus model can be used to manipulate and export any finite element model as a set of VTK files.

Parameters:

element_tags (Sequence[int]) – Tags of all elements being part of the model. Tags have to be unique.
connectivity (Sequence[Sequence[int]]) – Connectivity list in the order defined for the element tags. The respective nodes have to be in order as defined for VTK cells.
element_types (Sequence[int]) – The VTK cell types for all elements in the order defined for the element tags.
node_tags (Sequence[int]) – Tags of all nodes being part of the model. Tags have to be unique.
node_coords (Sequence[Sequence[float]]) – Nodal coordinates in the order defined for the node tags. The coordinates can be defined in 1d-, 2d- or 3d-space as an array of shape (number of nodes, number of dimensions).
model_name (str, optional) – Name of the main model. In case of multiple frames or parts every Paraqus model should have the same model name. Default: 'MODEL NAME'.
part_name (str, optional) – Name of the part instance. Default: 'PART NAME'.
step_name (str, optional) – Name of the load step. Default: 'STEP NAME'.
frame_time (float, optional) – Current frame time. Default: 0.0.
source (ParaqusConstant, optional) – This is just for informational purpose and defines the source of the model, e.g. ABAQUS. Default: USER.

Variables:

model_name (str) – Name of the main model.
part_name (str) – Name of the part instance.
step_name (str) – Name of the load step.
frame_time (float) – Current frame time of the model frame.
source (ParaqusConstant) – This is a constant for informational purpose and describes the source of the model, e.g. ABAQUS or USER.
elements (ElementRepository) – A repository storing all information on elements, e.g. tags and element types.
nodes (NodeRepository) – Repository storing all information on nodes, e.g. tags and coordinates.
node_fields (NodeFieldRepository) – Repository storing all node fields.
element_fields (ElementFieldRepository) – Repository sotring all element fields.

Example

>>> import numpy as np
>>> from paraqus import ParaqusModel, BinaryWriter
>>>
>>> # Define the model parameters
>>> element_tags = np.array([1,2])
>>> connectivity = [np.array([1,2,3,4]),np.array([4,3,5])]
>>> element_types = np.array([9,5])
>>> node_tags = np.array([1,2,3,4,5])
>>> node_coords = np.array([[0,0],[1,0],[1,1],[0,1],[0.5,1.5]])
>>>
>>> # Create a new model
>>> model = ParaqusModel(element_tags,
>>>                      connectivity,
>>>                      element_types,
>>>                      node_tags,
>>>                      node_coords,
>>>                      model_name="foo",
>>>                      part_name="bar",
>>>                      step_name="foobar",
>>>                      frame_time=0.1)
>>>
>>> # Export model as VTK
>>> writer = BinaryWriter()
>>> writer.write(model)

add_element_group(group_name, element_tags)

Add an element group to the model.

The elements must have been added beforehand, this method just stores the information that the elements form a named group.

Parameters:

group_name (str) – Name of the group. Must be unique.
element_tags (Sequence[int]) – Integer tags of the elements in the group.

Return type:

None.

add_field(field_name, field_tags, field_values, field_position, field_type)

Add a field to the model.

The field will also be part of any exported VTK model.

Parameters:

field_name (str) – Name of the field.
field_tags (Sequence[int]) – Tags of the nodes or elements at which the field is stored.
field_values (Sequence[Sequence[float]]) – Values of the field in the order defined for the field tags. At nodes or elements that are not part of the field tags, the values will be set to NaN automatically.
field_position (ParaqusConstant) – A constant defining the storage position of the field, i.e. NODES or ELEMENTS.
field_type (ParaqusConstant) – A constant defining the field type, i.e. SCALAR, VECTOR or TENSOR.

Return type:

None.

add_node_group(group_name, node_tags)

Add a node group to the model.

The nodes must have been added beforehand, this method just stores the information that they form a named group.

Parameters:

group_name (str) – Name of the group. Must be unique.
node_tags (Sequence[int]) – Integer tags of the nodes in the group.

Return type:

None.

property element_fields: The repository storing the element field.

property elements: The ElementRepository of the model.

property frame_time: Current frame time of the model frame.

get_element_field(field_name)

Request an element field of a given name.

If there is no field found, None will be returned.

Parameters:: field_name (str) – Name of the requested element field.
Returns:: The requested field.
Return type:: Field

get_fields_by_type(field_type, field_position)

Return all fields of a specific type, e.g. of type SCALAR.

Fields stored at nodes as well as fields stored at elements can be returned.

Parameters:

field_type (ParaqusConstant) – Type of the field, i.e. TENSOR, VECTOR or SCALAR.
field_position (ParaqusConstant) – Position of the field, i.e. NODES or ELEMENTS.

Returns:

All fields that match the requested type and position.

Return type:

list[Field]

get_node_field(field_name)

Request a node field of a given name.

If there is no field found, None will be returned.

Parameters:: field_name (str) – Name of the requested node field.
Returns:: The requested field.
Return type:: Field

property model_name: The name of the main model.

property node_fields: The repository storing the node fields.

property nodes: The NodeRepository of the model.

property part_name: The name of the part instance.

property source: Source of the model, e.g. ABAQUS or USER.

split_model(number_of_pieces)

Split the model into number_of_pieces different parts.

The split is performed based on element numbers, so that the resulting model pieces are not necessarily continuous (i.e. they might have holes etc.).

Parameters:: number_of_pieces (int) – Number of parts the model will be split into.
Yields:: piece (ParaqusModel) – The resulting submodel for one piece including all fields and groups.

property step_name: The name of the load step.

Writers

class paraqus.AsciiWriter(output_dir='vtk_files', clear_output_dir=False, number_of_pieces=1)

Writer for the export of paraqus models to ASCII .vtu file format.

Parameters:

output_dir (str, optional) – Directory, where all exported VTK files will be stored. Default: 'vtk_files'.
clear_output_dir (bool, optional) – If True, the output directory will be cleared before exporting any files. Default: False.
number_of_pieces (int, optional) – Number of pieces each model will be split into. The default is 1.

Variables:

number_of_pieces (int) – Number of pieces each model will be split into.
output_dir (str) – The path to the folder where all VTK files will be stored.
fmt (ParaqusConstant) – This is a constant with value ASCII and is only used for informational purposes.

Example

>>> from paraqus import AsciiWriter
>>> writer = AsciiWriter(number_of_pieces=2)
>>> writer.write(random_paraqus_model)

property fmt: The type of the writer.

property number_of_pieces: Number of pieces each model will be split into.

write(model)

Write .vtu and .pvtu files for the model to disk.

Export a paraqus model to .vtu file format. In case the model shall be split into multiple pieces, aditionally, a .pvtu file is created. The file names are set automatically in dependence on the model parameters.

Parameters:: model (ParaqusModel) – The model that will be exported.
Returns:: file_path – If the model is exported as one piece, this is the file path of the .vtu file. If there are multiple pieces, it is the path to the corresponding .pvtu file.
Return type:: str

class paraqus.BinaryWriter(output_dir='vtk_files', clear_output_dir=False, number_of_pieces=1, encoding=<paraqus.constants.ParaqusConstant object>, header_type=<paraqus.constants.ParaqusConstant object>)

Writer for the export of paraqus models to binary .vtu file format.

Parameters:

output_dir (str, optional) – Directory, where all exported VTK files will be stored. Default: 'vtk_files'.
clear_output_dir (bool, optional) – If True, the output directory will be cleared before exporting any files. Default: False.
number_of_pieces (int, optional) – Number of pieces each model will be split into. Default: 1.
encoding (ParaqusConstant, optional) – The binary encoding used for data arrays. Currently supported are RAW and BASE64. Default: BASE64.
header_type (ParaqusConstant, optional) – The data type used for the headers of the binary data blocks. Currently supported are UINT32 and UINT64. Default: UINT64.

Variables:

number_of_pieces (int) – Number of pieces each model will be split into.
output_dir (str) – The path to the folder where all VTK files will be stored.
encoding (ParaqusConstant) – The binary encoding used for data arrays.
header_type (ParaqusConstant) – The data type used for the headers of the binary data blocks.
fmt (ParaqusConstant) – This is a constant with value BINARY and is only used for informational purposes.

Example

>>> from paraqus import BinaryWriter
>>> from paraqus.constants import RAW
>>> writer = BinaryWriter(number_of_pieces=2, encoding=RAW)
>>> writer.write(random_paraqus_model)

property encoding: The binary encoding used for data arrays.

property fmt: The type of the writer.

property header_type: The data type used for the headers of binary data blocks.

property number_of_pieces: Number of pieces each model will be split into.

write(model)

Write .vtu and .pvtu files for the model to disk.

Export a paraqus model to .vtu file format. In case the model shall be split into multiple pieces, aditionally, a .pvtu file is created. The file names are set automatically in dependence on the model parameters.

Parameters:: model (ParaqusModel) – The model that will be exported.
Returns:: file_path – If the model is exported as one piece, this is the file path of the .vtu file. If there are multiple pieces, it is the path to the corresponding .pvtu file.
Return type:: str

CollectionWriter

class paraqus.CollectionWriter(writer, collection_name)

Writer for the export of a collection of .pvtu or .vtu files.

This writer can be used as a context manager to generate a .pvd file.

Parameters:

writer (BinaryWriter or AsciiWriter) – The writer that is used to generate .pvtu and .vtu files.
collection_name (str) – The name of the collection. This is used for the name of the .pvd file.

Variables:

writer (BinaryWriter or AsciiWriter) – The writer that is used the generate .pvtu and .vtu files.
collection_name (str) – The name of the collection.

Example

>>> from paraqus import BinaryWriter, CollectionWriter
>>> vtu_writer = BinaryWriter()
>>> with CollectionWriter(vtu_writer, "my_collection") as writer:
>>>     writer.write(random_paraqus_model_frame_1)
>>>     writer.write(random_paraqus_model_frame_2)
>>>     writer.write(random_paraqus_model_frame_3)

write(model)

Write a ParaqusModel to a VTK file using the underlying writer.

Parameters:: model (ParaqusModel) – The model that will be converted to a VTK file.
Return type:: None.

OdbReader

The OdbReader class is only useable in the Abaqus Python interpreter.

class paraqus.abaqus.OdbReader(odb_path, model_name=None, instance_names=None, time_offset=0.0)

Reads an .odb file and exports selected results to a ParaqusModel.

Parameters:

odb_path (str) – Name of the underlying ODB.
model_name (str, optional) – Name of the model returned by the reader. When model_name is omitted, it is set based on odb_path. Default: None.
instance_names (Sequence[str], optional) – Instances that will be exported to individual models. If instance_names is omitted, all instances in the ODB will be exported. Default: None.
time_offset (float, optional) – Assume the simulation started at this time when exporting. Useful to create files in VTK format that are ordered in time from multiple ODBs. Default: 0.0.

Variables:

odb_path (str) – Path to the underlying ODB.
model_name (str) – Name of the model returned by the reader.
field_export_requests (list[FieldExportRequest]) – Contains one request per field that will be exported to VTK format.
group_export_requests (list[GroupExportRequest]) – Contains one request per node or element set that will be exported.
instance_names (list[str]) – Instances that will be exported to individual models.
time_offset (float) – Assume the simulation started at this time when exporting. Useful to create files in VTK format that are ordered in time from multiple ODBs.

Examples

>>> from paraqus.abaqus import OdbReader
>>> # Define the odb/model/instances that will be read
>>> reader = OdbReader(odb_path="example.odb",
>>>                    model_name="example model",
>>>                    instance_names=["instance-1", "instance-2"],
>>>                    )
>>> # Export the node field 'U' (displacements)
>>> reader.add_field_export_request("U", field_position="nodes")
>>> # Export the element set 'element set name' for 'instance-1'
>>> reader.add_set_export_request("element set name",
>>>                               set_type="elements",
>>>                               instance_name="instance-1")
>>> # Store the models for both instances in a list
>>> instance_models = list(reader.read_instances(step_name="Step-1",
>>>                                              frame_index=-1)
>>>                        )

add_field_export_request(field_name, **kwargs)

Request export of an output field.

Parameters:

field_name (str) – Abaqus identifier for the field, e.g. 'S' for stress.
**kwargs (dict[str, str or int]) – Additional parameters that will be passed to the underlying FieldExportRequest. See the documentation of class FieldExportRequest for possible options.

Return type:

None

add_set_export_request(set_name, set_type, instance_name=None)

Request that a node or element set is exported.

Parameters:

set_name (str) – Name of the set in the ODB.
set_type (str) – Type of the set. Valid values are 'nodes' or 'elements'.
instance_name (str, optional) – If instance_name is not None, look for an instance-level set in the ODB. Otherwise look for an assembly-level set. Default: None.

Return type:

None

add_surface_export_request(surface_name, surface_type, instance_name=None)

Request that a node or element set is exported.

Parameters:

surface_name (str) – Name of the surface in the ODB.
surface_type (str) – Type of the surface. Valid values are 'nodes' or 'elements'.
instance_name (str, optional) – If instance_name is not None, look for an instance-level surface in the ODB. Otherwise look for an assembly-level surface. Default: None.

Return type:

None

get_frame_indices(step_name, how='all')

Return the indices of frames with at least one requested field.

Parameters:

step_name (str) – Name of the step in the ODB.
how (str) – Whether to get frame indices where 'any' or 'all' fields have values. Default: 'all'.

Returns:

frame_indices – Indices of the frames with at least one requested field.

Return type:

list[int]

get_frame_time(step_name, frame_index)

Get the highest time value of any frame in the ODB.

The time_offset attribute specified for the reader is added to the value.

Parameters:

step_name (str) – Name of the step in Abaqus.
frame_index (int) – Index of the frame in the step in Abaqus.

Returns:

frame_time – The total time passed (includes time offset).

Return type:

float

get_number_of_frames(step_name)

Return the number of frames for a step in the underlying ODB.

The reader does NOT check that all output is available in each frame.

Parameters:: step_name (str) – Name of the step in the ODB.
Returns:: number_of_frames – Number of frames in the step, including the initial (0th) frame.
Return type:: int

read_instances(step_name, frame_index)

Read a frame from the underlying ODB.

Each instance is read separately and returns an individual ParaqusModel. Models are generated lazily, so memory-efficient iteration over the return values is possible.

Parameters:

step_name (str) – Name of the step in Abaqus.
frame_index (int) – Index of the frame in the step in Abaqus.

Yields:

model (ParaqusModel) – Model representing the geometry and output for one part instance at the step/frame.