Examples from the cheat sheet

doc/source/examples_source/00-basic/00-launch-reporting-service.py

@@ -0,0 +1,52 @@
+"""
+.. _ref_launch_reporting_service:
+
+Launching the Ansys Dynamic Reporting Service
+=============================================
+
+To launch the service, provide an Ansys installation directory as a string.
+You can provide an existing, empty, directory if you intend to create a database.
+
+.. note::
+   This example assumes that you have a local Ansys installation.
+
+"""
+
+import ansys.dynamicreporting.core as adr
+
+db_dir = "C:\\tmp\\my_local_db_directory"
+ansys_ins = "C:\\Program Files\\Ansys Inc\\v241"
+
+adr_service = adr.Service(ansys_installation=ansys_ins, db_directory=db_dir)
+
+
+###############################################################################
+# Starting the Service
+# ~~~~~~~~~~~~~~~~~~~~
+# Once a `Service` object has been created, it must be started. It can be
+# similarly stopped.
+#
+
+session_guid = adr_service.start(create_db=True)
+
+# To stop the service
+adr_service.stop()
+
+###############################################################################
+# Connecting to a remote Service
+# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+# You may need to connect to a service that is already running. To do so create
+# a Service object, as before, but leave off the database argument and this time,
+# call the `connect` method and provide connection details, including any
+# credentials required. If no username and password were set when creating the
+# database, you can leave these fields empty and the default values will be
+# used.
+#
+
+ansys_ins = r"C:\Program Files\Ansys Inc\v241"
+adr_service = adr.Service(ansys_installation=ansys_ins)
+adr_service.connect(url="http://localhost:8000", username="user", password="p455w0rd")
+
+# To stop the service
+# sphinx_gallery_thumbnail_path = '_static/00_create_db_0.png'
+adr_service.stop()

doc/source/examples_source/00-basic/00-create_db.py → doc/source/examples_source/00-basic/01-create_db.py

