Digital Twin for PI Data Infrastructure

Workbook
Table of contents
Pre-Lesson .............................................................................................................................................. 4
PI System Set up.................................................................................................................................. 4
Lesson 1. PI Digital Twin 101 ................................................................................................................... 5
Introduction ........................................................................................................................................ 5
AVEVA PI System ................................................................................................................................. 6
AVEVA Digital Twin ............................................................................................................................. 8
PI Digital Twin ..................................................................................................................................... 9
PI Digital Twin Best Practices ............................................................................................................ 15
Lesson 2. Asset Structure ...................................................................................................................... 17
Introduction ...................................................................................................................................... 17
Exercise – Equipment Hierarchy Brainstorming ............................................................................... 18
Asset Framework libraries for PI Digital Twin ................................................................................... 20
Exercise – Loading Libraries ............................................................................................................. 22
Containers ......................................................................................................................................... 25
Exercise – Creating Containers ......................................................................................................... 27
Primary Assets................................................................................................................................... 31
Exercise – Creating Primary Assets ................................................................................................... 32
Secondary Assets .............................................................................................................................. 33
Exercise – Creating Secondary Assets ............................................................................................... 34
Lesson 3. Accessories ............................................................................................................................ 36
Introduction ...................................................................................................................................... 36
Exercise – Flow rate – Simple Sensor Accessory ............................................................................... 42
Exercise – Pump Efficiency – Multi-variable Accessory .................................................................... 44
Exercise – Vibration Analysis ............................................................................................................ 46
Tuning analytics – key recommendations......................................................................................... 51
Exercise – Creating Assets in Bulk ..................................................................................................... 53
Notification configuration................................................................................................................. 56
Exercise – Tracking Efficiency excursions – Notification................................................................... 57
Exercise – Using PI Vision to Summarize “Children” Dynamically .................................................... 59
Exercise – PI Digital Twin Asset Overview in PI Vision ...................................................................... 65
Forecasting Library ............................................................................................................................ 66
Exercise – Forecasting ....................................................................................................................... 68
Exercise – Forecast in PI Vision ......................................................................................................... 73
Lesson 4. PI Digital Twin project execution .......................................................................................... 74
Project delivery considerations......................................................................................................... 74

2
 Element template configuration ....................................................................................................... 79
Event Frames configuration .............................................................................................................. 82
Lesson 5. AVEVA PI Digital Twin in the Cloud ....................................................................................... 84
Hybrid PI Data Infrastructure – Global and Secure ........................................................................... 84
Summary ............................................................................................................................................... 87
References ............................................................................................................................................ 89

3
Pre-Lesson
Before reading this sec on, please refer to the following course YouTube video:
What is PI Digital Twin and how will it help you? (promotional video)

Pre-requisites.

Comple on of the following are required for the successful results of this course:

- PI System Basics h ps://learning.osiso .com/pi-system-basics

- PI Asset Framework Basics h ps://learning.osiso .com/asset-framework-basics
- PI Vision Basics: h ps://learning.osiso .com/pi-vision-basics
- PI Vision Beyond the Basics: h ps://learning.osiso .com/pi-vision-beyond-the-basics

PI System Set up
This lab uses a simplified PI System including the PI Data Archive, PI Asset Framework, and PI Vision all
bundled together on one produc on server. Each student will have their own client machine to access
PI System Explorer remotely.

The servers of importance are:

 PISRV01
o PI Data Archive version 2018 SP3 Patch 4
o PI AF Server version 2018 SP3
o PI System Explorer version 2018 SP3 Patch 5
o AVEVA PI Vision Version 2022

4
Lesson 1. PI Digital Twin 101
Objectives

 Understand PI Digital Twin concept and its impact.

 Familiarize with best prac ces of implemen ng PI Digital Twin.

Introduction
In today's fast-paced and compe ve business landscape, the role of data in priori zing safety,
minimizing risk, and reducing down me is vital to success. Organiza ons across industries, from
manufacturing and construc on to healthcare and finance are increasingly recognizing that these
factors are not merely aspects of opera onal efficiency but cri cal components of sustainable success.

Implemen ng a comprehensive solu on to address and mi gate these issues should be a tangible
strategy for the benefit of organiza ons. As a part of this lab, we will introduce you to the PI Digital
Twin (PI DT) concept that could play a significant role in building this strategy. Without addi onal
coding, achieving reduc ons in manpower, cost savings, and scalability you will be shown how to
u lize the best out of the box func onality of the PI System by using pre-built library of Assets and
Accessories that can be also tailored to any customers’ needs.

All the described concepts in this learning course are a combina on of the latest AVEVA, ISA (standards
for Automa on) and ISO standards, and best prac ces from AVEVA systems engineers and solu on
architects that enhances agility into your PI System and take away duplicated content and excessive
labour.

5
 AVEVA PI System

- This sec on is a brief introduc on to AVEVA PI System, more detailed informa on could
- be found in respec ve PI System courses.

AVEVA PI System is the market leader in data management so ware for industrial opera ons. It is the
proven system of record for opera ons data in the power genera on and u li es, water, oil and gas,
mining and metals, pharmaceu cals, facili es, transporta on, food and beverage, and manufacturing
industries. Customers use PI System to collect and understand their opera ons data so they can
improve produc on processes, extend the life of valuable assets, reduce energy and water use, and
maintain health and safety.

The PI System is the digital backbone to unify and manage informa on which allows you to:
 Collect real- me data from any asset—including legacy, proprietary, remote, mobile, and IIoT
devices. Edge Data Store (EDS) is one of the op ons provided for data collec on (see picture
below).
 Store decades worth of data with sub-second granularity. Get immediate access to high-
fidelity historical, real- me, and predic ve data to keep cri cal opera ons running and
business insights flowing (AVEVA PI Server).
 Make raw data streams more meaningful and see the big picture by adding descrip ve labels
and metadata. Define data hierarchies that reflect your opera ng and repor ng
environments. Use a rich set of built-in analy cs func ons to easily perform simple or
advanced calcula ons (AVEVA PI Server).
 Easily create your own custom reports and views, so you can monitor processes and
troubleshoot on the spot. Quickly drill down into detailed data to see issues in an individual
asset.
 Deliver trustworthy, analysis-ready opera ons data to analy cs tools and machine learning
algorithms to derive new insights. Easily send data to the cloud with just a few clicks to start
collabora ng with analysts, data scien sts, and partners and service providers outside your
organiza on (former AVEVA Data Hub, now called Connect Data Services).

6
AVEVA PI Server is a collec on of so ware components and related so ware tools that are used to
store, manage, and enhance data. The two main components of the PI Server are the Data Archive
and the Asset Framework. Data Archive retrieves me-series data from adapters, connectors, and
interfaces and delivers the data in real me throughout the PI System. Asset Framework (AF) provides
context to me-series data with metadata that makes it easy to organize data in familiar categories.
On top on the Asset Framework, there is Asset Analy cs to enhance the raw data by performing
calcula ons, the Event frames to capture important events and no fica ons to deliver them. All of
these components work together as can be seen in the figure below.

7
 AVEVA Digital Twin
A digital twin is a virtual, real- me representa on of a physical asset, system, or process.

Whilst there is no single or uniform set of requirements, our experience at AVEVA has shown that
there are 3 fundamentals to deploying a Digital Twin solu on:

1) Collected, consolidated, aggregated and contextualized data

The first is ensuring the availability of the data needed to describe the asset or process. Here data is
collected, consolidated, aggregated, and put in context for it to be ready to share across the
organiza on. For this to be complete, the digital twin should be able to manage both real- me
opera onal data sources (such as sensors and other field devices) and engineering data over the full
industrial lifecycle from engineering to opera ons.

2) AI and first principle models to get deeper insight into future events

Once data is properly managed the next element is to enrich this with AI and first principle models
crea ng the “intelligence” of the digital twin to get deeper insight into future events to make be er,
and more informed decisions. Knowing how things were designed, how they should be opera ng, and
predic ng how they will operate.

3) Mul -experience visualiza on layer

The third is the mul experience, role-based visualiza on element enabling the user to have access to
the data and the insights in the visualiza on the user of the digital twin prefers. The user on the shop
floor sees the informa on relevant for their KPIs, while c-suite is looking at the same data relevant for
their overall management.

AVEVA offers a comprehensive digital twin, providing a unified way of connec ng with all types of raw
data and turning it into ac onable informa on throughout the en re design, opera on, and
op miza on phases of an industrial lifecycle. Within opera on phase, AVEVA PI System is commonly
used. On top of it AVEVA offers a digital twin solu on also known as PI Digital Twin, which would be
the main focus for this learning course.

8
 PI Digital Twin
PI Digital Twin provides a framework to capture the en re history of opera ons that is currently
accessible and gives various Teams of Engineers a single system of record. That allows them to thrive
and accelerate decision making.

A PI Digital Twin is a replica of opera ons equipment that

 capture me-series data in a structured way (Data Archive and Asset Framework),
 forecasts condi ons and provides calcula ons (Asset Analy cs),
 detects meaningful pa erns (Event Frames),
 alerts subscribers (No fica ons),
 provides instruc on to first responders (PI Vision and No fica ons).

In the picture below you will find a 3D model from AVEVA Engineering applica on with stages of
building Opera onal Digital Twin in PI System.

Asset Framework (AF) plays an important role for PI Digital Twin, it brings context to raw data,
templa zes equipment types and calcula ons, and connects to external systems:

Let’s look at a possible implementa on of PI Asset Framework hierarchy, where at least several dozens
of a ributes are given per one element/template. In the example below, Pump has data almost about
everything:

 Operating conditions: various Pressures, Temperatures, Flow rate.

 Data about its parts, including Bearing (Temperature and Vibration) and Motor.

9
  Equipment information and KPIs.

As a result, at least a dozen of calcula ons are being associated with the same Pump.

10
At larger scale, there are many varia ons, including several different pump types, models,
manufactures, fluid type, environment, vibra on analysis, extra sensors.

To grasp the magnitude of this issue, consider the following example: for simplicity, we assume there
are 18 possible measurements/features (measurements like discharge or suc on pressure, vibra on
analysis, the whole list could be found in ‘Lesson 3. Accessories (link)’) that can represent the
behaviour of a pump. A single pump might have any number of these measurements, but if we assume
it has 4 out of 18, the number of unique combina ons using factorial nota on is over 3000, calculated
as

18! 18!
= = 3060
(4! (18 − 4)!) 4! ∗ 14!

In case greater than 4 measurements assigned to each pump, the number of combina ons would be
even more. This approach becomes tedious to implement and could lead to poten al errors and
mul ple repe ons.

PI Digital Twin, in contrast, offers an elegant scalable solu on where each feature or calcula on is
represented as a separate module = template. The high modularity structure of PI Digital Twin
supports an opportunity for mul ple authors to collabora vely create templates based on AVEVA
Best Prac ces, in-house knowledge, and external Subject-Ma er Experts (SMEs). This collabora ve
approach ensures that templates are robust, comprehensive, and incorporate diverse perspec ves
and exper se.

Once a template is created, it is typically managed and maintained by a designated individual or a

small team (the "single owner(s)"). The designated owners are responsible for making updates and
changes as needed, which helps maintain the integrity and usability of the templates. With single
owner(s) of templates, they become easy to use and modify. Furthermore, with PI Digital Twin
consistent naming conven on, templates and elements are self-explanatory and easy to search in all
user applica ons. As a result, the user gets opera onal digital twin which matches exactly to the
physical asset.

This high modularity is executed through Accessories – Asset Framework templates purposely built to
perform a certain calcula on or represent a feature of an Asset. Examples could include Vibra on
analysis, Efficiency calcula ons, Forecast, Nameplates, simple Sensors and alike. Accessories are
designed to iden fy pa erns and detect faults in equipment opera on, send alerts and provide
instruc ons to end users or systems. This ensures a detailed overview across the whole equipment
fleet.

11
In addi on, cross applica ons links could be established from equipment and equipment parts to
external engineering, maintenance and repor ng applica ons for online data gathering, analysis and
situa onal awareness. Below is a standard set up of PI Digital Twin home page in PI Vision with the
whole equipment list with its major parts and on the top of the screen various links to other
applica ons:

Once modular structure is in place, excursions become much easier to build and consume. PI Digital
Twin watches the opera ng condi ons for you and triggers alerts that prescribe ac on:

