Archive Class and Functions#

class ansys.mapdl.reader.archive.Archive(filename, read_parameters=False, parse_vtk=True, force_linear=False, allowable_types=None, null_unallowed=False, verbose=False, name='', read_eblock=True)

Read a blocked ANSYS archive file or input file.

Reads a blocked CDB file and optionally parses it to a vtk grid. This can be used to read in files written from MAPDL using the CDWRITE command or input files ('.dat') files written from ANSYS Workbench.

Write the archive file using CDWRITE, DB, archive.cdb

Parameters:

  • filename (string, pathlib.Path) – Filename of block formatted cdb file

  • read_parameters (bool, optional) – Optionally read parameters from the archive file. Default False.

  • parse_vtk (bool, optional) – When True, parse the raw data into to VTK format.

  • force_linear (bool, optional) – This parser creates quadratic elements if available. Set this to True to always create linear elements. Defaults to False.

  • allowable_types (list, optional) –

    Allowable element types. Defaults to all valid element types in ansys.mapdl.reader.elements.valid_types

    See help(ansys.mapdl.reader.elements) for available element types.

  • null_unallowed (bool, optional) – Elements types not matching element types will be stored as empty (null) elements. Useful for debug or tracking element numbers. Default False.

  • verbose (bool, optional) – Print out each step when reading the archive file. Used for debug purposes and defaults to False.

  • name (str, optional) – Internally used parameter used to have a custom __repr__.

  • read_eblock (bool, default: True) – Read the element block.

Examples

>>> from ansys.mapdl import reader as pymapdl_reader
>>> from ansys.mapdl.reader import examples
>>> hex_beam = pymapdl_reader.Archive(examples.hexarchivefile)
>>> print(hex_beam)
ANSYS Archive File HexBeam.cdb
  Number of Nodes:              40
  Number of Elements:           321
  Number of Element Types:      1
  Number of Node Components:    2
  Number of Element Components: 2

Print the node array

>>> hex_beam.nodes
array([[0.  , 0.  , 0.  ],
       [1.  , 0.  , 0.  ],
       [0.25, 0.  , 0.  ],
       ...,
       [0.75, 0.5 , 3.5 ],
       [0.75, 0.5 , 4.  ],
       [0.75, 0.5 , 4.5 ]])

Read an ANSYS workbench input file

>>> my_archive = pymapdl_reader.Archive('C:\Users\user\stuff.dat')

Notes

This class only reads EBLOCK records with SOLID records. For example, the record EBLOCK,19,SOLID,,3588 will be read, but EBLOCK,10,,,3588 will not be read. Generally, MAPDL will only write SOLID records and Mechanical Workbench may write SOLID records. These additional records will be ignored.

property filename: str

String form of the filename. This property is read-only.

property grid

Return a pyvista.UnstructuredGrid of the archive file.

Examples

>>> from ansys.mapdl import reader as pymapdl_reader
>>> from ansys.mapdl.reader import examples
>>> archive = pymapdl_reader.Archive(examples.hexarchivefile)
>>> archive.grid
UnstructuredGrid (0x7ffa237f08a0)
  N Cells:      40
  N Points:     321
  X Bounds:     0.000e+00, 1.000e+00
  Y Bounds:     0.000e+00, 1.000e+00
  Z Bounds:     0.000e+00, 5.000e+00
  N Arrays:     13
property parameters

Parameters stored in the archive file

Examples

>>> from ansys.mapdl import reader as pymapdl_reader
>>> from ansys.mapdl.reader import examples
>>> archive = pymapdl_reader.Archive(examples.hexarchivefile,
                                     read_parameters=True)
>>> archive.parameters
{}
property pathlib_filename: Path

Return the pathlib.Path version of the filename. This property can not be set.

plot(off_screen: bool | None = None, full_screen: bool | None = None, screenshot: str | bool | None = None, interactive: bool = True, cpos: CameraPositionOptions | None = None, window_size: list[int] | None = None, show_bounds: bool = False, show_axes: bool | None = None, notebook: bool | None = None, background: ColorLike | None = None, text: str = '', return_img: bool = False, eye_dome_lighting: bool = False, volume: bool = False, parallel_projection: bool = False, jupyter_backend: JupyterBackendOptions | None = None, return_viewer: bool = False, return_cpos: bool = False, jupyter_kwargs: dict | None = None, theme: Theme | None = None, anti_aliasing: Literal['ssaa', 'msaa', 'fxaa'] | bool | None = None, zoom: str | float | None = None, border: bool = False, border_color: ColorLike = 'k', border_width: float = 2.0, ssao: bool = False, **kwargs)

Plot a PyVista, numpy, or vtk object.

Added in version 0.47: plot can be invoked with the shell command:

pyvista plot <files> --screenshot output.png --off-screen

Run pyvista plot --help for more details on available parameters.

Note

Providing multiple files renders them inside the same window.