@@ -1,8 +1,8 @@
 """
 .. _ref_createdb:
 
-Create a database
-=================
+Create a database and populate it
+=================================
 
 This example shows how to use PyDynamicReporting to create an Ansys
 Dynamic Reporting service, create a database for this service, and

doc/source/examples_source/00-basic/01-connect.py → doc/source/examples_source/00-basic/02-connect.py

@@ -58,7 +58,7 @@
 # ---------------------------------
 #
 # Now that you have a running Ansys Dynamic Reporting service, create a
-# second instance of the ``Reporting`` class and use it to
+# second instance of the ``Service`` class and use it to
 # connect to the database. Visualize the default report.
 
 connected_s = adr.Service()

doc/source/examples_source/00-basic/04-set-plot-properties.py

@@ -0,0 +1,74 @@
+"""
+.. _ref_set_plot_properties:
+
+How to set plot properties
+==========================
+
+When working with a table, you can turn it into a plot by specifying
+the plot type through the `plot` property. Once a table is converted
+you can alter all sorts of plot properties by accessing properties on
+the item object.
+
+.. note::
+   This example assumes that you have a local Ansys installation.
+
+Initially, you must create and start a session as per other examples.
+
+"""
+
+###############################################################################
+# Start an Ansys Dynamic Reporting service
+# ----------------------------------------
+#
+# Start an Ansys Dynamic Reporting service on a new
+# database. The path for the database directory must be to an empty directory.
+#
+
+import numpy as np
+
+import ansys.dynamicreporting.core as adr
+
+db_dir = "C:\\tmp\\new_database"
+adr_service = adr.Service(db_directory=db_dir)
+session_guid = adr_service.start(create_db=True)
+
+###############################################################################
+# Create a simple table
+# ---------------------
+#
+# Start by creating a simple table and visualizing it. Create a table
+# with 5 columns and 2 rows.
+#
+
+my_table = adr_service.create_item(obj_name="Table")
+my_table.table_dict["rowlbls"] = ["Row 1", "Row 2"]
+my_table.item_table = np.array(
+    [["1", "2", "3", "4", "5"], ["1", "4", "9", "16", "25"]], dtype="|S20"
+)
+
+###############################################################################
+# Once you have created a table, set it to be a plot by changing
+# its properties, and then you can set other properties.
+#
+
+# Set visualization to be plot instead of table
+my_table.plot = "line"
+
+# Set X axis and axis formatting
+my_table.xaxis = "Row 1"
+my_table.format = "floatdot1"
+
+###############################################################################
+# Properties can also be inspected this way.
+#
+
+print(my_table.type)
+
+# Close the service
+# -----------------
+#
+# Close the Ansys Dynamic Reporting service. The database with the items that
+# were created remains on disk.
+
+# sphinx_gallery_thumbnail_path = '_static/00_create_db_0.png'
+adr_service.stop()

doc/source/examples_source/00-basic/05-explore-plot-properties.py

@@ -0,0 +1,98 @@
+"""
+.. _ref_all_plot_properties:
+
+Explore plot properties
+=======================
+
+When working with a table, you can turn it into a
+plot by specifying the plot type through the `plot` property.
+This example demonstrates a variety of the possible plot
+properties available.
+
+.. note::
+   This example assumes that you have a local Ansys installation.
+
+Initially, create and start a session as per other examples.
+
+"""
+
+###############################################################################
+# Start an Ansys Dynamic Reporting service
+# ----------------------------------------
+#
+# Start an Ansys Dynamic Reporting service on a new
+# database. The path for the database directory must be to an empty directory.
+#
+
+import numpy as np
+
+import ansys.dynamicreporting.core as adr
+
+db_dir = "C:\\tmp\\new_database"
+adr_service = adr.Service(db_directory=db_dir)
+session_guid = adr_service.start(create_db=True)
+
+###############################################################################
+# Create a simple table
+# ---------------------
+#
+# Start by creating a simple table and visualizing it. Create a table
+# with 5 columns and 2 rows.
+#
+
+my_table = adr_service.create_item(obj_name="Table")
+my_table.table_dict["rowlbls"] = ["Row 1", "Row 2"]
+my_table.item_table = np.array(
+    [["1", "2", "3", "4", "5"], ["1", "4", "9", "16", "25"]], dtype="|S20"
+)
+
+###############################################################################
+# Once you have created a table, set it to be a plot by changing
+# its properties, and then you can set other properties.
+#
+
+# Set visualization to be plot instead of table
+my_table.plot = "line"
+
+# Set X axis and axis formatting
+my_table.xaxis = "Row 1"
+my_table.format = "floatdot1"
+
+###############################################################################
+# Some rules on properties
+# ------------------------
+# - If a property is not relevant to a plot and it is changed, nothing will happen
+# - Plots are not dynamically updated. Subsequent `visualize` calls are needed
+# - Plots can have `visualize()` called repeatedly without exhausting the object
+#
+
+my_table.line_color = "black"
+# This won't appear on our 2D plot or affect its output
+my_table.zaxis = "z-axis"
+my_table.visualize()
+
+# Sets the x-axis limits and similar patterns work for yrange and zrange.
+my_table.xrange = [0, 3]
+my_table.visualize()
+
+###############################################################################
+# Key properties
+# --------------
+# A few key properties are listed below as well as what they do, to get you started.
+#
+# - `xtitle`, `ytitle`, `ztitle`, `palette_title` - set the axis, and colorbar, labels
+# - `xrange`, `yrange, `zrange`, `palette_range` - set the axes amd colorbar limits
+# - `plot_title` - set the plot title
+# - `line_marker` - set the marker of scatter data, defaults to `circle`.
+# - `line_error_bars` - set y-axis error bars. Other axes are not available.
+# - `width`, `height` - dimensions of chart in pixels
+#
+
+# Close the service
+# -----------------
+#
+# Close the Ansys Dynamic Reporting service. The database with the items that
+# were created remains on disk.
+
+# sphinx_gallery_thumbnail_path = '_static/00_create_db_0.png'
+adr_service.stop()

doc/source/examples_source/00-basic/06-create-report-templates.py

@@ -0,0 +1,77 @@
+"""
+.. _ref_create_report_templates:
+
+Creating report templates
+=========================
+
+Templates are used to specify how the final report will be organised. They
+can be nested to describe the layout of subsections in greater detail.
+
+.. note::
+   This example assumes that you have a local Ansys installation.
+
+Initially, create and start a session as per other examples.
+
+"""
+
+###############################################################################
+# Start an Ansys Dynamic Reporting service
+# ----------------------------------------
+#
+# Start an Ansys Dynamic Reporting service on a new
+# database. The path for the database directory must be to an empty directory.
+# Get the serverobj property from the service. This property will be used to create the
+# template.
+#
+
+import ansys.dynamicreporting.core as adr
+
+db_dir = "C:\\tmp\\my_local_db_directory"
+ansys_ins = "C:\\Program Files\\Ansys Inc\\v241"
+adr_service = adr.Service(ansys_installation=ansys_ins, db_directory=db_dir)
+session_guid = adr_service.start(create_db=True)
+server = adr_service.serverobj
+
+
+###############################################################################
+# Create a template
+# ~~~~~~~~~~~~~~~~~~
+# The template is a plan of how ADR items will be presented in the final report.
+# The contents of sections is specified by filters that query the tags of items
+# in the database.
+#
+
+
+template_0 = server.create_template(name="My Report", parent=None, report_type="Layout:basic")
+
+server.put_objects(template_0)
+
+###############################################################################
+# Nesting templates
+# ~~~~~~~~~~~~~~~~~
+# Templates can be nested to describe layouts within a section, with the topmost template
+# being the report itself.
+#
+# Filters are composed of strings in a common format. The format is explained in more detail
+# on this page [Query Expressions](https://ansyshelp.ansys.com/public/account/secured?returnurl=/Views/Secured/corp/v251/en/adr_ug/adr_ug_query_expressions.html?q=query%20expression).
+#
+
+template_1 = server.create_template(name="Intro", parent=template_0, report_type="Layout:panel")
+template_1.set_filter("A|i_type|cont|html,string;")
+
+server.put_objects(template_1)
+server.put_objects(template_0)
+template_2 = server.create_template(name="Plot", parent=template_0, report_type="Layout:panel")
+template_2.set_filter("A|i_type|cont|table;")
+
+server.put_objects(template_2)
+server.put_objects(template_0)
+
+# Close the service
+# -----------------
+#
+# Close the Ansys Dynamic Reporting service. The database with the items that
+# were created remains on disk.
+
+# sphinx_gallery_thumbnail_path = '_static/00_create_db_0.png'
+adr_service.stop()