- Users do less searching, more solving.

- Users drill Down, Across and Up by asset classes through past failures.
- Users find and discover better solutions.

12
 - PI reports Asset Health by Name, Site, Unit, Trigger, Reason, Class, Severity,
Duration, Count.

An example of reports that can be created and u lized once PI Digital Twin is in place can be
seen below:

On top of this, PI Digital Twin could no fy users through emails and SMSs about anomalies.

Once these no fica on are received, users can inves gate them further on PI Vision screens.

13
PI Digital Twin includes the following libraries and PI Vision dynamic dashboards. A chosen set of
libraries represent common equipment types that are present in most industries. AVEVA is constantly
working on expanding and improving PI Digital Twin library set.

Asset Libraries: Accessory Libraries: AVEVA PI Vision:

 Pump  Vibration Monitoring  Anomaly: Displays, Overlay,
 Compressor  Forecasting Annotate
 Dryer  PID Controller Diagnostics  Asset Displays by class
 Turbine  Energy Management  Accessory Displays by class
 Electric Motor  Weather Live/Forecasts  Asset “HOME” dashboard
 Valve
 Heat Exchanger Base Library: Microsoft PowerBI:
 Generator  Containers  Enterprise aggregation of
 Vessels  Classes events
 Taxonomy  Interactive asset health
reports

14
PI Digital Twin Best Practices
1. Consistent Global Naming Scheme – ensure consistent naming scheme across site, enterprise
and community. Each asset, accessory and anomaly must follow this name per this global
scheme.
2. Adhere to Industry/Engineering Standards – seek to understand and adhere to the design
standards for sensor and asset naming as found in the plant design and operating control
systems.
3. Intuitive Replica of Operations – in the digital twin, mimic the established asset boundaries
defined by how assets are designed, purchased, operated and maintained by the end-user.
This ensures the most sustainable adoption by the end-user.
4. Primary and Secondary Asset Classification – classify assets as primary and secondary
modularizes the templates such that secondary assets are positioned as optional in the twin.
Primary assets house secondary assets. This reduces user frustration from wasted time
moving through long flat lists. This also allows for asset comparisons across more asset types.
Another large time saving benefit automated naming of secondary assets from their primary
asset parents. Examples: Primary Asset – Pump, Secondary Asset – Electric Motor.
5. Accessory Classification – classify purpose-built calculations for Primary/Secondary Assets
into modular reusable format.
6. Focus on Time Series Sensor Data – lead with time series data. PI Systems are best suited for
time series data from operations (historian). Context plays a supporting role.
7. Combine Related Streams – combine disparate (related) sources of time series data to
promote discovery.
8. Watch for meaningful patterns – utilize predictive analytics as they produce a “work by
exception” culture where operations teams spend more time in critical thinking, less time
gathering data and achieve greater value.
9. Notifications\Actionable – configure notifications for anomalies such that they include rich
explanations of the data that triggered the concern and explain the actions to take in language
understood by the reader.
10. Notifications\Related data – include all "Related Data" streams in the event frame attributes
and add them in the notification body with an explanation of their association to the subject
trigger. This is the framework for building a thorough and verbose notification. The attributes
of all PI Digital Twin asset and accessory element templates contain a category for "Related
Data" streams to facilitate being used in the analytics and referenced in the notification.
11. UI Bridging to Related APM Systems – incorporate self-populated links, with asset context, to
UI’s such as Enterprise Document Management Systems (Engineering) and Centralized
Maintenance Management Systems (Maintenance).
12. Data Quality/Validation – ask for the anomalies to be validated by operations teams.
Operations teams would be able to validate the surveillance results against the actual asset
performance. This ensures that only valid problems and meaningful opportunities are flagged
for sharing and further study.
13. Future Data – forecast your predictive analytics results into future data tags to gain ease of
communication with operations end-users.
14. Anomaly Sharing – design the PI Digital Twin anomaly data or sharing upward to larger digital
twin pla orms and data science pla orms that span across enterprise and community. The
“work by excep on” culture begun in the opera ons team should be extended upward to the

15
 enterprise and the community of partners. This would allow to join efforts in resolving issues
in the most efficient way and collectively brainstorm the strategy to prevent them from
happening in the future.
15. Surveillance Guidance – with a PI Digital Twin platform in place, operations teams should
gather templates from various sources or develop them together with local site staff,
enterprise resources or community partners and suppliers.
16. Time Series Pattern Recognition – recognizing patterns in historical data streams is a critical
tool to detect anomalies accurately. Learn from the examples included in the standard set of
PI Digital Twin libraries. Expect to spend time acquiring deeper capabilities for time series
pattern recognition pertinent to your industry and problem set.
-

16
Lesson 2. Asset Structure
Objectives

 Examine AF Libraries.
 Understand the main concept of Containers, Primary and Secondary Assets.
 Create drill down Asset structure.

Introduction
This lesson is designed to put theore cal knowledge from the previous sec on into prac se. To do
that, let us assume that you are working on a new project for a customer called NuGreen, LLC. They
are building a brand-new produc on line in Houston: some of the PI Points have been created and are
collec ng data, some of them would be new.

The following requirements should be met:

 Plant Management needs to include several SMEs (Subject Ma er Experts) in this
moderniza on, so they all could work together and share their exper se.
 Same naming conven on should be used across mul ple pla orms (CMMS, SCADA, PI
System). Also, different departments need to have an easy access to PI System and have their
own view of assets with the below requirements:
o Operators need to monitor the current data of produc on,
o Management should be able to see forecas ng and overall performance,
o Maintenance should be able to quickly troubleshoot any equipment failures.
 The first phase of the project should include:
o A few main assets from the plant,
o Efficiency calcula on,
o Forecas ng mechanism,
o Electrical power calcula ons,
o Tracking of anomalies and no fying users through Emails,
o Displaying data on PI Vision screen for further analysis.
The main equipment for this phase of the project would be Heat Exchanger, Pump and Motor.

The decision has been made that PI Digital Twin approach will be used to answer all the requirements
men oned above.

17
 Exercise – Equipment Hierarchy Brainstorming
In this exercise let’s brainstorm how the desired structure may look considering all the requirements
men oned on the previous page.

First let’s start with the physical objects. Each customer has the whole list of Equipment stored
somewhere from the Engineering stage. In the real case scenario, these items could be exported from
the Engineering so ware or linked in real me, so Opera on so ware (PI System) could be always up
to date. Below is the example of how the structure may look like in the Engineering system (for example
AVEVA Informa on Standard Manger) and respec ve view in PI System in PI Digital Twin format.

Data Model in Operation

Data Model in Engineering (PI Digital Twin templates)

Mechanical Assets

Rotating Rotating

Pump Pump

Static Equipment Fixed

Heat Exchanger Heat Exchanger

Once the Data Model (AF Templates) is obtained or created locally, we need to generate the object
items. These objects can be created manually within the system or imported from other sources. For
instance, within the AVEVA por olio, you can use AVEVA Asset Informa on Management to export
relevant data subsets for opera ons, which can then be transferred to and mirrored in the PI System,
as illustrated below.

Equipment in Operation
Equipment in Engineering (PI Digital Twin Hierarchy)

Site Site

Division Division

Pump 123 Pump 123

Pump 345 Pump 345

Heat Exchanger 123 Heat Exchanger 123

Lastly, the structure in the PI System should be enriched with me series data coming from
instrumenta on sources such as AVEVA Historian, integrated into the system as a ributes. This
founda onal data can then serve as the basis for further detailed analysis and calcula ons. Moreover,
the results of sophis cated calcula ons and advanced analy cs, such as those generated by AVEVA
Predic ve Analy cs, can also be incorporated into the hierarchy. This layered approach ensures a

18
comprehensive and dynamic representa on of the data, facilita ng more accurate and insigh ul
decision-making processes.

Based on the requirements above, pump should have calcula on for its efficiency and forecast. A
tradi onal approach in Asset Framework would lead to a hierarchy where analyses is configured at
element level, resul ng in a structure similar to the following.

PI Digital Twin

Site (Houston)

Division (Production Line)

Pump 123 (G-01) Analyses: Pump Efficiency;

Efficiency forecast;

This representa on of the physical assets, however, introduces several limita ons. It becomes
cumbersome to manage and maintain as the number of elements and associated templates increases,
leading to poten al errors and inconsistencies. Furthermore, the inflexibility in handling varia ons and
the lack of modularity restrict the ability to easily adapt and scale the system. In contrast, as we briefly
introduced and will explore in the next lessons, the PI Digital Twin approach offers a more streamlined,
scalable solu on. It u lizes modular accessories that ensure consistency, reduce complexity, and
enhance overall opera onal insights and system responsiveness. In PI Digital Twin format, the resul ng
hierarchy may resemble the structure shown below.

PI Digital Twin

Site (Houston)

Division (Production Line)

Pump 123 (G-01)

Pump Efficiency

Efficiency forecast

Once the structure is created and calcula ons are configured, it is important to configure Event Frames
to track all the excursions and no fy the end user when they occur.

As a part of this course, we will be crea ng and configuring the structure directly in PI System using
built-in capabili es. For those interested in integra ng data from Engineering tools, please reach out
to your AVEVA representa ve for further assistance.

19
 Asset Framework libraries for PI Digital Twin
Asset Framework has a capability to save libraries to provide a collec on of applica on- or domain-
specific objects that you can be imported into a PI AF database. Saved libraries typically include a set
of objects that must be included such as: categories, element templates, enumera on sets, reference
types, tables, as well as the unit-of-measure database. On top of these objects, you also have an op on
to include other objects, such as elements and no fica ons.

PI Digital Twin (PI DT) uses templates for various asset types or types of calcula ons that are generic
and applicable for different assets. Those templates are divided in different groups and saved as AF
libraries.

Each PI DT library has a certain naming pa ern and descrip on that should help to define the content
that it holds. Each template within the library always starts with three-le ers in upper case – a prefix
to help the user iden fy where the content/template came from once it has been merged with other
libraries in a produc on deployment.

The same logic should be applied when developing your own PI Digital Twin library.

General naming pa ern for PI DT libraries looks like the following:

Name: PIDigitalTwin.<X><NameOfLibrary>

Where X =

a [for a library that has Primary Assets]

b [for a library that has only Secondary Assets]

c [for a library that has only Accessories]

Descrip on: <ABC> – <descrip on of the library’s scope or purpose>

Where ABC = Library Abbrevia on

Below you can find examples of the libraries that are used as a part of this course:

PIDigitalTwin.!Base [BAS] – basic library that always needs to be loaded first and holds all the basic
skeleton configura on for other libraries.

PIDigitalTwin.aPump [PMP] – Primary Asset Library for a pump covering different types of pumps and
related calcula ons.

PIDigitalTwin.bElectricMotors [MTR] – Secondary Asset library for electric motor covering specifics for
a motor, rela ons to the primary asset and corresponding analy cs.

zzz.GlobalConfiguration

To keep track on which PI DT Library is used and which version it is, AF Element zzz.GlobalConfigura on
should be created at the root of AF Hierarchy. In addi on, this AF Element holds configura on that is
used later across all libraries like Global No fica on Email Adress, PI Vision Server name, PI Server
name, links to external systems and others. Crea on of this element will be covered in exercises later.

20
Library Objects

Library objects are:

1. Element Templates
2. Event Frame Templates
3. Analysis Templates
4. No fica on Templates
5. Tables
6. Enum Sets
7. Reference Types

ABC.<Library Object Name>

By default, the following pa ern applied to library objects coming from the same library: same name
prefix that is inherited from the Library name. When a project requires to expand the number of library
objects, it is easy to follow the same pa ern and iden fy their inheritance a er wards.

Keeping the standard naming pa ern is crucial, when ge ng new version of

libraries, merging several different libraries in one or upda ng an exis ng set up.

21
 Exercise – Loading Libraries
In case you need to load the libraries on your own system outside of this course, the following steps
would be required. In the dedicated Virtual machines for learning course all the libraries have already
been uploaded.

1. Open PI System Explorer (Start > PI System > PI System Explorer).

2. Check that all PI Digital Twin Libraries are uploaded on PSRV01 server. If not (or if you are
uploading this on you own system), upload libraries from XML files to PI AF Server Proper es
(‘File’ > ‘Server Proper es’ > ‘Libraries’ tab > Right click 'Import from File' and import the
libraries from C:\AVEVA PIDT Libraries). The result should look like on the screenshot below.

