VapCyc® Workshop:

Integrating User Component Models

with VapCyc® Standard
Ransisi Huang, Vikrant Aute

Sept. 10, 2018, Semi-Annual Meeting

Modeling & Optimization Consortium
Center for Environmental Energy Engineering
Department of Mechanical Engineering
University of Maryland, College Park, MD 20742
 Content
Prerequisites
Overview of Integrating User-defined Components
Introduction to VapCyc® Standard
Component Properties
Boundary Conditions
Component Lifetime and Events
Sample Component Models:
Heat load-based heat exchanger model
Efficiency-based compressor model
Conducting Simulation with User-component
VapCyc® Component Tester
Cycle Simulation in VapCyc®
Parametric Analysis

Copyright© 2018 Center for Environmental Energy Engineering, University of Maryland.

2
 Prerequisites
Background
Basics of Heat Transfer, Thermodynamics
Basics of Simulation
VapCyc related papers (Winkler et al., IJR)
Object Oriented Programming – Polymorphism and Interfaces
Experience in programming with JIT/runtime-based
programming languages (C#, VB.NET)
Tools
Microsoft Visual Studio 2015+
VapCyc setup files or valid installation
Microsoft Windows 7 +, x86 (with 64-bit support in the future),
.NET Framework 4.0+

Copyright© 2018 Center for Environmental Energy Engineering, University of Maryland.

3
 Introduction
The way we
understand vapor
compression system
Compressor, HX,
pipe, etc.
VapCyc® Solver
The way VapCyc®
NLSolver
solver understands
vapor compression
system
Black box component
which can be
interacted with using
the VapCyc®
Component inputs and execution outputs Standard

Copyright© 2018 Center for Environmental Energy Engineering, University of Maryland.

4
 User Component Integration
Developed by CEEE VapCyc Component Developed by You
Does NOT work without
Your Performance Data
Can reside locally/remotely

Interface to
Component
Your
VapCyc Performance
Component
Data/Library/DLL
DLL

User Component: Any DLL/callable-library that represents/computes

component performance for a given set of geometric and operating inputs.

VapCyc Component: A User-Component that implements (‘obeys’) the

VapCyc Component Standard Interface

Copyright© 2018 Center for Environmental Energy Engineering, University of Maryland.

5
 User Component Distribution
Developed by CEEE Developed by CS Developed by
Does NOT work without
CS Performance Data
Component Supplier (CS)

VapCyc, Interface to CS CS Component

CoilDesigner or Component Performance
CEEE Software Performance Data/Library/DLL

Distributed by CEEE Supplied at CS Discretion

Copyright© 2018 Center for Environmental Energy Engineering, University of Maryland.

6
 Incorporating User-Defined Components
1. Verify that the Component DLL is ‘callable’ from a .NET
console/WinForms application; in/out of Visual Studio
2. Implement VapCyc Standard to ‘expose’ the Component DLL to
VapCyc
3. Test the newly developed VapCyc component using the VapCyc
Component Tester
4. Add new Component to VapCyc installation (.components file)
5. Test in VapCyc
I. Verify physics
II. Verify simulations: single run, parametric analysis
III. Verify file save/load
IV. Check for memory leaks, unmanaged resources etc.
6. Test on multiple desktops (e.g., OS, MS Office, x86/x64
combinations)
7. Distribution considerations (documentation, versioning, backward-
compatibility – within component and with VapCyc versions)
Copyright© 2018 Center for Environmental Energy Engineering, University of Maryland.
7
 Introduction to VapCyc®
Standard

8
 Introduction to VapCyc® Standard

Standardized
Framework

“Followed” by all
component models
VapCyc
Solver Component
models Enable solver-
component
communication

Copyright© 2018 Center for Environmental Energy Engineering, University of Maryland.

9
 VapCyc® Standard I (IVC1)
IVC1
Component
Model
• Refrigerant
• Charge
• Heat Capacity
• Power
• Ports
Inlet Outlet
Port(s) Port(s)
• PortStates
• Pin • Pout • P
Component • h
• hin • hout
• Tin Model • Tout • T
• xin • xout • x
• 𝒎𝒎̇ • 𝒎𝒎̇ • 𝑚𝑚̇
States represented using:
PortStates

Copyright© 2018 Center for Environmental Energy Engineering, University of Maryland.

10
 VapCyc® Standard II (IVC2)
Air (Open stream) IVC2
C C Component Model
R-404A
(Closed Loop)
• Fluid Groups
• Refrigerant
• Charge
E
Water CO2 (Closed • Heat Capacity
(Open Loop) • Power
Stream) • Ports
E
• PortStates:
P, h, T, x, 𝑚𝑚̇

Inlet Ports: Pin, hin, Outlet Ports: Pin,

Tin, xin, 𝒎𝒎̇ Evaporator hin, Tin, xin, 𝒎𝒎̇

Inlet Ports : Pin, hin, Model Outlet Ports: Pin,

Tin, xin, 𝒎𝒎̇ hin, Tin, xin, 𝒎𝒎̇

Fluid Group 1: CO2 (Closed loop)

Fluid Group 2: Water (Open stream)
Copyright© 2018 Center for Environmental Energy Engineering, University of Maryland.
11
 Component Properties

Independent Properties

Inlet Outlet
Port(s) Port(s)
• Pin Component • Pout
• hin Model • hout
• Tin • Tout
• xin • xout
• 𝒎𝒎̇ • 𝒎𝒎̇

Dependent Properties

Only numeric, strongly-typed values are supported as

Component Properties, see next slide.
Copyright© 2018 Center for Environmental Energy Engineering, University of Maryland.
12
 Component Properties (contd.)
Independent Properties
Strongly-typed values with physical quantity and units associated with
them
Can be changed before Simulation begins
Are exposed in the UI during Parametric Analysis
Caution: property dependencies (i.e., fin density and fin thickness)
NOT all component characteristics need to be Independent Properties;
e.g., CoilDesigner file path
Component model may choose to have zero independent properties
Dependent Properties
Read-Only, Strongly typed values, similar to Independent Properties
Are outputs of the Simulation
VapCyc solver does NOT know anything about them
e.g., Avg. HTC reported by CoilDesigner component

Copyright© 2018 Center for Environmental Energy Engineering, University of Maryland.

13
 Boundary Condition Type
A Inlet Outlet Inputs
hin is optional
Port(s) Port(s)
• Pin Component • Pout
• hin Model (e.g. HX, • hout
• Tin pipe) • Tout
• xin • xout
• 𝒎𝒎̇ Model outputs
• 𝒎𝒎̇ Massflow based Boundary Condition

For both
Inputs and
B Inlet Outlet Outputs,
Port(s) Component Port(s) user-
• Pin • Pout Component
• hin Model (e.g. • hout MUST use
compressor, exp. (P,T,x)
• Tin • Tout
• xin device) • xout
• 𝒎𝒎̇ • 𝒎𝒎̇
Pressure-Based Boundary Condition

Copyright© 2018 Center for Environmental Energy Engineering, University of Maryland.

14
 Component Lifetime and
VapCyc® Standard Structure

15
 Component Lifetime
Initializes fluid groups, boundary condition Initialize
type, property folder paths, independent VapCyc® Component
and dependent properties etc. Initialization
Loads Component State & Independent Initialize Component
Properties from file Load/Save
Load Component State
Provides Modal UI dialog for users to
change the Independent Properties Edit Component User
Parameters Interface
Sets information for the property routine
library required for model execution. Set Property
Routine Property
Provides the option to conduct pre-
Routine Setup
processing prior the component model
execution. Begin Simulation 2
Executes the underlying Component Pre- /Post-
Run Component Process
model code (or calls other relevant codes). 1
Provides the option to conduct post-
processing after the simulation ends, but End Simulation Model
Execution
before the Component output is accessed.
Saves Independent Properties of the Save Cycle
Component
component to an XML node. Termination
Terminate Component

1: Single VapCyc run

2: Parametric runs (e.g., [change property, run simulation])
Exit VapCyc®
Copyright© 2018 Center for Environmental Energy Engineering, University of Maryland.
16
 VapCyc® Standard Structure
Component
Initialization

Save/Load

User
Interface
Property
Routine Setup
Pre- and
post-process
Model
Execution
Component
Termination
Copyright© 2018 Center for Environmental Energy Engineering, University of Maryland.
17
 Component Initialization
Component
Initialization

initializationData provides information about the working folder path,

property folder paths and property library type
Always the first method to be called once the Component is created
The method creates and/or initializes
PortStates for IVC1 and FluidGroups for IVC2 ,
Boundary condition type,
Folder paths: Application path, temp folders, component folder
etc.
Property library,
Working fluids,
Independent and dependent properties
The method is called only once during the lifetime of a component
Copyright© 2018 Center for Environmental Energy Engineering, University of Maryland.
18
 Loading and Saving
Load/Save

LoadState
The method loads component state including Independent Properties of
the component from an XML node
stateNode is an XML node storing component Independent Properties. It
is essentially the same XML node created by the Component Model
when the SaveState method is called
SaveState
The method saves the component properties to an XML Node and
returns the Node
The Cycle/Solver takes this Node and appends it to a list of nodes for
saving/loading of components. The Component Model code may choose
to encrypt the contents of this node.
The Component Model code must also ensure backward compatibility
when making updates to Component Models
Copyright© 2018 Center for Environmental Energy Engineering, University of Maryland.
19
 User Interface
User
Interface
This method is mainly used to facilitate User Interaction through a graphical
user interface
Upon invocation, the component model ideally displays a modal dialog
where the user can change the independent properties and any other
relevant parameters of the component
May include any Branding or Licensing information

Copyright© 2018 Center for Environmental Energy Engineering, University of Maryland.

20
 Property Routine Setup
Property
Routine Setup
This method sets information to the component about the property folder
paths and property library type that the user may specify on Edit System
Parameters after the cycle has been initialized.
Caution: Mixing property libraries and using Enthalpy values

Copyright© 2018 Center for Environmental Energy Engineering, University of Maryland.

21
 Pre- and Post-processing
Pre-/Post-
process

BeginSimulation
Notifies the Component that the simulation is about to commence. The
Component can use this event to conduct any initializations etc.
Can be called multiple times during the component lifetime
May choose to clear the Message List
EndSimulation
Notifies the Component that the simulation has ended
status argument informs the component about how the simulation ended,
e.g., successful, failed etc.; Component may use this information for post
processing
Can be called multiple times during the component lifetime

Both methods return True/False: A simulation is terminated is

any of Component models in the cycle returns False
Copyright© 2018 Center for Environmental Energy Engineering, University of Maryland.
22
 Model Execution
Model
Execution

arg provides information about Cancellation token, component ID, solution

stage etc.
Cancellation Token: Facilitates termination of long running simulations
Component ID: Distinguish between multiple instances of the same Component
Solution Stage [Guess Runs, Newton Iteration..]: Allows Component to be more intelligent
Simulation ID: Globally unique ID for component debugging/tracking
The method executes the physics-based or performance map model
Returns 0 for success, non-zero for error/warning; Non-Zero return value
would terminate the simulation
Example contents of a Run Method in a HX
Access PortStates to get inlet (P,h, mdot)
Run HX model code
Populate outlet PortStates (Pout, hout, Tout….)
Populate: Charge, HeatOut, PowerConsumption etc.

May also include a check for license validity

Copyright© 2018 Center for Environmental Energy Engineering, University of Maryland.
23
 Signed Properties
IVC1 IVC2
HeatOut For each Fluid Group
Heat gained by the HeatOut
refrigerant is negative
Heat gained by the
PowerConsumption refrigerant is negative
Always positive PowerConsumption
WorkOut Always positive
e.g. negative for a WorkOut
compressor
e.g. negative for a
PortStates compressor
𝑚𝑚̇ Ports
Negative for inlet 𝑚𝑚,
̇ positive
for outlet 𝑚𝑚̇ PortStates: 𝑚𝑚̇
Signed properties are used for System level Negative for inlet 𝑚𝑚,̇
mass/energy balance. positive for outlet 𝑚𝑚̇
Copyright© 2018 Center for Environmental Energy Engineering, University of Maryland.
24
 Diagnostics

Message List can be populated during

simulation; all messages are reported at then
end of a simulation
TraceSwitch: Set by the end-user, controls the
level of output to be reported for diagnostic
purposes
Verbose, Information, Error,….

Copyright© 2018 Center for Environmental Energy Engineering, University of Maryland.

25
 Component Termination
Component
Termination

Used to terminate the component

Called before the component is unloaded from the program, or when
the cycle is disposed/destroyed
Must implement any clean up, especially for native resources or
unmanaged codes to avoid memory leaks
e.g., unload REFPROP.DLL

Copyright© 2018 Center for Environmental Energy Engineering, University of Maryland.

26
 Sample Component Models

27
 Heat Load-based HX
Q Mass flow rate-based
Pin, hin, 𝑚𝑚̇ 𝑖𝑖𝑖𝑖
Boundary Condition type
∆Tsat Independent Properties
Pout, hout, 𝑚𝑚̇ 𝑜𝑜𝑜𝑜𝑜𝑜 Heat load (+, -)
Saturation temperature
VapCyc® Standard drop

VapCyc® Solver

NLSolver

Copyright© 2018 Center for Environmental Energy Engineering, University of Maryland.

28
 Efficiency-based Compressor
Pressure-based
Discharge Boundary Condition Type
Pout, hout, 𝑚𝑚̇ 𝑜𝑜𝑜𝑜𝑜𝑜
Independent Properties
Displacement
Volumetric Efficiency
𝜼𝜼𝒗𝒗 , 𝜼𝜼𝒔𝒔 , RPM
RPM, Disp, Isentropic Efficiency
𝜼𝜼𝒎𝒎 Mechanical Efficiency

Pin, hin, 𝑚𝑚̇ 𝑖𝑖𝑖𝑖

Copyright© 2018 Center for Environmental Energy Engineering, University of Maryland.

29
 Conducting Simulation with
User-component

30
 Component Tester
1. Use Browse to load the DLL of
the user component.
1
2. Select the component model
3 from the list.
2 3. Click at initialize to initialize the
component and select appropriate
BC (Boundary Condition) type.
4. Click at Edit Component to
5 invocate the component user
interface and specify the
component Independent
Properties.
5. Provide refrigerant information
4 6 and inlet refrigerant states.
6. Click at Run for execution
results.

Copyright© 2018 Center for Environmental Energy Engineering, University of Maryland.

31
 Adding User Component to Component List
1
1. Go to the Components folder of the
VapCyc® installation folder.
2. Copy the user component DLL
here.
3&4
3. Create a new COMPONENTS file
and name it the same as the user
2 DLL file.
4. Add component type, class name,
library name and friendly name in the
file.
5 5. Start VapCyc®, right click at the
appropriate component and select
Choose Component to find the newly
added user component in Available
Component Models.

Copyright© 2018 Center for Environmental Energy Engineering, University of Maryland.

32
 Conducting Cycle Simulation
1. After the user component is
successfully added to the
component list, right click at it and
chose Edit Component to
invocate the component user
interface.
2. Specify the Independent
Properties.
3. Set the information for all the
other components.
4. Go to Edit System Parameters
to provide cycle-level inputs.
5. Click at Run to start the
simulation.

Copyright© 2018 Center for Environmental Energy Engineering, University of Maryland.

33
 Conducting Parametric Analysis
1. Go to Project -> Parametric
Study…
2. Select appropriate component
in Available Components.
3. Specify the appropriate
Independent Properties for
parametric runs.
4. Provide settings for the
parametric study as appropriate.
5. Click at Update Table at the
bottom and then click at Run
Parametric Analysis.

Copyright© 2018 Center for Environmental Energy Engineering, University of Maryland.

34
 Thank you!

35