diff --git a/doc/source/examples_source/00-basic/00-launch-reporting-service.py b/doc/source/examples_source/00-basic/00-launch-reporting-service.py new file mode 100644 index 00000000..ad85a22c --- /dev/null +++ b/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() diff --git a/doc/source/examples_source/00-basic/00-create_db.py b/doc/source/examples_source/00-basic/01-create_db.py similarity index 98% rename from doc/source/examples_source/00-basic/00-create_db.py rename to doc/source/examples_source/00-basic/01-create_db.py index 095a22d9..43cd5a3e 100755 --- a/doc/source/examples_source/00-basic/00-create_db.py +++ b/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 diff --git a/doc/source/examples_source/00-basic/01-connect.py b/doc/source/examples_source/00-basic/02-connect.py similarity index 98% rename from doc/source/examples_source/00-basic/01-connect.py rename to doc/source/examples_source/00-basic/02-connect.py index 51194e4c..122e3256 100755 --- a/doc/source/examples_source/00-basic/01-connect.py +++ b/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() diff --git a/doc/source/examples_source/00-basic/02-plottype.py b/doc/source/examples_source/00-basic/03-plottype.py similarity index 100% rename from doc/source/examples_source/00-basic/02-plottype.py rename to doc/source/examples_source/00-basic/03-plottype.py diff --git a/doc/source/examples_source/00-basic/04-set-plot-properties.py b/doc/source/examples_source/00-basic/04-set-plot-properties.py new file mode 100644 index 00000000..6f39e117 --- /dev/null +++ b/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() diff --git a/doc/source/examples_source/00-basic/05-explore-plot-properties.py b/doc/source/examples_source/00-basic/05-explore-plot-properties.py new file mode 100644 index 00000000..d942e231 --- /dev/null +++ b/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() diff --git a/doc/source/examples_source/00-basic/06-create-report-templates.py b/doc/source/examples_source/00-basic/06-create-report-templates.py new file mode 100644 index 00000000..c2aace57 --- /dev/null +++ b/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()