3. Load PI Digital Twin Libraries into desired AF Database (‘File’ > ‘Load Library’), star ng with
AVEVA.PIDT.!Base.
The BAS library for PI Digital Twin represents the backbone of PI Asset Framework templates.
The library introduces a three-step methodology for building digital twins: Containers, Assets
and Accessories. Classifica on of assets into mul ple layers is presented to facilitate library
applying op onal content on specific classes of assets. Classifica on also is important to
perform filtering of assets and accessories with visualiza on client tools.

22
4. A series of Element Templates and other items in the Library will be uploaded to your
Database. These could be found by naviga ng to Library and then expanding Templates >
Element Templates > BAS Master
- BAS.1.Containers are groups of Assets (Sites, Business Unites);
- BAS.2.Assets are the physical Assets themselves (Pumps, Motors);
- BAS.3.Accessories are the func ons or the features that we want to put on to assets
in various combina ons (Calcula ons).

5. In the Demo Environment for this course an element zzz.GlobalConfigura on will be used. It
holds some global configura on informa on. This element is based on a Template that could
be accessed from the Pale e (View > Pale e > Element Templates or click CTRL+SHIFT+1). To
create it and drag ‘zGlobal Configura on’ from the Element Templates to the Elements root,
or right click on that root, click New Element, and select the template:

23
6. One of the Global Se ngs is PI Vision Server name, as a part of this class the
pisrv01.pischool.int server will be used. Edit the PI Vision Server a ribute value of the
zzz.GlobalConfigura on element as shown in the picture below:

24
 Containers
