EnSight Python Ansys Dynamic Reporting API#

This API is integrated into the EnSight Python interpreter. It can be accessed via the nexus module and can only be accessed from within the Python interpreter embedded in EnSight. The alternative External Python API can be used from within EnSight or from an EnSight cpython interpreter running outside of EnSight.

From inside of a running EnSight session, one can access the module like this:

from ensight.core import nexus

nexus module#

This module is the root of the EnSight Ansys Dynamic Reporting API.

Methods#

version_float = nexus.version()

Return the version of the Ansys Dynamic Reporting framework. 0.0 means the Ansys Dynamic Reporting framework could be found.

The nexus module provides several sub modules.

nexus.ReportServer module#

The ReportServer module controls the connection to an ADR Nexus server. Most operations in the nexus module use the server connection specified by this module. The server instance is a singleton for the current EnSight session.

Class Methods#

nexus.ReportServer.set_URL("http://localhost:8000")
nexus.ReportServer.set_username("ensight")
nexus.ReportServer.set_password("cei")

Specifies what server to which to connect the current session.

url = nexus.ReportServer.get_URL()
username = nexus.ReportServer.get_username()
password = nexus.ReportServer.get_password()

Retrieves the current session configuration.

server_version_float = nexus.ReportServer.validate()

Attempts to connect to the database and verifies that the server connection specifications are valid. It returns the version of the nexus server API that the server is using. Note: this method will throw an exception on encountering an error.

has_database_url = nexus.ReportServer.valid_database()

This method checks to see if a database url has been set. It returns True if a url has been set. It does not verify that the connection and username, password is valid.

success = nexus.ReportServer.launch_local_server(directory,
                                                 port=8000,
                                                 connect=False,
                                                 terminate_on_python_exit=False)

Launches an instance of the nexus report server using the SQLite database and media directory found in the directory included in the arguments. The listening port may be set via the port keyword. It is also legal to specify the port as None. In this case, nexus will find an unused port and assign it automatically. If the connect keyword is True, once the server is launched, the nexus.ReportServer server connection will be connected to the new server. Finally, if terminate_on_python_exit is set to True and EnSight terminates for any reason before stop_local_server() is called, the server will be stopped automatically.

nexus.ReportServer.stop_local_server()

Stops a local instance of a nexus report server. The specific server is the one currently specified by the ReportServer URL, username and password. This method will have no effect on a server that is using a database other than SQLite.

success = nexus.ReportServer.create_local_database(directory)

Creates a new, empty database in the directory passed as an argument. The call will generate an SQLite database and a media subdirectory in the specified directory. Note: the directory should be empty. It is not legal to place two databases in the same directory.

nexus.ReportItemSourceInterface module#

The ReportItemSourceInterface provides the methods needed to create data items and push them into the database.

Methods#

session = nexus.ReportItemSourceInterface.getSession()

Returns the current ReportSession object for this EnSight session. Note: if the current session has been modified since the last save, calling this method will cause the session to be saved to the database.

dataset = nexus.ReportItemSourceInterface.getDataset()

Returns the current ReportDataset object for this EnSight session. Note: if the current dataset has been modified since the last save, calling this method will cause the session to be saved to the database.

item = nexus.ReportItemSourceInterface.createItem(name, source="", sequencenum=0)

Creates a new ReportItem object. The name of the object should be a string and the source should be a string that describes the source of the item (it is often a Python namespace). This object has not yet been saved in the database. The sequence number allows multiple objects with the same name and namespace to have a sequential index number.

nexus.ReportItemSourceInterface.saveItem(item)

Saves an item to the database. Once an item has been created using createItem(), it can be saved to the database using this method. Note: this method may save the associated ReportDataset and/or ReportSession if they have not yet been saved to the database.

nexus.ReportTriggerInterface module#

The ReportTriggerInterface provides the methods needed to operate with triggers that have been defined in this session.

Methods#