Parameters:

var_item (pyvista.DataSet) – See Plotter.add_mesh for all supported types.

off_screenbool, optional

Plots off screen when True. Helpful for saving screenshots without a window popping up. Defaults to the global setting pyvista.OFF_SCREEN.

full_screenbool, default: pyvista.plotting.themes.Theme.full_screen

Opens window in full screen. When enabled, ignores window_size.

screenshotstr | bool, optional

Saves screenshot to file when enabled. See: Plotter.screenshot(). Default False.

When True, takes screenshot and returns numpy array of image.

interactivebool, default: pyvista.plotting.themes.Theme.interactive

Allows user to pan and move figure.

cposCameraPositionOptions, optional

List of camera position, focal point, and view up. See the pyvista.Plotter.camera_position for concrete examples on how to use this parameter and Cameras for a detailed documentation on pyvista.Camera.

window_sizelist[int], default: pyvista.plotting.themes.Theme.window_size

Window size in pixels.

show_boundsbool, default: False

Shows mesh bounds when True.

show_axesbool, default: pyvista.plotting.themes._AxesConfig.show

Shows a vtk axes widget.

notebookbool, default: pyvista.plotting.themes.Theme.notebook

When True, the resulting plot is placed inline a jupyter notebook. Assumes a jupyter console is active.

backgroundColorLike, default: pyvista.plotting.themes.Theme.background

Color of the background.

textstr, optional

Adds text at the bottom of the plot.

return_imgbool, default: False

Returns numpy array of the last image rendered.

eye_dome_lightingbool, optional

Enables eye dome lighting.

volumebool, default: False

Use the Plotter.add_volume() method for volume rendering.

parallel_projectionbool, default: False

Enable parallel projection.

jupyter_backendJupyterBackendOptions, optional

Jupyter notebook plotting backend to use. See available documentation at pyvista.set_jupyter_backend() to see all valid values for this parameter along with a detailed documentation.

Defaults to pyvista.plotting.themes.Theme.jupyter_backend

return_viewerbool, default: False

Return the jupyterlab viewer, scene, or display object when plotting with jupyter notebook.

return_cposbool, default: False

Return the last camera position from the render window when enabled. Defaults to value in theme settings.

jupyter_kwargsdict, optional

Keyword arguments for the Jupyter notebook plotting backend. See Customize Trame toolbar for an example using this keyword.

themepyvista.plotting.themes.Theme, optional

Plot-specific theme.

anti_aliasingLiteral[‘ssaa’, ‘msaa’, ‘fxaa’] | bool, optional

Enable or disable anti-aliasing. If True, uses "msaa". If False, disables anti_aliasing. If a string, should be one of the following:

  • "ssaa" - Super-Sample Anti-Aliasing

  • "msaa" - Multi-Sample Anti-Aliasing

  • "fxaa" - Fast Approximate Anti-Aliasing

Defaults to pyvista.plotting.themes.Theme.anti_aliasing

zoomfloat | str, optional

Camera zoom. Either 'tight' or a float. A value greater than 1 is a zoom-in, a value less than 1 is a zoom-out. Must be greater than 0.

borderbool, default: False

Draw a border around each render window.

border_colorColorLike, default: “k”

Either a string, rgb list, or hex color string. For example:

  • color='white'

  • color='w'

  • color=[1.0, 1.0, 1.0]

  • color='#FFFFFF'

border_widthfloat, default: 2.0

Width of the border in pixels when enabled.

ssaobool, optional

Enable surface space ambient occlusion (SSAO). See Plotter.enable_ssao() for more details.

**kwargsdict, optional

See pyvista.Plotter.add_mesh() for additional options.

Returns:

  • cpos (list) – List of camera position, focal point, and view up. Returned only when return_cpos=True or set in the default global or plot theme. Not returned when in a jupyter notebook and return_viewer=True.

  • image (np.ndarray) – Numpy array of the last image when either return_img=True or screenshot=True is set. Not returned when in a jupyter notebook with return_viewer=True. Optionally contains alpha values. Sized:

    • [Window height x Window width x 3] if the theme sets transparent_background=False.

    • [Window height x Window width x 4] if the theme sets transparent_background=True.

  • widget (ipywidgets.Widget) – IPython widget when return_viewer=True.

Examples

Plot a simple sphere while showing its edges.

>>> import pyvista as pv
>>> mesh = pv.Sphere()
>>> mesh.plot(show_edges=True)

Plot a volume mesh. Color by distance from the center of the ImageData. Note volume=True is passed.

>>> import numpy as np
>>> grid = pv.ImageData(dimensions=(32, 32, 32), spacing=(0.5, 0.5, 0.5))
>>> grid['data'] = np.linalg.norm(grid.center - grid.points, axis=1)
>>> grid['data'] = np.abs(grid['data'] - grid['data'].max()) ** 3
>>> grid.plot(volume=True)
property quality