PI Digital Twin has a separate set of templates called Containers. They represent a grouping of items
based on common factors, such as loca on, use, equipment subdivision, etc. Various Interna onal
Standards call this grouping a Taxonomy. Most commonly, customers have an established taxonomy
that is the result of the EPC (Engineering, Procurement, Construc on) process that designed the
facility. This would lead to several taxonomic levels depending on the category. The following pyramid
represent categoriza on by use, loca on and equipment subdivision as an example from ISO
14224:2016 (Source: h ps://www.iso.org/obp/ui/en/#iso:std:64076:en).

Figure – Taxonomy classifica on with taxonomic levels

In PI Digital Twin a similar design concept is covered by Containers and Asset templates. Similarly to
the pyramid above, each level in Containers could represent Enterprise, Site, Produc on Unit etc.
Equipment and its parts are usually represented as Primary and Secondary Assets within PI Digital Twin
(will be covered later in the book). The whole structure is fully configurable and expandable for each
customer implementa on and may not follow exactly the standard above.

There are several rules and best prac ces that should be followed while designing Containers for PI
Digital Twin.

Rules:

1. Labels for Containers are to be used consistently across all instances (AF Servers). This means
that the labels being used for a certain level should be exactly the same across various PI DT
models. For example, in one instance Level 3 (L3) is labeled as “ProcessUnit”, then in every
other AF instance Container Lx (may or may not be Level 3) also should be labeled the same
“ProcessUnit”. This rule is required for further repor ng and analysis across similar
“ProcessUnit” in various implementa ons.
2. Every child Container should be at a deeper level than the parent Container. For instance, L3
Container could have a child Container that is L4 or L5.

25
 3. Container template levels can be skipped. A par cular level might be prevalent in some plant
sites of a business enterprise but non-existent in others. For example, L4 can be placed on an
L2 when there is no L3 present in the model at all.

Taxonomy configuration

Each Container element has a pre-defined set of a ributes:

 Container Type – is a taxonomic level that this container represents (Plant, Unit, Sec on etc.).
The whole list of possible taxonomic levels that are present in the Enterprise should be
created in the Enumera on Set (Library > Enumera on Sets > BAS.AssetContainerTypes).

 Taxonomy – is a family of a ributes that holds data from the current taxonomic level and all
the levels above. In the example below a ribute ‘Taxonomy’ and all its child a ributes
represent a breakdown of actual values for a par cular AF structure.

Best Prac ces:

 Container templates are numbered 1 through 5 with the expecta on that each customer will
define each container template “type” indica ng the scope of that container level. Set the
container type to show users the meaning of that level in the taxonomy.
 Setup the “Taxonomy” a ribute in PI DT at launch. Taxonomy is a parent a ribute of every
container whose child a ributes echo the taxonomy found in the Element naming pa erns
across all elements in the PI DT model. The Taxonomy a ribute is useful in various client tools
that consume PI AF data from PI DT. For instance, a report could be built for all “ProcessUnit”
across various sites.

26
 Exercise – Creating Containers
Containers are the first out of the main three groups of Templates within PI Digital Twin Libraries that
represent Business Units, Produc on Lines and alike. As a part of NuGreen project our hierarchy should
look like Company > Site > Produc on Line > Assets.

1. Add an Element to represent Company – NuGreen. Use Element Template for the Business
Unit at the first level (BAS.1.Containers.L1):
Note: to use the Element Templates pale e to create a new element, click on View > Pale e > Element
Templates (or Ctrl+Shi +1):

And drag the BAS.1.Containers.L1 element to the Elements root:

Update the Name a ribute to be “NG”, and ensure that ContainerType has a value of “BusinessUnit”:

A er you check-in, the name should be automa cally updated:

27
 2. Add a child element to the NG element that would represent Site in Houston (HOU). Use
Element Template BAS.1.Containers.L2.

Verify the Reference Type as <BAS.L1-L2>, it should be pre-selected.

Set the Name a ribute to be “HOU”, and ensure the ContainerType is Site. Save/Check-in and confirm
that the name of the element is NG.HOU.

28
3. Finally, add an element for Produc on Line 1, based on BAS.1.Containers.L3, using Reference
Type <BAS.L2-L3>, change the Name a ribute to PL1, and set the ContainerType to be
“Produc onLine”. If there is no such op on for ContainerType, add it in the Enumera on Set
BAS.ContainerType. Save/Check-in.

29
Now, when the high-level structure is ready you may recognize the inheritance in the naming pa ern.
You can always track it back in the set of configura on a ributes called Taxonomy. It significantly helps
structure and organize data, making it more accessible and understandable for users, especially when
dealing with complex systems and large volumes of data.

30
 Primary Assets
A primary asset represents a tangible en ty crucial to the smooth func oning of opera ons within a
given system. These assets encompass a wide array of physical objects, ranging from pumps and heat
exchangers to generators, compressors, fans and more. They form the backbone of industrial
processes, each fulfilling a dis nct role vital to overall efficiency and produc vity.

Iden fying primary assets means gathering informa on from nearby systems that are important for
the organiza on to work well. These systems may include engineering databases, computerized
maintenance management systems (CMMS), enterprise resource planning (ERP) so ware, and others.
Within the AVEVA Por olio, one such applica on could be AVEVA AIM (Asset Informa on
Management).

Once the list of primary assets is obtained from these disparate systems, it undergoes a series of
manipula ons to ensure compa bility and seamless integra on within a digital framework. This
transi on involves transla ng the physical assets into relevant PI Asset Framework element for PI
Digital Twin. For each asset class there is a corresponding AF Library within the PI Digital Twin toolkit.

Pump Library
As a part of the next exercise, a library for Pump will be covered.

The Purpose – Provide a list of pre-configured AF Templates and other relevant objects for digital twin
model for a pump. It also allows for the collec on of the most used streaming values related to pumps
and their associated accessories such as flow, pressures, fluid power and others. Several calcula ons
are included in the library, among them is Pump Efficiency. This is the efficiency of the pump in turning
input sha power (from the motor) into useful power output to the fluid (Hydraulic Power). Rich
no fica ons are also included as part of the library.

Applica on – The pump is a primary asset type used in various industries. The pump collects sensor
stream data that is used to calculate its opera ng performance. It also allows for a achment of
accessories which provide further data streams used for pump performance and health analy cs.

31
 Exercise – Creating Primary Assets
The next stage for the project in NuGreen requires crea ng assets for a produc on line that involves
a heater to preheat raw material A and a pump.

1. Load Libraries for this exercise. (File > Load Library)

2. Load the following libraries:

- AVEVA.PIDT.aHeatExchangers
- AVEVA.PIDT.aPumps
Note: In the following step, you may see a warning pop-up message indica ng that the element names
already exist when you add the element assets. This is because when crea ng the assets, they will
have the same default naming pa ern un l the name a ribute is specified in this step. You can ignore
these warnings as you will be upda ng the name once the two elements have been created. Once the
name a ribute has been specified, right-click on the element and select “Re-evaluate naming pa ern”,
this will ensure that the correct naming pa ern has been applied.

3. Add two elements for Primary Assets (Reference Type <BAS.1.Containers-BAS.2.Assets>):

Asset Name attribute Template

Heat 01 <HEX.2.Assets.Fixed.HeatEx.ShellTube>
Exchanger
Pump 01 <PMP.2.Assets.Rot.Driven.Pump.Centrifugal>

Le er “G” by default is used for pump, which is a common prac ce for various industries. If in your
industry a different nomenclature is used, it could be easily changed in the template Naming Pa ern.

If you s ll see any “PI Point not found” errors, ensure that the naming pa ern (e.g. NG.HOU.PL1.E-01
etc.) for each element matches what is shown above. If not, update the Name a ributes appropriately,
“Re-evaluate naming pa ern” of the element(s), and then Refresh so that the PI Point references are
updated.

32
 Secondary Assets
Some primary assets rely on essen al parts to carry out their func ons effec vely. These parts, such
as motors, engines, ba eries, and gearboxes, are crucial components that contribute to the overall
opera on of primary assets. In systems like computerized maintenance management systems (CMMS),
these parts are o en represented as separate objects to ensure comprehensive management. In line
with this approach, PI Digital Twin respects this structure by organizing these parts into dedicated
libraries. Within the PI Asset Framework (PI AF) hierarchy, they are created as child elements to their
respec ve primary assets, forming a coherent and structured representa on of the system.

Some secondary assets, on the other hand, don't directly interact with the product itself but instead
provide essen al services or u li es to support the primary assets. These services could include energy
provision, rota on control, speed reduc on, or various types of controllers. While secondary assets
may have an impact on the product, their main role is to facilitate the func oning of primary assets
within the larger system.

In some cases, secondary assets touch the product but perform isolated func ons that support the
broader scope embodied by the primary asset. For instance, an outlet valve can be considered
secondary to its primary asset, such as a vessel. While the valve directly interacts with the product by
controlling the flow or release of materials, its func on remains dis nct from the primary asset's core
purpose. Instead, it serves to regulate and support the primary asset's opera ons, ensuring efficient
and safe func onality within the larger system. For each asset class, including secondary assets, there
is a corresponding AF Library within PI Digital Twin toolkit.

Electric Motor Library

As a part of the next exercise, a library for Electric Motor will be covered. It comprises of the
components that make up an electric motor including its drive type.

The purpose of this library is to provide a pre-configured digital twin model for an electric motor. It
also allows for the collec on of most used streaming values related to electric motors and its
associated accessories. Analy cs such as Motor Sha Power, voltage and current imbalance are
calculated by the addi on of a specific power calcula on accessory. Rich no fica ons are also included
as part of the library.

Applica on – The Electric motor plays a suppor ng role to a primary asset such as a pump. The electric
motor collects sensor stream data that is used to calculate the opera ng performance of the motor
and its primary asset. It also allows for a achment of various associated accessories which provide
further data streams used for motor performance and health analy cs.

33
 Exercise – Creating Secondary Assets
In this exercise, we will create a Motor for a Pump.

 Load a Library for Motor AVEVA.PIDT.bElectricMotors

 Under Pump G-01 create a Motor by selec ng a Template
<MTR.2.Assets.Rot.Driver.ElecMotor.DOL>, Reference Type <MTR.Rota ngEquipment-
MotorElectric> (for more details about Reference Types (link), see Lesson 4) and name
will be assigned automa cally and should be GM-01.

 Motor will have two accessories, names will be assigned automa cally, just drag and
drop templates on GM-01, in more details the topic about accessories and simple
sensors will be covered in the next lesson:

Accessory What is it for? Template Reference Type

JI-Power Monitoring <BAS.3.Acc.Sensor.SimpleAnalog.Power> <Bas.2.Assets-
electrical power BAS.3.Acc.Sensors
consumption >
NPL Name Plate, <MTR.3.Acc.Nameplates.Motor.NEMA/IEC> <MTR.MotorElectri
Performance c-
Ratings of the MotorNEMA/IEC>
equipment,
Certifications,
classifications,
and more

34
  In addi on to Motor, also include a nameplate accessory for Heat Exchanger that holds all
the necessary informa on about this piece of equipment

Accessory What is it for? Template Reference Type

NPL Name Plate, <HEX.3.Acc.Nameplates.HeatExchanger.ASM <HEX.2.Assets.Fixe
Performance E.Shell&Tube> d.HeatEx.Shell&Tu
Ratings of the be-
equipment, HEX.3.Acc.HeatEx.
Certifications, ASME
classifications, Shell&TybeNamepl
and more ate>

-
Let’s recap on what has been covered.
-

Up un l this point several major topics were covered, let’s highlight them:

 Tiering assets is essen al for communica on ease and scalability.

 Most common sensors are part of the low-level BASE Template, in our exercise we’ve used
it for JI-Power, other examples could be Pressure, Temperature, Current. This adopts ISA
Instrumenta on Naming scheme.
 Several sensors could be combined in one calcula on, in PI Digital Twin it is classified as
Accessory. An example could be Pump Efficiency described in the next lesson.

35
Lesson 3. Accessories
Objectives

 Understand the need and variety of Accessories within PI Digital Twin.

 Create Vibration Analysis and Forecast calculation.
 Set up Notification for anomalies.
 Visualize the whole equipment fleet, calculations, and alerts on a single PI Vision
dashboard.

Introduction
Asset Accessories – are purpose-built components that are highly reusable and could be applied to a
subset of assets in each asset class or across multiple asset classes. They are optional child element
templates that provide additional functionality for an asset or container. They are applied in various
combinations to fit the needs of each particular asset. Asset Accessories have these traits:

 Detect anomalies, produce Event Frames/Notifications on behalf of their parent.

 Receive Name and Asset Class data from their parent and use to set context.
 Often represent an “additional or optional” sensor or edge device.
 Exist as a child of an Asset or a Container.
 Governed by 'Reference Types' that set what accessories can be applied to what asset classes
or asset super classes.
 Receive attributes from their parent to feed their predictive analytics/Notifications.
 Receive related sensor streams to feed their predictive analytics/Notifications.
 Can themselves have accessories.

Why accessories are crucial in PI AF structure?

Here is an example of 18 measurements and associated calculations that may or may not be present
for a pump:

 Discharge pressure.
 Suction pressure.
 Fluid properties:
o viscosity,
o density,
o temperature.
 Torque.
 Fault codes.
 Shaft seal temperature.
 Shaft seal leakage.
 Ultrasonic Pump Condition Monitoring.
 Noise level.

36
  Net Positive Suction Head (NPSH): NPSH is a critical parameter that determines whether a
pump will operate reliably without cavitation. It's calculated by considering the pressure,
velocity, and elevation heads at the pump suction, along with the vapor pressure of the
pumped fluid. Ensuring adequate NPSH prevents cavitation, which can damage the pump and
degrade performance.
 Flow Rate Calculation: calculating the flow rate of a pump is crucial for determining how much
fluid it can move within a given time. It's typically measured in liters per minute (LPM) or
gallons per minute (GPM). The flow rate is influenced by factors such as pump size, speed, and
system resistance.
 Pump Efficiency: pump efficiency indicates how effectively a pump converts input power into
useful work (flow and pressure). It's calculated as the ratio of the pump's hydraulic power
output to its mechanical power input, usually expressed as a percentage. Higher efficiency
pumps are more energy-efficient and cost-effective.
 Vibration Measurement: Vibration is typically measured using accelerometers or vibration
sensors placed at strategic locations on the pump and its components. These sensors detect
vibration in multiple directions (axial, radial, and tangential) and provide data for analysis.
Drive end, non-drive end (pump and motor), casing, foundation of the pump is sitting on.
o Bearing Analysis: Bearing defects such as wear, lubrication issues, and mechanical
damage can result in increased vibration. Vibration analysis can help diagnose bearing
faults by identifying characteristic frequencies associated with defects such as ball
pass frequency (BPFO) and ball spin frequency (BSF).
o Imbalance Calculation: Imbalance is a common cause of pump vibration and occurs
when the center of mass of the rotating components is not aligned with the axis of
rotation. Imbalance can be calculated based on the vibration amplitudes measured at
different points around the pump's circumference.
o Resonance Analysis: Resonance occurs when the natural frequency of the pump
system coincides with external excitation frequencies, leading to excessive vibration
amplitudes. Finite element analysis (FEA) or modal analysis techniques can be used to
identify and mitigate resonance issues.

An average pump may have 4 items out of 18 from the list above, after simple calculations using
factorial notation the number of unique combinations is over 3000.

18! 18!
= = 3060
(4! (18 − 4)!) 4! ∗ 14!

How to keep up with all the variations? And what would be the best AF Template design to reflect
all unique combinations?

There are several options available to do so:

1. Create one single AF Template

2. Create 3060 different AF Templates
3. Create AF Templates for each type of Accessories

Let’s look at each option in more details.

Option 1. Single template for a pump may look like the following:

37
 Does not apply to Pumps 01, 02, 47, 189...
Does not apply to Pumps 421, 345, 789, 894...
Does not apply to Pumps 48, 345, 789, 894, 1140...
Does not apply to Pumps 68, 247, 800, 917...
...

This option gathers all the relevant pump data within one single Template. Some of the AF Attributes
are relevant to some pumps but may not be present in others. Same exceptions also would apply to
Analysis, calculated attributes, and notification rules. To keep up with all the differences, ‘excluded
attributes’ would need to be used. Although it may be applicable in some cases, at large scale it could
be tricky to maintain, and it may cause some confusing errors in Visualization tools.

Option 2. Create 3060 different templates for each combination.

38
As a result of this approach the same module of Vibration monitoring VI-NDE.Imbalance would be
copied and maintained for different asset types. This module is applicable to not just a pump, but to
various rotating equipment, agitators, dryers, gearboxes etc. Making some minor changes in the
Accessory would require careful meticulous implementation repeatedly throughout all the assets.
That approach is labour intensive, high cost and susceptible to error. In addition, if the number of
features the pump should have is greater than 4, let’s say 5/6/7 out of 18 than a number of
combinations would be 8568/18564/31834.

Option 3. AF Templates for each type of Accessories.

39
With this approach a calculation like pump efficiency is represented as a separate template –
Accessory. As a result, every Primary Asset is a combination of smaller modules (Secondary Assets and
Accessories), and every Secondary Assets could be represented as a combination of accessories.

Benefits of modular approach:

 Only 40-50 pump-related templates!

 Logic is not duplicated
 More use of stronger Query tools
 Users see the diverse make-up of each asset sooner

When to use Accessory approach?

Questions that need to be answered:

1. Does every instance of the asset type have this?

2. Is there only one asset type that will use this?
3. Will this appear only one time in an instance of an asset?
- If "yes" to all: You don’t need the accessory approach
- If "no" to any: Consider the accessory approach

Common examples of Accessory:

 Forecasting
 Alarms & Events from SCADA/DCS/IIoT
 Advanced multivariate analytics
 PID and MPC controllers
 IIoT Edge Instrumentation
 Process simulation
 Nameplates
 Fluid properties
 Single Sensor Instrumentation

Simple Sensor Accessory

The PI Digital Twin offers a suite of Simple Sensors designed to encompass commonly utilized sensors
in production, regardless of the asset they are applied to. In plain language, it is one accessory for one
simple sensor that is one data stream coming in operations.

Each sensor within this family shares a foundational logic that can be inherited, while also featuring
unique characteristics tailored to their specific application. This design facilitates user-driven
extension and modification within both generic and specialized contexts. To identify which context
should go where we recommend following the rule of thumb to put generic logic into generic
template. In other words, decouple pattern detection logic from asset type and define it in the TOP
template. In the example below it would be BAS.3.Acc.Sensors.SimpleAnalog. And the specifics will be
in the derived templates.

For instance, the heat exchanger library can post a version of the simple analog and its temperature
in the temperature family. It adds a specific context – notification – to heaters outlet temperatures on
what to do when the temperature is too high or too low.

Other examples from Simple Sensors are Density, Pressure, Temperature and so on.

40
 TOP: Time Series Pa ern Recogni on. HI/LO in one place.

HI/LO No fica on in asset context.

In conclusion:
- Single sensors address a failure mode and avoid excessive instrumentation costs.
- Single sensor templates apply universally to just about any asset type.
- Template inheritance adds layers of increasing focus to this accessory family.

Multi-Variable calculation accessory

To perform complex logic on various data streams PI Digital Twin has a different type of Accessories –
Multi-Variable calculation accessory. In general, they are being developed together with Asset Type
Library to reflect asset-specific analytics.

In the example below to calculate Pump Efficiency several data streams are required for calculation:
Discharge Pressure, Flow Rate, Suction Pressure and Motor Shaft Power.

In conclusion, accessories are essential for managing diversity at scale in digital twin implementations.
They give a great and easy tool to reflect all the unique combinations within PI Digital Twin model.

And the result is: what we see in the digital twin is what we have in the field.

41
 Exercise – Flow rate – Simple Sensor Accessory
Flow rate for a pump is crucial because it determines how much fluid the pump can move within a
given me frame. Measuring a flow rate is paramount to ensuring fluid control processes run smoothly,
safely and cost-effec vely. Here's why it's important:

Efficiency: opera ng a pump at its designed flow rate ensures maximum efficiency. Running it below
or above its intended flow rate can lead to increased energy consump on and decreased efficiency.

Equipment Longevity: proper flow rates help in maintaining the longevity of both the pump and the
other components of the system. Overloading a pump with a flow rate it can't handle can lead to
premature wear and tear, while running it below capacity might cause issues like overhea ng.

Process Control: in industrial processes, precise control of flow rates is o en essen al for maintaining
product quality and consistency. Devia ons from the required flow rate can lead to varia ons in the
process output.

In this exercise we will be working with flow rate to ensure that the pump delivers the necessary
amount of fluid at the required pressure to meet the demands of the applica on. For opera ons team
it is cri cal to always monitor flow rate independently and alert when the flow rate has demonstrated
a sustained behaviour of flow below a set threshold. Moreover, the opera ons personnel need to be
no fied when the flow rate is low to take ac ons.

In the current setup pump NG.HOU.PL1.G-01 does not have any sensors on it in PI Digital Twin. The
first step would be to add a Simple Sensor Accessory for flow rate. Drag an Element Template
<PMP.3.Acc.Sensors.SimpleAnalog.FlowRate.Pump.Centrifugal> over a Pump G-01 (Reference Type
<BAS.2.Assets-BAS.3.Acc.Sensors>), a new child Element for Flow Rate will be created with a name of
NG.HOU.PL1.G-01.FI-General.

Check the a ributes for this new element, each with the pencil icons should be configured/verified by
the user. The key a ribute is the Name and should be set as “Disch” (Discharge). Some customers may
choose to see the instrument sequence number (aka Loop number, example “2354”) while others
might prefer something more readable like (Discharge), others may want both in the name.

Check-In/Save and see that the name of the flowrate accessory is set to be NG.HOU.PL1.G-01.FI-Disch.

42
The result of this calcula on needs to be taken further and Event Frame with No fica on should be
configured when the flow rate has demonstrated a sustained behaviour of flow below a set threshold.

As a part of this exercise, we will not be tes ng it, however, it is available in the library configura on,
and you can make a use of them in your own setup.

43
 Exercise – Pump Efficiency – Multi-variable Accessory
Pump efficiency is crucial for centrifugal pumps because it directly impacts energy consumption,
operating costs, environmental considerations, equipment longevity, and regulatory compliance. It is
an important parameter to consider when evaluating or designing a pump system.

In this exercise we will be working with pump efficiency that refers to the ratio of output power to
input power of the pump, usually expressed as a percentage. It indicates how effectively the pump
converts mechanical energy (input) into hydraulic energy (output). Higher efficiency means that the
pump wastes less energy and operates more effectively.

First step is to add accessory for calculating Pump Efficiency by adding a child element using
<PMP.3.Acc.Calc.PumpEffcy> element template to Pump <G-01>. Choose
<PMP.2.Assets.Rotating.Pump.Centrifugal-PMP.3.Acc.Calc.PumpEffcy> as a Reference Type. The
name will be applied automatically.

In the default Library set up PI Points could be simulated for the testing purposes or linked
automatically (when the naming pattern is matched to PI AF) or manually (when the naming pattern
for PI Point and AF are different) to the real system.

As a part of this course, we will reuse the PI Point from the previous exercises (Flow rate) for
calculating Pump Efficiency, because it will need that exact measure in calculation. To make this
happen, assign PI Point NG.HOU.PL1.G-01.FI-Disch.Actual manually to Flow rate attribute.

44
Once it is done, let’ check calculations included into Pump Efficiency Accessory:

Analyses Description Notify

Pump Efficiency Calculates TDH, Fluid Power, Efficiency No
Detect Low Excessive time spent below a low efficiency limit for a specified amount of
Yes
Efficiency history looking back from the present.

Pump Efficiency analyses uses the following formula:

First step is to calculate pump’s differential pressure (Discharge-Suction), then calculate TDH – total
differential head, corrected to the fluid factor, which is water in this case. And last step is to calculate
Efficiency using ‘Motor Shaft Power’, which is coming from JI-Power Accessory for Motor
(NG.HOU.PL1.GM-01.JI-Power, child element to a Motor, which is child element to a pump).

Enable both analysis and preview the results, verify they both are working and no error messages
appear.

Later in the book we will work more with Event Frames and Notifications for Efficiency to send out to
the end user. Once again about the main logic: almost every calculation should end up as Event Frame
and Notification to inform the customer about any excursion that happened. Pump Efficiency is one
of the most critical calculations and any deviations should be carefully tracked.

45
 Exercise – Vibration Analysis
Vibration monitoring for pumps using accelerometers is a common and effective method for assessing
the health and performance of pump systems. To roll out the monitoring Vibration Monitoring Library
will be required.

The Vibration Monitoring (VIB) library for PI Digital Twin provides vibration monitoring accessories for
placement on any asset. The library is focused on the use of edge devices at the sensor layer for
vibration that stream the time wave form and overall vibration summaries. The accelerometer sensor
accessory is provided and focuses on overall acceleration, overall velocity, and overall bearing fault.
The proximity sensor accessory is provided and is focused on overall displacement.

A second layer of vibration accessory is provided for fault frequency monitoring. Edge devices for
vibration sensors can be configured to export from their local Fast Fourier Transform (FFT) analyses
the amplitude at specific frequencies of interest specified by the user. The library here provides
accessory templates to receive these focused fault frequency streams in accessory templates. Fault
frequency data comes from an accelerometer or proximity sensor and thus are modeled as children
in the PI Digital Twin.

The libraries introduce Units of Measure (UOM) classes for acceleration, velocity, bearing fault and
displacement. These are sinusoidal wave form classes that include Pk, Peak-To-Peak, Avg, RMS.

As a part of this exercise, we will analyze vibration by creating three accessories in PI Digital Twin
hierarchy, which will represent different fault frequencies. By analyzing the vibration data and
identifying these fault frequencies, maintenance personnel can detect and diagnose bearing issues,
allowing for timely maintenance or replacement to prevent catastrophic failures.

All libraries for PI Digital Twin are designed to be merged together in any combination chosen by the
end-user. The Vibration library is optional.

1. Load Vibration Library AVEVA.PIDT.cVibration: File > Load Library

2. Review the following structure for Pump G-01, main vibration element with three child
elements for different fault frequencies (like it is shown on the screenshot below):

Accessory What is it for? Template

VI-DE-V <VIB.3.Acc.Sensors.Accelerometer-VAB>
BPIR BALL PASS INNER RACE Fault <VIB.3.Acc.Sensors.FaultFreq.Accel.BPIR>
Frequencies;

46
 It represents the frequency at which
each ball passes over the inner race
defect.
BPOR BALL PASS OUTER RACE Fault <VIB.3.Acc.Sensors.FaultFreq.Accel.BPOR>
Frequencies; It represents the
frequency at which each ball passes
over the outer race defect
BSF BALL SPIN Fault Frequencies; It <VIB.3.Acc.Sensors.FaultFreq.Accel.BSF>
represents the frequency at which
the balls spin within the bearing. It is
generally lower in magnitude
compared to BPIR

3. Create the first Element – Accelerometer. Right click on a pump G-01 element > New >
New Child element

4. Select the Reference type for asset sensor accessories <BAS.2.Assets-BAS.3.Acc-Sensors>

and it will filter out all the related Templates. Pick Accelerometer for vibration analysis.

47
 5. Repeat step 3 for the newly created element VI-DE-V create three child elements of each
type (BPIR, BPOR, BSF), selecting <VIB.3.Acc.Sensors.Accelerometer-VIB.3.Acc.Sensors-
FaultFreq.Accel> as Reference type.

The result should look like this:

For each Vibra on related analysis, you can find PI Vision screen that is very helpful for end users to
view the results, get a table with possible causes and prescrip ve ac ons.

48
Another benefit of having vibra on analysis in place, assuming you have all the sensors available, is
Event frames and No fica ons that are part of this Vibra on Library. The user receives an email with
possible causes and correc ve ac ons when vibra on analysis deviates from the norm.

As a part of this course, we will not be tes ng them, but those samples are available for you to use.

49
50
 Tuning analytics – key recommendations

Let’s recap on Analy cs that were just built.

Before moving forward, it is essen al to understand the importance of well-tuned analy cs and a
meaningful amount of Event Frames the user should receive. It is o en an underes mated capability
that could be easily converted into ‘spam generator’. However, based on our experience, it is one of
the most valued func onali es of the PI System that allows the user focus only on something that is
truly important now.

Key Deliverable – Time Series Pattern Recognition. The user should watch for meaningful patterns
and generate notifications only when attention is truly needed. In other words, produce a “work by
exception” culture using analytics.

Too many or too few event frames ruin the success of this program. When designing templates and
conducting tests with the real system, your goal is to generate only significant notifications when
attention is truly needed. You cannot rush through this step. Firstly, understand the production
process. Secondly, ensure the Event Frame remains open until the condition is resolved. Thirdly, be
very cognizant of Event Frame count (what is the correct and expected amount) and history for each
component. Lastly, tune asset analytics until the correct event counts occur.

This requires continuous improvement of the design of the analytic and adjusting at each use case.
Whatever you can do in the template design to reduce tuning requirements is time well spent.

Analytics tuning routine for PI Digital Twin templates involves bringing the analytics online in a
standard order to avoid false alerts and confusion. Each analytic is different in how it relates to the
physical assets and the variation therein. These steps illustrate how analytics can be tuned at runtime.

1. Capture historical tag data for several days (>30days).

2. Review raw data trends to get oriented and estimate the number of event frames should
you have gotten from this data.
3. Enable any expression analyses and backfill (if present).
4. Preview the Event Frames analytic to confirm proper amount of event frames would be
generated and with the proper duration.
5. Tune the settings for the analytic as needed, repeat step 4 until satisfied with the number
of Event Frames.
6. Enable and backfill the analytic for an appropriate amount of history (~1 year, discuss with
the appropriate Team).
7. Enable the notification rule.

General recommendations for accessories/calculations

Units of Measure (UOM) are to be specified for all numeric attributes. This is a best practice that
promotes fast accurate recognition of units by users. It also demonstrates improved accuracy in
conversions when done by AF. Any non-standard UOMs that are needed must be very uniquely named

51
so as not to interfere with existing UOMs when imported. Examples of UOMs that have been added
in PI Digital Twin are.

UOM Class: Quantity Rate

UOM’s: Events/Min, Events/Sec, Events/Min, Counts/Sec, Counts/Min

UOM Class: Time

UOM’s: msec

CONVERT() function should be used whenever an analytics statement does not resolve the UOM itself.
The best way to determine if needed is when you “Evaluate” the analytic it should display the UOM
immediately to the right of the output result. This allows the best practice of letting the user see the
UOM when “Evaluate” is pressed. Also allows edits to attribute UOMs without disturbing the analytics
code. Reminder: Restarting the Analysis is required when attribute UOMs involved in the analysis are
edited.

Source Units should be explicitly specified for all PI point attributes if known. This is most prominent
at deeper layers inside a template family where it is aligned to an OEM product. The goal is promoting
the use of UOM conversions.

AF Analysis Output PI Points are to be set for tag crea on and use a common pointsource name in the
PI Data Archive. To do this, the pointsource name is to be specified in the Tag Crea on Se ngs of the
a ribute templates. The point source name is a user se ng in zzz.GlobalConfigura on. The absolute
path to the pointsource is '\zzz.GlobalConfigura on|PIDigitalTwinPointSource'. (DEF VALUE = “PIDT”)

BADVAL() is recommended as a filter in analy cs to prevent triggering nuisance event frames from bad
data.

Exit() func on is par cularly helpful during tes ng phase and also to op mise the calcula on.

NoOutput() is recommended when a certain logic does not require an output, especially useful for
code op misa on.

Analysis Templates Disabled when Deployed, default for all analy cs to prevent nuisance errors.
Users are required to enable the analy cs a er all tags are created with data flow.

Comments in Analysis Code using the “//” are a fantas c way to include explana ons of the analy cs
scripts. These are always valuable to users that are unfamiliar with your template.

52
 Exercise – Creating Assets in Bulk
As a part of modernisation project multiple similar assets should be created. PI Digital
Twin with its predefined Templates gives an easy and quick way to scale up the structure
in PI Asset Framework. In this exercise we will be creating another 3 pumps with slightly
different modifications, and more or fewer sensors.
To reflect these differences and create new pumps we can use MS Excel with PI Builder.
1. Open MS Excel to access PI Builder.
2. Make sure the correct AF Server and database is selected under PI Builder
Connections.

3. Select Elements > Find Elements to get Pump and all the elements under it. Then
select the whole structure for Pump ‘G-01’, it’s components and accessories
with ‘Shift’ key pressed.

4. For the column selection, reset first by clicking Clear All, then enable ‘Template’
under Element and ‘Name’ under Attribute Columns.

53
 5. Find and replace all ‘01’ with ‘02’

Make sure that the “|Name” attribute for the Pump is ‘02’ and not just ‘2’. MS Excel
could have removed zero. Naming convention for all Pumps is G-XX, where XX is its’
number.

54
 6. Click on Publish (with Create Only-option).

7. Switch to PI System Explorer, click on Refresh and verify a new Pump G-02 has
been created with the exact same configuration of secondary assets and
accessories.
Once you have a solid foundation for Pump structure it becomes extremely easy to
create more copies of the same object.
8. Repeat step 5 and 6 for Pumps 03 and 04. Verify that they are created in PI
System Explorer.

9. Enable new analysis and verify they are working correctly, no error messages.

55
 Notification configuration
No fica on closed message: The default no fica on closed message shall be overwri en (provided
there is no objec on from customer) to be [RTN]. This is somewhat of a standard message coding in
the IT (Informa on Technology) industry meaning Return to Normal. It is brief and designed to be the
first object in the SMS text message and Email Subject line. This feature is controlled by adding a PIANO
configura on database a ribute.

No fica on Email Subject Line must follow this format:

“[MessageForClosedNo fica on][EventFrameName]”. This format makes it easy to recognize
whether the email represents a new no fica on or the closing of an old one.

Subscrip ons to “Poor Performance” No fica ons should always be set for both the start and end of
the event frame so all users know when the issue is cleared. This is not the default se ng in PI System,
so make sure it is set correctly.

Global Dynamic email delivery method is a method that allows users to u lize one global a ribute to
be the default email distribu on list for the en re library of no fica on rule templates. This is done to
streamline PI admin rou ne. Addi onal subscrip ons can s ll be added as needed to any no fica on.
This se ng can be removed on any element as needed.

Global Format(s) for no fica ons are required and must be provided with the library to lead the
customer to make advanced, rich, and consistent no fica ons across their PI Digital Twin deployments.
The PI DT library will have an example global format that applies to any industry. One such example is
BAS. Asset Health Event. This global format has a layout (eMail) that provides a place for sensor
streams, outputs, limits, explana ons, triggers, probable causes, correc ve ac ons, etc. When crea ng
your own no fica ons templates, this default PI DT template could become a good basis to start. In
mature PI DT build at a customer site several mul ple global formats covering not only health, but
other subjects could be found.

No fica ons Rules Templates Disabled when Deployed, default for all no fica ons deployment to
prevent nuisance errors. Users are required to enable no fica ons a er analy c is running.

56
 Exercise – Tracking Efficiency excursions – Notification
Now that our assets are live, collec ng produc on and electricity usage data. They also calcula ng
Specific Electricity Usage, we want to confirm that no fica ons are enabled. These will alert staff when
assets are consuming more electricity than expected for the given produc on rate.

1. First, navigate back to the ‘zzz.GlobalConfigura on’ element, and update the value for the
a ribute ‘GlobalNo fica onsEmailAddress’, enter email address [email protected]:

This will set the global no fica on email address for all elements with the appropriate a ribute. (This
can be overwri en at an element-by-element level, if you have different maintenance/opera on/SME
groups for various assets).
2. Next, navigate to one of the four Efficiency accessories, go to the No fica ons Rules tab and
select No fica on rule for Low Efficiency in centrifugal pumps. Click on the View/Edit
Subscrip ons:

3. Select ‘Dynamic Endpoint’, then ‘No fica onEmailAddress’ and click on the pencil icon to edit
and confirm that the ‘Current Value’ is configured to use the email address specified in the
previous step. If it is not available, you can create a new Dynamic Endpoint, by pressing the
bu on “Create a new dynamic endpoint…”. This is a person/group of people who receives a
no fica on when Efficiency is too low.

57
4. Finally, let’s manage the format of the email that a recipient will get. Navigate to Manage
Formats and further to the PMP.Centrifugal.Efficiency.Low:

5. View the whole message template, and you will see the format for the email no fica on is
well built out in the PI Digital Twin template. This provides rich informa on about possible
reasons for the alert and ac ons that can be taken by the appropriate personnel.
6. Test that you are receiving no fica ons by clicking on “Test Send” and verify in Outlook that
you receive an email.
7. Trigger manually an EF to confirm that emails are received when EF opens. You can manually
edit the values of the a ributes ‘AllowedTimeAbnormal’ and ‘EventTriggerDeadband’ to
open a new Event Frame or close an already opened Event Frame.

58
 Exercise – Using PI Vision to Summarize “Children”
Dynamically
PI Digital Twin strategy pushes content from inside one element to mul ple child elements. These
children can then easily vary from one deployment to another and over the life of each asset. And
every me a PI Vision screen should be able to reflect the changes and be flexible to represent each
Primary and Secondary assets and their Accessories.

This presents a challenge, “How does PI Vision display asset and accessory architecture that is always
growing and shrinking?”.

To overcome the challenge PI Vision has a func onality of “Collec ons” to dynamically display the
children beneath an element root as selected in PI Vision. This allows PI AF to flex without changing PI
Vision.

This exercise will teach you how this is done from the ground up in PI Vision.

All the equipment should be displayed on one dashboard that would be accessible through PI Vision.
We will be building such dashboard in PI Vision.

1. Navigate to PI Vision in Edge, URL: h ps://pisrv01.pischool.int/pivision.

2. Open the display PI-DigitalTwin.Start

We would like to have a dynamic display with the whole list of our equipment and a list of their
accessories that would be updated automa cally. Collec ons in PI Vision will be used to make it
happen.

Collec ons allow you to find and see all assets of the same type on the current display. With
collec ons, you can choose one or more data symbols and automa cally find and view their related
assets and a ributes on the same display, without having to search for each asset separately. By
changing the collec on search criteria, you can then customize your collec on to see only those assets

59
whose parameters fall within a desired range, or which are in a specific state. The collec on will update
automa cally as the parameters or state of the asset changes.

The following Informa on should be displayed for each piece of equipment: Name, KPI and link to
detailed PI Vision display.

1. From the ‘Assets’ tab navigate to NuGreen > NG > NG.HOU > NG.HOU.PL1 >
NG.HOU.PL1.G-01

2. Select ‘Value’ widget and drag&drop PIVision URL on the display

3. Right click on the Value > Format Value.

a. In Style sec on change Text to Blue,
b. In Visibility sec on select Label to <Custom> and change it to “Detail”, uncheck
all other op ons in Visibility sec on.

4. Add two more a ributes on the display:

60
Attribute name Widget type Format Value > Style Format Value >
Visibility
LongName Value Value - White Value only
KPI Value Value - Yellow Units and Value
5. Arrange all three in one line and group them together.

6. Convert the group to collec on

7. Right click and select ‘Edit Collec on Criteria’. The following se ngs should be
configured. Click ‘Refresh’.

8. Next step would be to set up a dynamic update for Accessories, when the Equipment is
selected. Right click on the list of equipment, select ‘Modify Collec on’

61
 9. Choose the name of the asset and ‘Add Naviga on Link’ from the proper es and the
following se ngs.

10. In the Accessories part of the screen arrange the following a ributes to Pump Efficiency:
Attribute name Widget type Format Value > Style Format Value >
Visibility
LongName Value Text - Blue Label only; Element
name
KPI Value Units and Value

11. Create a Trend

Attribute name Widget type Trend Options Trace Options

KPI Trend Background - Black Color - Green

62
 12. Arrange all three in one line, group them and convert to collec on (like it is shown in
step 7 and 8). The following se ngs should be applied, where search root is
NG\NG.HOU\NG.HOU.PL1\NG.HOU.PL1.G-01

The final screen may look like this

63
64
 Exercise – PI Digital Twin Asset Overview in PI Vision
As a con nua on of the previous exercise, a more sophis cated PI Vision display has been created
earlier to show you how naviga on through all the Enterprise, Primary, Secondary assets and their
Accessories could be organized.

1. Navigate to PI Vision in Edge, URL: h ps://pisrv01.pischool.int/pivision.

2. Open the display PI-DigitalTwin.Home. This home page uses collec ons of containers and
assets to display informa on about currently implemented assets.

3. Press on ‘Detail’ hyperlink and open an individual display to explore more details about
an Asset.
For pump G-01 the detailed screen would include all the informa on around its Motor, Calcula ons
for Efficiency, Vibra on, informa on around Alarms and Events and many more.

65
 Forecasting Library
To implement forecasting analysis in PI Digital Twin, a separate library has been created. It provides
the ability to forecast into the future, based on past and present PI Point values, using linear and
logarithmic regression methods.
Application – Forecasting is categorized as an Accessory to a Primary or Secondary Asset, as well as
other Accessories. This application is very flexible and allows you to forecast any PI Points from the
parent Asset or Accessory intuitively without disrupting the asset configurations and hierarchy.
Each Forecast instance can forecast a single PI Point only. If multiple PI Points need to be forecasted,
the corresponding number of Forecast instances need to be added.
Forecast Types
Linear Forecast
If the PI Point intended to be forecasted has values that either increase or decrease linearly during a
time period, linear regression can be utilized for this purpose. Linear regression attempts to model
the relationship between two variables by fitting a linear equation to the data. With time series data,
one of the variables is always a time value.
A linear regression line has an equation of the form Y = a + bX, where X is the time series variable
and Y is the data variable. The slope of the line is b, and a is the y-intercept (the value of y when x =
0). A visual example of linear regression with time series data is shown below:

In the plot above, the X value is in time units of years, the Y data value is in units of inches, the slope
value for the linear regression line is -2.2923 and the y-intercept is 4624.4.
The goodness-of-fit of this linear line through the data points considered is called the R2 value, or the
coefficient of determination. R2 measures the strength of the relationship between the linear model
and the data variable on a 0 to 1 scale, which in this case is 0.702. After fitting the linear
regression model, the user needs to determine how well the linear model fits the data, based on this
R2 value.

Logarithmic Forecast
If the PI Point intended to be forecasted has values that rise or fall rapidly at first and then steadily
slows over the time period, logarithmic regression can be utilized for this purpose. Logarithmic
regression attempts to model the relationship between two variables by first converting the data into
its logarithm value based on a specific base log, then fitting a linear equation to the logarithmic data.
For instance, if a base log of 10 is selected and the Y value is 82, the corresponding logarithm would
be log10 82 = 1.9138.

66
This regression line has an equation of the form logz(Y) = a + bX, where X is the time series variable, Y is
the data variable and z is the base log value. The slope of the line is b, and a is the y-intercept (the
value of y when x = 0). A visual example of logarithmic regression with time series data is shown
below:

In the plot above, the X value is in time units of weeks, the logz(Y) data value is in units of percent, the
slope value for one of the regression lines (red markers) is -0.0011 and its y-intercept is 1.999.
The goodness-of-fit of this linear line through the data points considered is called the R2 value, or the
coefficient of determination. R2 measures the strength of the relationship between the linear model
and the data variable on a 0 to 1 scale, which for the line above with red markers is 0.9883. After
fitting the linear regression model, the user needs to determine how well the linear model fits the
data, based on this R2 value. The goodness-of-fit will be determined by what base log value is selected
to transform the original data.
The Y data can be converted back to its original form by raising the base log value to the value
of logz(Y). For instance, in the plot above, the Y value would be (assuming the base log, z is 10)
10^(1.992), equivalent to 98.17% at an X value of 6 weeks.

67
 Exercise – Forecasting
Operators have no ced that the Pump Efficiency (implemented in an earlier exercise) value seems to
drop steadily before maintenance is needed and have correlated that pump failure will occur if the
efficiency value drops below 50%. Since it takes maintenance up to 5 days to procure the parts needed,
we would like to start a work order at least 5 days in advance of any expected issues.

For a pilot, on our most cri cal pump, Pump G-01, we will add a Forecas ng accessory to be able to
predict when efficiency drop will reach the cri cal level of 50%.

1. First, load AVEVA.PIDT.cForecas ng library

2. Add a child element to Pump G-01 Efficiency from

<FOR.3.Acc.Forecasts.Regression.Linear> and Reference Type <BAS.Master-
FOR.Forecasts>.

3. Configure the A ributeName a ribute to have a value of Effcy:

68
 4. Check-in and refresh and ensure that the value for Actual a ribute matches Efficiency
a ribute from Pump G-01.
5. Configure the Forecast Data Period a ribute (in the category: iSe ngs) to be +5d
(instead of the default +1d). The other defaults in the iSe ngs category are acceptable.
Under the Forecast Now a ribute, there should be four child a ributes. Update them as
follows:
 Hi: 100, HiReset: 100, Lo: 50, and LoReset: 70
(Note: We only want the forecast to predict when the efficiency is going to be lower than required.
Other forecas ng use cases may require us to have alerts for both hi and lo values so that’s why they’re
built into the template. By se ng the hi values to 100, we avoid nuisance “Forecast High” event frames
when the Efficiency resets back to a GOOD value a er maintenance”.)

The Lo value is the trigger at which a new event frame will be generated when the forecast breaches
that value 5 days out, and the LoReset ensures that the event frame doesn’t close un l the forecasted
value goes back well above that, to avoid unnecessarily closing the Event Frame and then re-opening
due to small varia ons).