triggers = nexus.ReportTriggerInterface.readTriggerFile(filename, server=None)

Reads a report trigger file (.rptt file written by the report trigger editor) and returns a list of trigger instances (class ReportTriggerInterface) from the file. If server is specified and the file contains server information, the server instance will be updated accordingly.

General objects used in the nexus API#

The core nexus API exposes a number of instances of other object classes. Several of these classes are documented here.

ReportDataset object#

This object represents the information stored in the database for the current dataset. By default, this object will track the current case automatically. It is re-evaluated when a new item is created.

Data members#

  • GUID - by default, this string is set from ensight.objs.core.CURRENTCASE[0].UUID

  • filename - the filename of the current case

  • dirname - the directory name of the current case

  • reader - the reader used to load the current case

  • numparts - the number of ENS_LPART objects in the current case

  • numelements - the number of potential elements in the current case

Methods#

item.set_tags(tagstring)

Set the tags for the dataset to the passed string. Multiple tags are space-separated.

ReportSession object#

This object represents the information stored in the database for the current session. It is initialized at startup to a singleton for the session.

Data members#

  • GUID - by default, this string is set from ensight.objs.core.UUID

  • date - date/time when the session started (datetime.datetime.now(pytz.utc))

  • hostname - the hostname for the current session

  • version - the version of EnSight for this session (e.g. '10.2.0(b)')

  • platform - the platform on which the client is running (e.g. 'win64')

  • application - the name of the application running this session ('EnSight' by default)

Methods#

item.set_tags(tagstring)

Set the tags for the session to the passed string. Multiple tags are space-separated.

ReportItem object#

The report item contains all of the information for a given data item. This class should not be created directly, use nexus.ReportItemSourceInterface.createItem() to create these objects.

Data members#

  • GUID - by default, this string is set via ensight.objs.core.generate_uuid()

  • session - a reference to the current session

  • dataset - a reference to the current dataset

  • sequencenum - the sequence number for this object

  • date - the date/time of this object creation

  • sourcename - the namespace of the class that generated this object

  • name - the name of the object

Methods#

item.set_payload_string(string)

Set the item type to a string and the value to the string argument.

item.set_payload_html(string)

Set the item type to HTML and the value to the string argument.

item.set_payload_table_values(array, rowlbls=None, collbls=None, title=None)

Set the item type to table. Array should be a numpy 2D array of floats. Rowlbls is a list of strings that should serve as labels for the rows. Collbls is a list of strings that should serve as labels for the columns. Title is a string that should be used as a title for the array (using when in plotted mode).

d = {'array': a, 'rowlbls': rowlbls, 'collbls': collbls, 'title': title}
item.set_payload_table(d)

Similar to set_payload_table_values except that a dictionary is passed that includes all of the parameters:

item.set_payload_image(img)

Set the payload to an image. img can be an instance of a QImage() object, an enve.image object or the in-memory representation of a png or jpeg file as a string (e.g. f = open("file.png","rb") img = f.read()).

item.set_payload_animation("filename.mp4")

Set the payload to a movie file in .mp4 format. The filename is passed to the method.

item.set_payload_scene(filename.csf)

Set the payload to a geometry scene file in .csf format. The filename is passed to the method.

item.set_payload_scene_capture(alltimesteps=False)

Set the payload to the current EnSight geometry. By default, only the current timestep is saved. Setting alltimesteps to True will save all timesteps into the geometry item.

item.set_payload_file(filename)

Set the payload to the context of a general file. The filename is passed to the method.

item.set_tags(tagstring)

Set the tags for the item to the passed string. Multiple tags are space-separated.

item.get_tags()

Returns the tags string for this object. Multiple tags are space-separated.

item.add_tag(tag, value=None)

Adds a tag to the current tag string. If no value is passed, the simple tag string is added to the tags string. If a value is specified, a string of the form tag=value will be added to the tag string.

item.rem_tag(tag)

Remove the tag (and any potential associated value) from the current tag string.