CAPE-OPEN Wizard User Manual

The CAPE-OPEN Wizard consists of two parts:

The project wizard that generates skeleton code for new CAPE-OPEN components.
The runtime library that wraps the most common CAPE-OPEN functionality

Using the wizard to create a new project

The wizard is available as a stand-alone program or can be installed as a Delphi wizard.

Compiling and running the wizard inside Delphi: The source code for the Delphi wizard is available in the \<CapeOpenFolder>\CapeOpenWizard folder. To install the wizard in Delphi, open the CapeOpenWizard.dpk file in Delphi, view the Project Manager, right-click on the CapeOpenWizard.bpl entry and click on install. Alternatively build the package, then install the wizard by clicking on Install Packages..., then click on Add..., browse to the output folder for compiled packages and select the CapeOpenWizard.bpl file. This should install the wizard and make it available when clicking on File, New and selecting Other.

Compiling and running the stand-alone wizard: The source code for the stand-alone wizard is available in the \<CapeOpenFolder>\CapeOpenWizard\StandAlone folder. Open the StandAloneWizard.dpr file in Delphi and compile and run.

Creating a new CapeOpen project using the wizard: After launching the wizard, the user should see the following window:

The different fields in the wizard are used as follows:

Project name. This value should be a valid Delphi project name, since it will be used as the project name.
Project folder. This value should contain a valid folder name where the newly created project will be saved. This should preferably be an empty folder since Cape-Open projects may contain unit names that are the same. Creating a new Cape-Open project in a folder containing an existing Cape-Open project may overwrite some of the files of the existing project.
Add type library to project file. Some versions of Delphi (e.g. Delphi 7) requires that the type library (projname_TLB.pas) be included in the project file, else the compiler will generate an error. On the other hand including the type library in the project sometimes generate funny errors caused by the Delphi Type Library Editor. The reference to the type library file (projname_TLB.pas) in the project file can be changed at a later stage from inside Delphi.

The tab control contains information relevant to each CapeOpen model in the project:

Component name. The name identifying the particular component. The COM ID of a component will be of the form ProjectName.ComponentName
CAPE-OPEN component. The type of component to create.
CAPE-OPEN version. Select the version of the CAPE-OPEN standard that should be implemented. Note that a larger number typically implies more functionality, but this may not be widely supported.
Description, Component version, Vendor URL, Help URL and About. These values are optional and are used to display additional information about the component before it is instantiated.

To add extra components to the project, click the Add button. Once all the components have been specified, click the Create project button. This will create a new ActiveX library project, a type library, a Pascal unit for every CAPE-OPEN component in the project, a LinkGUIDsUnit.pas file and (if a Unit component is in the project) a simple editor in InputForm.pas.

Coding a component

CAPE-OPEN Unit

A lot of functionality required for a Unit by the CAPE-OPEN specification is contained in a parent class structure. After creating a new CAPE-OPEN Unit, only four methods are automatically created in the new class: PMCInitialize, Terminate, Edit and Calculate. Typical use of each method is described below.

PMCInitialize. This method is used to create objects that will be used by this Unit. Typically ports and parameters that are associated with the Unit are created here. Other actions performed in this method could include creation of a model entity (if it is written as an object class), a GUI form for the model etc. Note that actions performed here should not be time consuming since some simulators could time out and consider the creation of this instance a failure.
PMCTerminate. This method is used to free up resources/objects allocated in the PMCInitialize method.
Edit. This method is called from the simulator if this Unit should display its editor GUI. Displaying a GUI is optional so if the Unit does not have a need for a GUI then just do nothing. Note that showing a Delphi form correctly on top of a simulator's GUI sometimes require one of the following hacks:
- To show a modal Delphi form, call
  Form.Show; Form.Close; Form.ShowModal;
- To show a nonmodal Delphi form , call
  Form.Show; SetWindowPos(Form.Handle, HWND_TOPMOST, Form.Left, Form.Top, Form.Width, Form.Height, SWP_SHOWWINDOW + SWP_NOSIZE);
Calculate. This method gets called when the Unit is supposed to calculate itself. Typically information is read from one or more inlet streams, the model is solved and output is written to one or more outlet streams. After outlet stream information has been written, each outlet stream's CalcEquilibrium method should be called.

Additional functionality that can be customized include:

Reporting, by overriding the following methods:
- Get_reports
- Get_selectedReport
- ProduceReport
- Set_selectedReport
Refer to the SimpleHX unit in the ExampleUnitOps project for an example of simple reporting.
Persistance, by overriding the following methods:
- Load
- Save
- GetSizeMax (optional)
Refer to the Load/Save code in the TBasePMC class to see how basic persistance can be implemented.

Thermo property package

A parent class for the CAPE-OPEN Property Package component has not yet been written. Refer to the PropPackage unit in the TestPropPackage project for an example of a property package class.

Thermo property system

A Thermo property system is a class that can be used to select/configure a property package from a list of available packages. Refer to the ThermoSystemUnit in the TestPropPackage project for an example of a property system class.

Debugging

A CAPE-OPEN Wizard model can be debugged inside Delphi by selecting Debug info under Compiler options. Specify the path to a simulator exe under Run|Parameters| Host Application. Sometimes this does not work properly. The alternative is to start the executable outside the IDE and then attach to the process from inside Delphi (Run|Attach to process).

One can use COCO for testing CAPE-OPEN components, get more detailed results about compliance to the CAPE-OPEN standard, the values and formats of parameters passed over COM and possible error values returned via COM.

Known issues

The Delphi Type library editor sometimes add bogus methods to the TCapeUnit class in CapeUnitIMPL.pas (observed in Delphi 6, 7, 2005, Turbo Delphi Explorer 2006). Just delete these methods and recompile. Try not to modify stuff using the type library editor. A fix that seems to work in D2005 and D2006 is to remove the unit implementing an automation object from the project, i.e. edit the project file and delete the "in someunit.pas'" bit after the problematic unit e.g. change "Unit1 in 'Unit1.pas'" to "Unit1".

Aspen Plus 2004.1 and 2006 do not correctly process requests to Get/Set compound molar flows. If Aspen is detected as the PME, a call to Get/SetMolarFlows is changed to a Get/SetOverallComposition and getting/setting the total molar flow via the OverallMolarFlow property.