6. Check-in again, and then Create or Update Data Reference at the Forecas ng accessory
element:

7. Navigate to the Analyses tab and enable the first two analyses (FOR.1.Linear.Regression
and FOR.2.PostForecastInFuture) by selec ng the analysis and then clicking on the green
start icon at the top.

69
8. Next we will backfill both of these analyses back for 1 month. Right-click on the first
analysis FOR.1.Linear.Regression and select Backfill/Recalculate. Enter the values shown
in the screenshot into the Start and End Time fields and select “Permanently delete
exis ng data and recalculate”, then click on start. Once complete repeat for the second
FOR.2.PostForecastInFuture analysis.

9. Now we will backfill the third analysis, which is an event frame analysis. However, before
doing so, let’s right click on the FOR.3.DetectForecastedThresholdExceeded analysis, and
select Preview Results, and enter a start and end me of ‘*-30d’ and ‘*’, respec vely.
 Then press Generate Results. You should now see where in the past 30 days; this
analysis would have triggered event frames if it had been running.
 Specifically, Event Frames would have been generated in advance of mes when
the Efficiency would have dropped below the specified threshold.
 Since the simulated efficiency is set to periodically ramp down every 30 days, you
should see several of Event Frames in the preview.

10. Verify that The Event Frame Template assigned to the this Analysis is
FOR.ForecastedValueOutsideLimits.