Minimum scaled jacobian cell quality.

Negative values indicate invalid cells while positive values indicate valid cells. Varies between -1 and 1.

Examples

>>> from ansys.mapdl import reader as pymapdl_reader
>>> from ansys.mapdl.reader import examples
>>> archive = pymapdl_reader.Archive(examples.hexarchivefile)
>>> archive.quality
array([1., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1.,
       1., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1.,
       1., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1., 1.])
ansys.mapdl.reader.archive.save_as_archive(filename, grid, mtype_start=1, etype_start=1, real_constant_start=1, mode='w', enum_start=1, nnum_start=1, include_etype_header=True, reset_etype=False, allow_missing=True, include_surface_elements=True, include_solid_elements=True, include_components=True, exclude_missing=False)#

Writes FEM as an ANSYS APDL archive file.

This function supports the following element types:

  • vtk.VTK_HEXAHEDRON

  • vtk.VTK_PYRAMID

  • vtk.VTK_QUADRATIC_HEXAHEDRON

  • vtk.VTK_QUADRATIC_PYRAMID

  • vtk.VTK_QUADRATIC_TETRA

  • vtk.VTK_QUADRATIC_WEDGE

  • vtk.VTK_QUAD

  • vtk.VTK_TETRA

  • vtk.VTK_TRIANGLE

  • vtk.VTK_VOXEL

  • vtk.VTK_WEDGE

Will automatically renumber nodes and elements if the FEM does not contain ANSYS node or element numbers. Node numbers are stored as a point array "ansys_node_num", and cell numbers are stored as cell array "ansys_elem_num".

Parameters:

  • filename (str, pathlib.Path) – Filename to write archive file.

  • grid (pyvista.DataSet) – Any pyvista.DataSet that can be cast to a pyvista.UnstructuredGrid.

  • mtype_start (int, optional) – Material number to assign to elements. Can be set manually by adding the cell array “mtype” to the unstructured grid.

  • etype_start (int, optional) – Starting element type number. Can be manually set by adding the cell array “ansys_etype” to the unstructured grid.

  • real_constant_start (int, optional) – Starting real constant to assign to unset cells. Can be manually set by adding the cell array “ansys_real_constant” to the unstructured grid.

  • mode (str, optional) – File mode. See help(open)

  • enum_start (int, optional) – Starting element number to assign to unset cells. Can be manually set by adding the cell array “ansys_elem_num” to the unstructured grid.

  • nnum_start (int, optional) – Starting element number to assign to unset points. Can be manually set by adding the point array “ansys_node_num” to the unstructured grid.

  • include_etype_header (bool, optional) – For each element type, includes element type command (e.g. “ET, 1, 186”) in the archive file.

  • reset_etype (bool, optional) – Resets element type. Element types will automatically be determined by the shape of the element (i.e. quadradic tetrahedrals will be saved as SOLID187, linear hexahedrals as SOLID185). Default True.

  • include_surface_elements (bool, optional) – Includes surface elements when writing the archive file and saves them as SHELL181.

  • include_solid_elements (bool, optional) – Includes solid elements when writing the archive file and saves them as SOLID185, SOLID186, or SOLID187.

  • include_components (bool, optional) – Writes note components to file. Node components must be stored within the unstructured grid as uint8 or bool arrays.

  • exclude_missing (bool, default: False) – When allow_missing=True, write 0 instead of renumbering nodes. This allows you to exclude midside nodes for certain element types (e.g. SOLID186). Missing midside nodes are identified as -1 in the "ansys_node_num" array.

Examples

Write a pyvista.UnstructuredGrid to "archive.cdb".

>>> from ansys.mapdl import reader as pymapdl_reader
>>> from pyvista import examples
>>> grid = examples.load_hexbeam()
>>> pymapdl_reader.save_as_archive('archive.cdb', grid)
ansys.mapdl.reader.archive.write_nblock(filename, node_id, pos, angles=None, mode='w')#

Writes nodes and node angles to file.

Parameters:

  • filename (str or file handle) – Filename to write node block to.

  • node_id (np.ndarray) – ANSYS node numbers.

  • pos (np.ndarray) – Node coordinates.

  • angles (np.ndarray, optional) – Writes the node angles for each node when included.

  • mode (str, optional) – Write mode. Default 'w'.

ansys.mapdl.reader.archive.write_cmblock(filename, items, comp_name, comp_type, digit_width=10, mode='w')#

Writes a component block (CMBLOCK) to a file.

Parameters:

  • filename (str or file handle) – File to write CMBLOCK component to.

  • items (list or np.ndarray) – Element or node numbers to write.

  • comp_name (str) – Name of the component

  • comp_type (str) – Component type to write. Should be either ‘ELEMENT’ or ‘NODE’.

  • digit_width (int, optional) – Default 10

  • mode (str, optional) – Write mode. Default 'w'.