User guide#

This section describes concepts that you need to know to use PyDynamicReporting.

Connected-service guides

API overview#

The PyDynamicReporting API has three main classes:

Service: Provides for starting and connecting to an Ansys Dynamic Reporting service. This class also provides for creating, querying, and deleting the database and for stopping an Ansys Dynamic Report service.
Item: Provides access to the items in the database and allows them to be modified.
Report: Provides access to and rendering of Report objects.

PyDynamicReporting supports creating and pushing these items into an Ansys Dynamic Reporting service:

Images
Animations
3D Scenes (AVZ file format supported)
Tables
Trees
Text (HTML and LaTeX file formats supported)
Files (generic file formats supported)

This code connects to a running Ansys Dynamic Reporting service and pushes an image item on a new session:

import ansys.dynamicreporting.core as adr

adr_service = adr.Service(ansys_installation=r"C:\Program Files\ANSYS Inc\v261")
ret = adr_service.connect(
    url="my_machine:8010", username="MyUsername", password="MyPassword"
)
first_image = adr_service.create_item()
first_image.item_image = "location\image\file.png"
first_image.visualize()

A rendering of the image object is embedded in the current interpreter. You can follow the same steps to create and visualize other types of items.

To get the URL corresponding to an item, use this attribute:

first_image.url()

Similarly, to get the iframe corresponding to an item, use this attribute:

first_image.get_iframe()

With the corresponding URL or iframe, you can embed the item visualization into any other app.

Note

If you want to update an image, all you need to do is redefine the item_image attribute. The Ansys Dynamic Reporting database is automatically updated.

Wrap long table text#

Service-mode table items support smart word wrapping. Set table_wrap_word to break long text at spaces or hyphens instead of in the middle of a word:

import numpy as np

table_item = adr_service.create_item(obj_name="Status table")
table_item.item_table = np.array(
    [["Run", "Long status message"], ["1", "Completed with warnings"]],
    dtype="|S64",
)
table_item.table_wrap_word = 1

Visualize an Ansys Dynamic reporting item#

PyDynamicReporting provides two main ways to visualize an item. The first is to visualize it standalone, as shown in the preceding code examples. The second is to visualize it together with all the other items that are present in the current Ansys Dynamic Reporting session.

Each time that you use the PyDynamicReporting start method to start an Ansys Dynamic Reporting service or the connect method to connect to one, you are connected to a specific session. Each session has its own GUID (globally unique identifier).

On the Ansys Dynamic Reporting object, you can execute the visualize_report method to visualize all items that are present in the session.

The following code embeds a widget in the app that you are running from. It shows that both items (image and text) have been created.

import ansys.dynamicreporting.core as adr

adr_service = adr.Service(ansys_installation=r"C:\Program Files\ANSYS Inc\v261")
ret = adr_service.connect(
    url="my_machine:8010", username="MyUsername", password="MyPassword"
)
first_image = adr_service.create_item()
first_image.item_image = "location\image\file.png"
first_text = adr_service.create_item()
first_text.item_text = "<h1>My Title</h1>This is the first example"
adr_service.visualize_report()

Connect to and query an existing Ansys Dynamic Reporting session#

You can start an Ansys Dynamic Reporting session in one Python interpreter and connect to it in a different interpreter or on a different machine by passing the session GUID as the parameter in the connect method.

This code starts an Ansys Dynamic Reporting session in the first interpreter:

import ansys.dynamicreporting.core as adr

adr_service = adr.Service(
    ansys_installation=r"C:\Program Files\ANSYS Inc\v261",
    db_directory=r"D:\tmp\test_pydynamicreporting",
    port=8010,
)
_ = adr_service.start()
session_guid = adr_service.session_guid

The session contains the GUID needed to connect to this session in a different interpreter or on a different machine.

This GUID is then copied and pasted into another interpreter as shown in this code:

import ansys.dynamicreporting.core as adr

adr_service = adr.Service(ansys_installation=r"C:\Program Files\ANSYS Inc\v261")
ret = adr_service.connect(url="http://localhost:8010", session=session_guid)

Once you are connected to the session, you can query its items:

all_items = adr_service.query()
only_images = adr_service.query(item_filter="A|i_type|cont|image|")

The query method takes a filter input that allows you to select the items to return. The query string follows the same structure as the queries described in Query Expressions

in the documentation for Ansys Dynamic Reporting.

To get a list of the existing report templates in the database, use the get_list_reports method:

all_reports = adr_service.get_list_reports()

To query the database for a specific report, use the get_report method:

my_report = adr_service.get_report(report_name="My Top Report")
my_report.visualize()

Export a connected report as static HTML#

Use export_html() to create an offline HTML bundle:

exported = my_report.export_html(
    directory_name=r"C:\reports\simulation-summary",
    query_params={"colormode": "dark"},
    item_filter="A|i_tags|cont|project=wing;",
    filename="index.html",
)

The high-level report API uses the product version reported by the connected ADR server. If you call the low-level Server.export_report_as_html() API with an explicit ansys_version, set it to the connected server’s version.

Diagnosing an export failure#

export_pdf(), export_html(), and export_browser_pdf() return False on failure instead of raising, so the specific reason is not visible unless you capture it. Each method logs the reason through the ADR logger (configure it with, for example, adr.Service(..., log_output="stdout")) and also raises it as a UserWarning, which you can catch even without configuring logging:

import warnings

with warnings.catch_warnings(record=True) as caught:
    warnings.simplefilter("always")
    exported = my_report.export_html(directory_name=r"C:\reports\summary")
if not exported:
    raise RuntimeError(str(caught[-1].message))

Backward compatibility with template generator scripts#

The template editor in Ansys Dynamic Reporting contains a feature for exporting a Python script to create report templates on the connected server with all their settings and properties and push these report templates to a new server. This script uses the low-level API for Ansys Dynamic Reporting, which preceded PyDynamicReporting.

A legacy script starts with these lines of code:

import cei
from template_editor import report_remote_server, report_objects

server = report_remote_server.Server("http://127.0.0.1:9528", "nexus", "cei")

Following these lines are a series of commands that describe the template names and properties.

To convert a legacy script to a report template for PyDynamicReporting, replace the preceding lines in the legacy script with these lines:

import ansys.dynamicreporting.core as adr

adr_service = adr.Service(ansys_installation=r"C:\Program Files\ANSYS Inc\v261")
ret = adr_service.connect(url="http://localhost:8010")
server = adr_service.serverobj

Everything else in the script remains the same.