70
 11. Once the preview looks good and the correct EF Template is assigned, right click on the
analysis, and Backfill/Recalculate. (If this op on is grayed out, make sure the analysis is
enabled with the green “check” icon. If not, enable with the green “play” bu on).

12. Set the Start Time to be ‘*-1mo’ and leave the End Time to be ‘*’:

And as we have seen many mes in the past, on almost every occasion during calcula ons
development the end goal – No fica on – should be kept in mind to create ‘work by excep on’ culture.
In the standard configura on for library a no fica on rule is also included that could be used at any
point.

71
72
 Exercise – Forecast in PI Vision
Finally, there is a Forecas ng PI Vision display included with the PI Digital Twin. Re-open the PI Vision
site and navigate to the FOR.3.Acc.Forecasts.Regressions.Linear Display page (alterna vely you can get
there from the A ribute PIVisionURL in PI System Explorer).

From here you can see a visualiza on of the Efficiency vs the Forecasted Results, and Events that have
been generated related to this forecast.

73
Lesson 4. PI Digital Twin project execution
Objectives

 General recommendations for projects.

 Element Templates naming pattern.
 Event Frames naming pattern.

Project delivery considerations

Meaningful Descriptions of all objects in your AF design must be entered. Describe things according
to their function and using standard terms a novice user will recognize. Avoid re-stating the name as
the description. Seek to find helpful words that put the attribute in context.

Asset Hierarchy. The PI Digital Twin toolkit promotes a consistent hierarchy of assets that can be placed
by the user in any container. Assets are constructed in the following scheme shown below. There is no
fixed limit to how deep this structure can be. The designer of assets and accessories should be aware
of the expected depth and use it wisely. To judge that, consider the number of a ributes presented at
each layer.

Asset {Primary}

Accessory {}

Asset {Secondary}

Accessory {}

Sizing of Element Templates refers to the number of attributes and associated analytics in the
template. Avoid having so many attributes that users must scroll vertically to see them all. Scrolling
magnifies the time a user must spend to find data. To avoid this, first look for groups of attributes that
function independently. These can be candidates for accessory templates. Another method is to use
child attributes to provide context behind a single attribute.

Child Attributes are the preferred place for context and settings supportive of a primary attribute.
This keeps the user interface cleaner and smaller at the top level of the element. This functions like a
menu system. Context such as hi/lo limits, max/min traits, timer settings, analysis outputs, etc. are
well organized under the parent attribute they pertain to. Anything of primary focus such as sensor
data streams should be a top-level attribute. To illustrate that check an example below from Vibration
Analysis exercise in Lesson 3.

74
A ribute Traits that are serving as limits and thresholds for alerts should be set with their
configura on property true. This will require check-in of changes and give ability to revert.

Tag Crea on enabled for Sensor Inputs. For any element template (Asset or Accessory) the “b.Sensor”
a ributes should have tag crea on enabled and all applicable tag proper es specified by the template.
These a ributes are the focus of the template’s analy cs and o en adhere to standard se ngs based
on the template’s use-case. The benefit is to see tags built faster and more consistently (name and
proper es) by capturing the exper se of the template SME (Subject Ma er Experts).

1. Physical proper es of interest are compression, excep on, step, zero, span, typical value,
engineering units, square root, display digits, filter. These are dictated by the physics of the
use case and typical instrumenta on resolu on.
2. Further proper es can be specified to capture communica on protocol (ModBus) such as
exdesc, instrumen ag, loca on codes, point source.
a. Customer will work to achieve greater speed and consistency by deriving vendor-
specific templates from a base. These templates specify more proper es to create
more speed and consistency. In the example below the Al var 630 has many more
data streams compared to others. Its template exposes all of these capabili es quickly
in PI System and streamlines deployment.
b. Example:
i. Motor.VFDDriven
ii. Motor.VFDDriven.Al var
iii. Motor.VFDDriven.Al var.630
3. c.Related Streams tags are not to be created by the template, but rather referenced only.

Examples could be found below from Vibration Analysis exercise in Lesson 3.

Sensor/output PI Points should all be Built to be Discovered among siblings. The PI Point name should
be as follows (for cases when the sensor in a Child Element to its Asset):

%@ParentAsset%.%A ribute%

With the use of standard a ribute names and applying the parent asset as a prefix to the a ribute
name generate a simple and repeatable naming of PI Points.

75
(Ex. Accessory #1 for a Vessel requires the vapor space pressure. The vapor space of a vessel pressure
is automa cally named from the Parent Asset and the A ribute name.

L1.L2.L3.Tank1.HeadPress

The Sensor naming conven on allows any subsequent accessory that needs head pressure in Tank1
readily find this PI Point due to its intui ve format and standard vocabulary. When dropped onto the
asset element because it an cipates the correct PI Point name.

(Ex: Discharge Pressure is a prominent sensor for many rota ng equipment assets

NG.HOU.PL1.G-01.DischPress

Sensor A ribute Sta s cs. Sta s cs could be obtained on demand by the user’s client device (Tablet,
Desktop, Mobile) without using AF Analysis and not being stored in the history (Value Retrieval
Methods, Formula Data Reference, or AF Analysis without saving history). Do not overuse this op on
as it may influence performance. More details on performance issues and other considera ons are
available in the ar cle Formula Data Reference VS. Analysis Data Reference for Analysis Inputs.

The final result may look like that (BAS.3.AccSensors.SimpleAnalog template from the
AVEVA.PIDT.!Base library).

A ributes like Avg, Min, Max, Range, Std were configured using Value Retrieval Methods in PI Point
data references as it is shown below:

76
Other a ributes like HiSuggested (Suggested High Alert Threshold) and LoSuggested (Suggested Low
Alert Threshold) were configured using Formula Data Reference. Example is shown below:

Both methods are using the me range set up by the client applica on, like PI Vision or PI System
Explorer (with excep on of Time Range Override op on). The me range could be set up as shown
below:

General Templates considerations

Base Template Only should be checked for element templates that are not designed to be deployed
but rather only form a base for derived templates.

Allow Extensions should not be checked for either element templates or event frame templates by
default. Any addi onal extensions outside of templates will lead to extensions outside of templates
that are impossible to back track or change for all the assets of the same type. In case of an error, it
could significantly complicate the troubleshoo ng process.

Reference Types (Library) must be created to associate element templates with their designated
parent template(s). At deployment this provides the user a guided list or prompt of what child
elements are valid under a given parent element. Component templates must have element
references for all accessory templates that are available as options. Below is an illustration for Base
library from Lesson 2.

77
Categories

Categories should be used at every opportunity as a best prac ce within the PI AF build. Categories
afford any PI user the use of filtering tools embedded in their client tools. PI Admin can also benefit
from filters by category once libraries are merged into a single produc on database. The PI Digital Twin
library objects are categorized by library, asset, accessory.

Categories for A ributes are required to classify all a ributes so that the new and casual users can get
oriented faster in the element. A common set of a ributes’ categories with a preset sort order should
be used on each element. A lower-case alpha prefix is to be used in the category name with no spaces
to put less important categories at the bo om. The current list of a ribute categories can be found in
the PIDigitalTwin.!Base Library and in the screenshot below.

Categories for Element Templates are to be categorized by Library, Container, Asset (Primary or
Secondary), Accessory.

The following categories are categorized by Library:

 Analysis Templates
 Event Frame Templates
 No fica on Rule Templates
 Tables
 Reference

78
 Element template configuration
Element template naming considerations

Element naming patterns are standardized to be the name of the Parent element plus a name of the
current element.

Example (Lesson 2. Exercise Primary Asset):

Parent name NG.HOU.PL1 +

Current element E-01

Full Element name for Heat Exchanger 01 is NG.HOU.PL1.E-01

Names should always be driven by the template’s AF naming pattern feature. Unique and consistently
formatted element names are the baseline for future event frame naming. It is particularly important
to create readable event frame names taken directly from their reference element name as it
drastically simplifies the process of analyzing anomalies coming with Event Frames.

‘Name’ Attribute is the base of the cascading naming scheme for assets and accessories. It is needed
in cases where the element requires a unique identifier from the end user at deployment of the
template. The user will enter the name attribute (aka Local Name) as any alphanumeric they choose.
Avoid describing the global position of the pump in its name as this is done by assuming the name of
its parents. AVEVA best practice is to make the name as small as you can but still be very recognizable
by the end users at the facility. Avoid spaces and use the description field for a written long-text
description of the asset location.

Examples: An outlet pump called 231 could have either of these names

Name: 231

Name: Outlet

‘ProperName’ Attribute for Assets only is used to standardize the local name into something useful
to sort and filter, usually class of equipment. AF creates the proper name attribute by adding the
asset’s single letter classification and hyphen as prefix to the name.

Example: A Pump called 231 would have a proper name G-231

The format for proper name is:

ProperName = SingleLetterAssetClassAbbreviation + “-” + Name

Case1 Element Naming Pattern: Fixed Suffix. This element naming pattern seeds the element with
its parent’s name plus a recognizable suffix. This is useful for calculation Accessories. The suffix can be
a shortened version of the template name. For example, the suffix for an efficiency calc accessory
might be Effcy. Note, we can name accessories generically since they will pick up the asset context
dynamically from their parent when deployed.

Example: A Pump Efficiency Calcula on Accessory: Hou.PL1.G-231.Effcy

The syntax for case 1 would be:

%..\Element%.TemplateApplica onSuffix

79
 Where TemplateApplica onSuffix would be a fixed literal string.

Case2 Element Naming pa erns with Flexible Suffix(es) is required for some cases. Suffix text set by
the end user at deployment in element name makes user naviga on easy. In these cases, the suffix(es)
must be an a ribute in the element. These suffix a ributes are to be entered at deployment.

The syntax for a Dynamic element would be

%@ParentAsset% .<Func onDescriptor>%.%@LocalName%

One example of this technique is naming the Fluid Loca on specifica on for an asset. The
FluidLoca on a ribute collects the name or nickname of the process fluid. The FluidLoca on can be
used as the suffix in the name of the Physical Property Element.

Case3 Element Naming pa ern across Primary/Secondary. Some interna onal industry taxonomy
standards require names between primary and secondary to be closely connected. One such case is
for rota ng equipment and their drivers.

The primary asset name follows the syntax

Element Name = %@..\Element%.%@Name|ProperName%

The secondary (driver) name is made by inser ng single le er abbrevia on for its asset class
immediately a er the single le er abbrevia on of the primary. This name helps the user with sor ng
by making secondary assets appear a er primary accessories. Also, the user can see this classifica on
faster at full scale.

The secondary asset name follows the syntax:

Element Name = %@..\|ParentName% . +

PrimaryAssetSingleLe erAbbrev . +

SecondaryAssetSingleLe erAbbrev + “-“ +

%@Name|ProperName%

Example: A pump Hou.PL1.G-01 and its motor Hou.PL1.GM-01

Default attributes to define names

A er launching a template into an element, the first thing to do is configure any a ributes unique to
this instance. Any a ribute that requires entry from the user should have its Configura on property
checked, giving it the Pencil icon in PI System Explorer. This is a cue to user where to check on launch
of an element. The default a ribute is indicated by the black and white Checkmark icon.

h ps://docs.aveva.com/bundle/pi-server-af-pse-f/page/1018787.html

Promp ng User about the Name a ribute. The default values of Name a ributes should lead the
user to enter the name where it is needed and to Re-Evaluate the naming pa ern of the element once
all configura on a ributes are entered.

Default value for Primary Assets should prompt for entry:

“Enter name a ribute and re-evaluate element name”.

80
 Default for accessories or secondary assets that allow a user-entered suffix:

“Op onal”

Re-Evaluate Naming Pa erns in bulk. Our best prac ce is to always have the element configura on in
place such that the en re AF Database can be re-evaluated for naming pa erns in bulk and achieve
the latest name for every element.

81
 Event Frames configuration
Event Frame (EF) naming consistency across the en re PI Digital Twin library is extremely cri cal. This
gives the end-user a solid foo ng to digest event frames faster. This also allows us to summarize the
event concisely for SMS text messages by using the event frame name in the subject line of the
no fica on. Finally, a consistent event frame naming pa ern allows the user to build reports quickly
just from the name.

Event Frames naming considerations

1. Each Event Frame name starts with the name of the Element that generated the event frame.
This will be a unique name (element long name). Accessories and secondary assets will have
their name inherited from the primary. The name of an Element is most o en abbreviated and
coded by class loosely to ISO and ISA standards. It is well-known resident opera on teams, less
known to newcomers.
2. A er the element name, the StartTriggerName will describe the type of anomaly that has
occurred. The StartTriggerName must always be the exact Start Trigger text as mapped directly
from the EF genera on analysis to the Event Frame a ributes.
3. Next, the ElementDescrip on is included to provide descrip ve process context of the asset’s
service. This context will always be the %Descrip on% at the parent asset level (primary or
secondary). We carry this asset descrip on down to all accessories and onto all EF they
generate as an a ribute. This provides the process context in the EF name and no fica on
body. This is also helpful at scale for filter/searches in the EF Visualiza on/BI tools.
4. Finally, the StartTime is included in the EF name to iden fy quickly and uniquely by when the
event started.

The event frame naming pa ern syntax using subs tu on parameters will be:

%ELEMENT% %@StartTriggerName% - %ELEMENTDESCRIPTION% %STARTTIME:yyyy-MM-dd

HH:mm:ss%

An example EF Name would look something like this in a live produc on system:
Cha.V2201.T110.E-103 FoulingForecastSuggestsCleaning – XLine Reactor Feed Cooler 2023-01-31
08:21:11

More informa on on subs tu on parameters for Event Frames naming pa erns

h ps://docs.aveva.com/bundle/pi-server-af-pse/page/1021820.html

Event Frames attribute templates

EF A ribute templates are required to focus the a en on of the user on the key a ributes that must
be considered when responding to the event. Choose these a ributes and calcula ons very selec vely.

WatchPeriod A ribute refers to a span of me in the past (archive data) or in the future (future data)
to analyse. It is a String type configura on a ribute where the user enters the expression or a
mespan. The ParseTime() func on can operate directly on the WatchPeriod expression to calculate
the mestamp.

82
 Example:

Given: WatchPeriod = “-1h”

Output: ParseTime("-1h") Returns Timestamp One hour in the past from the current
time

AllowedTimeAbnormal A ribute refers to a me frac on on top of a WatchPeriod, when the signal

could be outside of limits.

EventTriggerDeadband A ribute refers to a value frac on required to return to normal.

Derived EF a ribute templates should be used for every event to ensure consistency of the base
a ributes. The base template that was used as a part of this course is “BAS.Asset Health Event”. The
base template cannot be deployed itself. Every event frame template should have specific a ributes
to highlight the event characteris cs. At a minimum, all the per nent data from the reference element
should be listed as an EF a ribute in order to be readily available to all EF client tools and repor ng
services.

Event Frames without No fica on Rules. It is best to design event frames that lead immediately to
ac ons and thus use of a no fica on. However, there can be cases where event frames are designed
to be exposed to the user through repor ng tools such as PowerBI, Tableau, SpotFire, MS Excel and
etc. Scru nize event frames without no fica ons very carefully. Using Event Frames as intermediate
data can add risk of performance issues.

Event Frame Start Trigger Names should be short descrip ve readable phrases that describe the
trigger condi on in simple English. Avoid grouping mul ple trigger condi ons into one trigger
statement and calling it a “general” name. Do not use dots or dashes between words. Use spaces. This
concise piece of text should describe the event in the simplest and human-readable terms. For
example: “OverHeated”, “Tank_Empty”, “TooManyStarts”, “HighControllerStrain”, “Cavita ng”.

Imagine how your en re event frame name will read. For example:

DOW.PHX.U1.PMP-101 Overheated yyyy-MM-dd HH:mm

Event Frames general recommendations

Priority se ng should be set up on every event frame trigger, so later it could be reused for
No fica ons distribu on list. By default (Major, Cri cal = “subscrip on target A”), (Info, Minor,
Warning = “subscrip on target B”).

Reason Codes is required for all event frames. Every event frame template is to have its own dedicated
reason code list that aligns with the known failure modes and root causes. Reason codes are helpful
when a trigger condi on (symptom) is vague, and the root cause could be a variety of things. Reason
codes tell the user what to look for. Examine your triggers and their troubleshoo ng steps to design
your Reason Code list. Be sure to e Reason Code wording closely to the wording you have in the
no fica on. Use mul - ered reason codes for complex lists.

Event Frames Acknowledge shall be enabled on all event frame templates.

83
Lesson 5. AVEVA PI Digital Twin in the Cloud
- This sec on is a brief introduc on to possible integra on between PI System (PI Digital
Twin), AVEVA Connect Data Services (former AVEVA Data Hub) and AVEVA Connect
- Visualiza on Service.

Hybrid PI Data Infrastructure – Global and Secure

To extend the PI Server on-premises, AVEVA provides tenant space in the AVEVA CONNECT cloud
pla orm to elevate data and share broadly. AVEVA CONNECT cloud pla orm receives transfers of data
from PI Server(s) to be aggregated, stored, analysed and shared broadly. The overarching benefit is to
share any PI Server content selec vely with new persona, at greater frequency and greater historical
depth. PI Digital Twin significantly helps in the process with pre-defined content for cri cal equipment
in the plant.

This is especially helpful for digital twin models tasked with Asset Performance Management, Asset
Condi on Monitoring and Con nuous Process Improvement. Broad sharing of anomalies and
opera ons history between produc on units, sites, corporate experts, suppliers, external consultants,
and vendors can transform opera ons into a proac ve culture that is safer and more produc ve.

84
To get started using CONNECT, you pick the informa on from PI Server(s) that you want to share in the
cloud. This step allows you to condense the informa on into only what cloud users have a business
need to see. Further, it simplifies the consumer experience to be fast and lightweight.

Once the data is in the cloud there are several ways to visualize it. The na ve visualiza on tool is AVEVA
CONNECT Visualiza on Services (CVS). We’ll highlight some typical user scenarios that illustrate a
hybrid on-premises PI Server using AVEVA CONNECT cloud services.

Scenario 1: Community use of data between the Plant and OEM.

Plant Manager pushes a culture of proac ve, early ac on to avoid damages. PI System watches
vibra on of a machine and detects a significant and sustained increase. Personnel on the Plant validate
the issue by checking the history of load and speed. PI System flags the event and sends alerts to first
responders with detailed instruc ons. For some machines, an OEM supplier is alerted since they are
under contract to offer expert guidance and have replacement parts in stock. The opera ons team
receives recommended ac ons within hours from the OEM consultants in rich detail, then takes extra
ac ons from their experiences. The performed ac ons slow the progression and verify the issue. Later
all the necessary parts are ordered, and a repair is scheduled at the next planned outage.

Result: a significant saving on me and money through a close collabora on and data access between
Opera ons Team and OEM.

A dashboard in CVS may look like the one below.

85
Scenario 2: Global Enterprise Process Improvement director needs to see the efficiency of all their
produc on machines over the past 5 years ranked from the worst. They need to know are the losses
clustered around a site, a machine, a climate, a failure mode. What were the correc ve ac ons that
worked and those that didn’t work? Could we spend capital and see a payback in produc on savings
that pays for the project in 6 months or less?

The further chain of thoughts could be around finding a pa ern across similar devia ons.

A possible conclusion could be: a single machine is the culprit and most issues have the same pa ern
and cause. Targe ng capital on this machine to install more sensors will allow Opera ons Team to
manage the asset be er and avoid mis-opera on, avoid failures.

An example of possible dashboard is shown below.

86
Summary
Reaching the end of this training, we can summarize the key benefits of the PI Digital Twin approach,
which uses accessories to enhance modularity, scalability, integra on, and opera onal insights.

Modularity and Scalability

 Modular Structure with Accessories: the PI Digital Twin uses accessories, which are reusable,
modular components designed for specific func ons. These accessories can be applied in
various combina ons to fit the specific needs of each asset, providing a highly scalable and
flexible solu on.
 Template Reuse: instead of crea ng thousands of different templates with numerous
a ributes each, the PI Digital Twin leverages a smaller number of highly modular templates
(40-50 pump-related templates). Each accessory can be reused across different asset types,
reducing duplica on of effort and ensuring consistency.

Consistency and Ease of Use

 Consistent Naming Conven ons: ensures that templates and elements have self-explanatory,
consistent naming conven ons, making them easy to search and use.
 Modular Templates: modular templates reduce complexity and improve maintainability. Logic
is not duplicated, and users can easily see the diverse make-up of each asset.

Integration and Cross-Application Links

 Cross-Applica on Integra on: establishes links between equipment and external engineering,
maintenance, and repor ng applica ons, facilita ng seamless data gathering, analysis, and
situa onal awareness.
 Enhanced Opera onal Insight: accessories are designed to detect pa erns, send alerts, and
provide instruc ons, offering a detailed opera onal overview.

Comprehensive Operational Insight

 Detailed and Dynamic Representa on: provides a comprehensive and dynamic digital
representa on of physical assets using accessories. This enables detailed insights into
opera ons and facilitates mely decision-making.
 Advanced Analy cs and No fica ons: uses accessories to perform advanced calcula ons,
detect anomalies, and generate event frames and no fica ons, enhancing opera onal
awareness and response. The ability to fine-tune analy cs to ensure the genera on of
meaningful and ac onable no fica ons helps prevent alert fa gue and maintains focus on
cri cal issues.
 Event Frame Management: PI Digital Twin emphasizes the importance of well-tuned analy cs
and event frames to avoid crea ng a "spam generator" effect. By ensuring only significant
no fica ons are generated, the system enhances user efficiency and opera onal
effec veness.

Flexibility and Collaboration

87
  Support for Mul ple Authors: allows mul ple authors to create templates based on best
prac ces and expert knowledge, ensuring robustness and accuracy.
 Modular Design: accessories can be easily modified and extended, suppor ng con nuous
improvement and adapta on to changing opera onal needs.

Summary

In this training we presented the concept of PI System Digital Twin, learning what PI Digital Twin is and
how to set it up, providing you with the essen al founda onal knowledge required for the subsequent
lessons.

In the first lesson, we introduced to the concepts of the AVEVA PI System and AVEVA Digital Twin. A
detailed explana on of the PI Digital Twin approach was provided, focusing on the modularity and
scalability offered by accessories. These accessories are reusable, modular components designed for
specific func ons, allowing for template reuse. This significantly reduces the number of templates
needed and ensures consistency across various asset types.

We then delved into the asset structure, par cularly focusing on Asset Framework (AF) libraries for the
PI Digital Twin. Prac cal exercises including loading libraries, crea ng containers, primary assets, and
secondary assets. This hands-on approach ensured that you could effec vely manage and organize
assets within the PI System.

The third lesson was cri cal as it covered the use of accessories in the PI Digital Twin. We engaged in
exercises such as crea ng a flow rate sensor, a pump efficiency accessory, and performing vibra on
analysis. Key recommenda ons for tuning analy cs were provided, emphasizing the importance of
well-tuned analy cs and event frames to avoid genera ng excessive no fica ons. This lesson
highlighted the PI Digital Twin's ability to generate meaningful no fica ons, thus enhancing
opera onal awareness and response.

The focus shi ed to project delivery considera ons, element template configura on, and event frames
configura on in the fourth lesson. We presented indica ons of how to execute PI Digital Twin projects
effec vely, ensuring accurate and efficient implementa on.

In the final lesson, we explored the hybrid PI Data Infrastructure, with an emphasis on global and
secure deployment op ons. Insights were provided on leveraging cloud capabili es to enhance the
scalability and accessibility of the PI Digital Twin.

Throughout the training, we provided a comprehensive understanding of the PI Digital Twin, from
founda onal concepts to prac cal applica on, project execu on, and cloud integra on.

The PI Digital Twin approach, with its use of accessories, offers a highly modular, scalable, and
integrated solu on. It enhances opera onal insights, ensures consistency, and supports seamless
integra on with external applica ons. The modular design of accessories allows for efficient
management of diverse asset combina ons, reducing complexity and improving maintainability.
Addi onally, the PI Digital Twin emphasizes well-tuned analy cs to generate only significant and
ac onable no fica ons, avoiding alert fa gue and ensuring users focus on cri cal issues.

88
References
- Petroleum, petrochemical and natural gas industries — Collection and exchange
of reliability and maintenance data for equipment (ISO Standard No.
14224:2016):
- https://www.iso.org/obp/ui/en/#iso:std:64076:en.
- General documenta on https://docs.aveva.com/.
- AVEVA PI System

• AVEVA PI Server 2018 SP3

- AVEVA PI Vision

• AVEVA PI Vision 2022 User Guide

• AVEVA PI Vision 2022 Installa on and Administra on Guide

89