¡Descarga USER ADDED MODULES GUIDE CHEMCAD y más Apuntes en PDF de Ingeniería Química solo en Docsity!
USER ADDED MODULES GUIDE
WHAT IS A USER ADDED MODULE
This user’s guide describes the procedures used to create User Added Modules in CHEMCAD version 5.4.5 and later. A user added module (UAM) is a user unit operation, K-value method, or enthalpy method created by the user or a third party. UAM’s are programmed in Visual C++ and have access to a large number of internal CHEMCAD routines. For example, UAM’s have been created to model membrane separators, fuel cells and other proprietary technology. UAM’s also give users the ability to create new thermodynamic routines, or communicate data with other programs.
UAM’s are functions compiled into the USRADD.DLL dynamic link library. A Microsoft Visual C++ 6. project for compiling this DLL is provided for you to customize with your own functions. We recommend using Microsoft Visual C++ version 6.0 with service pack 3 for coding your module. If you have user added unitops, a series of files defining the unitops dialog, array and reports must also be created.
USRADD.DLL-The dynamic link library, which contains your user added function
ADD{n}.MY-The dialog file for your user added unitop
ADD{n}.MAP-The definition file for the uspec (unitop) array
ADD{n}.LAB-The report definition file
In order to program UAM’s you must first be proficient in C++ programming language. UAM’s use many different features of C++ such as operator and function overloading. If you are not familiar with these concepts, I suggest you review C++.
C++ makes the UAM package very powerful, but somewhat challenging if you are new to programming. If you are new to programming, I suggest you do not use UAM to model your system, instead use our Excel unit operations. The Excel unit operations require only a basic knowledge of Visual Basic and fundamental concepts like arrays and functions.
This user’s guide was written for the UAM developer with both CHEMCAD and Visual C++ experience. If you are a C++ developer new to CHEMCAD, I strongly suggest you review CHEMCAD until you become proficient in simulation before attempting to create a user added module.
This user’s guide works together with the Screen Builder user’s guide, which describes how to design and create dialog boxes for the user. Screen Builder documentation is required only for user-added unit operations, not K-value or enthalpy methods.
WHAT IS REQUIRED
Before we get started, let’s talk about the UAM requirements. Programming a UAM requires:
A Pentium or faster PC with at least 32 megabytes of ram and at least 50 Megabytes of available hard drive space in addition to the following programs installed:
Microsoft Visual C++ version 6.0 service pack 3 or later
User Added Modules CHEMCAD Version 5.
CHEMCAD version 5.4.5 or higher
CHEMCAD UAM version 5.4.5 or higher
Of course, a faster machine with more memory will yield faster, more reliable results. It is also important that you use the same version UAM as you do CHEMCAD itself. There is a different UAM package for each version of CHEMCAD.
INSTALLATION
To install the UAM development environment, select “Install accessories” from the CD menu, then select “User Added Modules” from the next menu. You may install the UAM anywhere, but I recommend using the default directory. If you use another directory, some project settings may not work properly. For information regarding how to install CHEMCAD or Microsoft Visual C++ version 5, please see their user’s guide.
CHEMCAD SIMULATION STRUCTURE
Before you create a user-added module, you must first understand the structure of simulations in CHEMCAD. This section will familiarize you with how simulations are represented in CHEMCAD. This information is applicable to all simulations in CHEMCAD.
Simulation flowsheets are composed of two distinct objects, Streams and Unitops. Unitops are mathematical representations of process equipment. Streams connect Unitops to each other. Streams are flows of material at a given temperature and pressure. This network of Unitops connected by streams is called a flowsheet.
Unitops depend upon only two things regarding streams: what streams are connected and in what order. For example, a FLAS (Flash unitop) takes all the inlet streams, mixes them, brings them to equilibrium, then sends the vapor phase out the first outlet, and the liquid out the second.
Flowsheet may therefore be simplified into a topology. A topology is a listing of unitops, showing stream connections. The topology defines which streams connect which units. For example, this flowsheet:
User Added Modules CHEMCAD Version 5.
ADD1 ()-AD10 ()
All unitops (ADD1-AD10, as well as standard unitops) are accessed in the same general manner. CHEMCAD is a sequential simulator, it runs one unitop at a time, iterating around recycle loops for convergence. When the run sequence gets to a user unitop, such as ADD1, CHEMCAD runs the ADD1() function in USRADD.dll and then continues to the next unitop.
All unitops, including UAM’s (e.g. ADD1 (), your function) must do the following:
- Read inlet stream data via SINP
- Read unitop parameters (if any). This data is passed into your function in the USPEC array
- Calculate the outlet streams. This is where your calculations come into effect.
- Put the data in the outlet streams via SOUT
User added unitops require extra files (.MY, .MAP files) to define the user dialog box.
An example unitop is given in the tutorial.
CHEMCAD Version 5.1 User Added Modules
ADDK(FLOAT *Y, FLOAT *X, DOUBLE T, DOUBLE P, FLOAT *XKV)
If you wish to calculate your own K-values, you must define an ADDK function with the above format. Notice that x,y and xkv arrays are passed by reference. Your addk function must adjust them.
A simple example of this is the following function, which calculates K-values based upon ideal vapor pressure (vt(i,t) returns the vapor pressure of the ith component at a temperature of t(degrees Rankine)).
#include "stdafx.h"
#include "callccx.h"
EXTERN short nc,idcom[];
EXTERN CP_RECORD *cmp[];
void addk(float *y, float *x, double t, double p, float *xkv)
// Sample ADDK using ideal vapor pressure for K values
int i;
for( i = 0; i < nc; i++)
xkv[i] = vp(i,t) / p;
return;
CHEMCAD Version 5.1 User Added Modules
ADDPIPE1-10((DOUBLE WG, DOUBLE WL, DOUBLE RHOG, DOUBLE RHOL, DOUBLE VISG,
DOUBLE VISL, DOUBLE SURF, DOUBLE D, DOUBLE RF, DOUBLE XL, DOUBLE Z,DOUBLE P,
FLOAT *DP100F, FLOAT *DP100Z, FLOAT *DP100A, SHORT *IREGX))
The addpipe function allows you to enter a user added pipe pressure drop function into CHEMCAD’s Pipe unitop. CHEMCAD will pass to your Addpipe1-10 function the following data in the specified units:
input:
wg gas flow, lb.hr
wl liquid flow , lb/hr
rhog gas density, lb/ft
rhol liquid density, lb/ft
visg gas viscosity, cp
visl liquid viscosity, cp
surf liquid surface tension dyne/cm
d pipe ID, inches
rf pipe roughness, ft
xl pipe length ft
z elevation ft
p inlet pressure pisa
The program expects your function to return to it the following data in the specified units (note data is passed by reference)
output:
dp100f total pressure drop of two-phase friction psi/100ft
dp100z total pressure drop of two-phase elevation psi/100ft
dp100a total pressure drop of two-phase accelaration psi/100ft
iregx flow region calculated by program
We give as an example the Beggs and Brill Calculation model in AddPIpe1, see next few pages for details.
User Added Modules CHEMCAD Version 5.
void addpipe1(double wg, double wl, double rhog, double rhol, double visg,
double visl, double surf, double d, double rf, double xl,
double z,
double p,
float *dp100f, float *dp100z, float *dp100a, short *iregx)
This is an example which uses Beggs and Brill method for pipe pressure drop
calculation
input:
wg gas flow, lb.hr
wl liquid flow , lb/hr
rhog gas density, lb/ft
rhol liquid density, lb/ft
visg gas viscosity, cp
visl liquid viscosity, cp
surf liquid surface tension dyne/cm
d pipe ID, inches
rf pipe roughness, ft
xl pipe length ft
z elevation ft
p inlet pressure pisa
output:
dp100f total pressure drop of two-phase friction psi/100ft
dp100z total pressure drop of two-phase elevation psi/100ft
dp100a total pressure drop of two-phase accelaration psi/100ft
iregx flow region calculated by program
Reference: Two-Phase Flow in Pipes, Janmes P. Brill and H. Dale Beggs. Sixth
edition, Fourth Printing. April, 1994
double A, dft, Vsg, Vsl, Vm, Nfr, lamda_L, Nlv;
double L1, L2, L3, L4;
WORD regime = 0;
double HL0, HL0_S, HL0_I, A_trans, B_trans, C, C_S, C_I, Rad;
double sin_fac, HL_S, HL_I, si, si_S, si_I, HL, rhos, dpdZ_el, rhon;
double visn, N_Ren, fn, y, lny, S, es, ftp, dpdZ_f;
double Ek, dpdZ, dpdZ_a;
User Added Modules CHEMCAD Version 5.
else
// Else, all other area is treated as distributed regime
regime = DISTRIBUTED;
// HL0 holdup which would exist at the same condition in a horizontal pipe, pp3-
if( regime == SEGREGATED )
HL0 = 0.98 * pow(lamda_L,0.4846) / pow(Nfr,0.0868);
else if( regime == INTERMITTENT )
HL0 = 0.845 * pow(lamda_L,0.5351) / pow(Nfr,0.0173);
else if( regime == DISTRIBUTED )
HL0 = 1.065 * pow(lamda_L,0.5824) / pow(Nfr,0.0609);
else
// Transition
HL0_S = 0.98 * pow(lamda_L,0.4846) / pow(Nfr,0.0868);
HL0_I = 0.845 * pow(lamda_L,0.5351) / pow(Nfr,0.0173);
// dspmsg("HL0_S = %g HL0_I = %g\n",HL0_S, HL0_I);
A_trans = (L3 - Nfr) / (L3 - L2);
B_trans = 1. - A_trans;
HL0 = A_trans * HL0_S + B_trans * HL0_I;
// Constraint is HL0 > lamda_L
if( HL0 < lamda_L ) HL0 = lamda_L;
// Calc C, pp 3-
if( z < 0. )
// Downhill
C = (1. - lamda_L ) * log( 4.70 * pow(lamda_L,-0.3692)
CHEMCAD Version 5.1 User Added Modules
* pow(Nlv,0.1244)
* pow(Nfr,-0.5056));
C_S = C;
C_I = C;
else
// Uphill
if( regime == SEGREGATED )
C = (1. - lamda_L ) * log( 0.011 * pow(lamda_L,-3.768)
* pow(Nlv,3.539)
* pow(Nfr,-1.614));
else if( regime == INTERMITTENT )
C = (1. - lamda_L ) * log( 2.96 * pow(lamda_L,0.305)
* pow(Nlv,-0.4473)
* pow(Nfr,0.0978));
else if( regime == DISTRIBUTED )
C = 0.;
else
// Transition
C_S = (1. - lamda_L ) * log( 0.011 * pow(lamda_L,-3.768)
* pow(Nlv,3.539)
* pow(Nfr,-1.614));
C_I = (1. - lamda_L ) * log( 2.96 * pow(lamda_L,0.305)
* pow(Nlv,-0.4473)
* pow(Nfr,0.0978));
// Calc flow angle in radians
if ( z > xl ) z = xl;
Rad = asin(z/xl);
// eqn 3.
sin_fac = sin(1.8 * Rad) - 0.333 * pow(sin(1.8 * Rad),3.);
CHEMCAD Version 5.1 User Added Modules
fn = 1. / pow( 2. * log10( Xre / (4.5223 * log10( Xre) - 3.8215)),2.);
y = lamda_L / pow(HL,2.);
if( 1 < y && y < 1.2 )
S = log(2.2 * y - 1.2);
else
lny = log(y);
S = lny /
( -0.0523 + 3.182 * lny - 0.8725 * pow(lny,2.) + 0.01853 * pow(lny,4.));
es = exp(S);
ftp = fn * es;
// dpdZ_f in psf/ft
dpdZ_f = ftp * rhon * Vm * Vm / (2. * 32.2 * dft);
// eqn 3.93 p * 144 to lbf/ft
Ek = rhos * Vm * Vsg / (32.2 * p * 144.);
if( Ek > 0.8 )
Ek = 0.8;
dpdZ = (dpdZ_el * sin(Rad) + dpdZ_f) / (1. - Ek);
dpdZ_a = dpdZ * Ek;
*dp100f = dpdZ_f / 144. * 100.;
*dp100a = dpdZ_a / 144. * 100.;
*iregx = regime;
return;
User Added Modules CHEMCAD Version 5.
OVERVIEW OF PROJECT
The project to compile the USRADD.DLL file is included in the CC5UAM package. This project is a Microsoft Visual C++ version 5 project. It contains all the settings, header files, libraries and debug versions of our DLLs needed for you to compile your USRADD.DLL and test it in debug.
File listing of CC5UAM project:
CC5D (folder)-Debug versions of EXE and dlls available for troubleshooting your module in DEBUG
Debug (folder)-Used for Debug info on your dll
Release (folder)-Where the release version of your dll resides
Res-Resources folder
ADD1-AD10.CPP-Templates for your code
ADDH, ADDK.CPP-User added K values templates
ADDPIPE.CPP- User-added Pipe model template (Beggs and Brill)
CALLCCX.H-Header file describing various CHEMCAD functions
CC5.H-Header file describing various CHEMCAD functions
Microsoft generated files:
STDAFX.H, CPP
Resource.h
USRADD.*
User code goes in the provided templates for ADD1.cpp-AD10.cpp, ADDK.cpp, ADDH.cpp, and ADDPIPE.cpp. These files are yours to modify, but I recommend making copies of these files for your reference before you do so. We have structured this project so that code for each UAM function goes into a separate source file.
After completing your code, you will have to compile your USRADD.dll and move the compiled dll into your CC5 program directory, along with any additional files such as .MY, .MAP, or .LAB files for your unitops. The screen builder documentation describes these files and how to create them.
UNIT OPERATIONS: GETTING/SETTING STREAM AND UNIT DATA
All unitops, including UAM’s (e.g. ADD1 (), your function) must do the following:
- Read inlet stream data via SINP
- Read unitop parameters (if any). This data is passed into your function in the USPEC array
- Calculate the outlet streams. This is where your calculations come into effect.
User Added Modules CHEMCAD Version 5.
In order to use debug mode, special “debug” versions of your program must be created. Setting the active configuration, in the “build” menu to “USRADD Win32-debug” does this. Your debug version of the dll should always be used with the ccd.exe and debug versions of our dlls provided in the cc5d directory. The project is already set for this. While we provide debug versions of dlls, we do not provide enough information for you to debug into our program, so all code outside of that in usradd.dll will be inaccessible. Do not try to use a debug version usradd.dll with a release version of cc5.exe or vice versa. Trying to do so may result in an error.
The simplest way to use a debug session is to place a breakpoint in your user added function (such as ADD2 ()), run the debug mode, and create a simulation which uses that function. When CHEMCAD comes to your user added function, for example when you run your unit operation (make sure the inlet streams have some flow) Visual studio will detect your breakpoint and stop execution at that point. You can then step through your code, line by line, adding watches on important variables and using the mouse to check current values of variables.
When starting a debug session, you will get a message warning you “…CCd.exe does not contain any debugging information…” This is normal; we don’t give enough information to debug the executable, only your dll. Press [OK] to continue. If you wish, you may disable this notification by checking the checkbox on the dialog with the warning.
On certain systems (mostly Windows 9x operating systems) you will get a series of 4 debug assertion failures as CHEMCAD loads. These assertion failures happen in a Microsoft source file appui3.cpp. These are normal for this version and will cause no noticeable problems in the release version. Simply press the “Ignore” button to get past each message.
The first debug assertion failure
After these messages, CHEMCAD will start and appear just like the release version, albeit slightly slower due to the debug overhead. If you get a debug assertion failure in your code (i.e. other than the first four which normally show) you may use the “Retry” button to debug it.
CHEMCAD Version 5.1 User Added Modules
APPENDIX: CHEMCAD LIBRARY OF FUNCTIONS
In order for your UAM to be successful, you will need access to physical properties and DATA from
within CHEMCAD. This access is granted through a library of functions. This library consists
of several parts:
- General Functions-Access to streams and equipment, printing functions
- Engineering Units-Unit conversion, units reporting information
- Physical Property Calculation-Calculation of stream properties
- Thermodynamic Calculations-Calculation of K-values, Enthalpy, and Entropy of streams
GENERAL FUNCTIONS
Message display
The following functions use the flowsheet window as a scrollable text area. The first call to Put_Scr_Line automatically opens this area. If you wish, you can clear the scrollable text area between calls to Put_Scr_Line with a call to Clear_Scr_Wndo. It is your responsibility to call Close_Scr_Wndo when you are finished using the scrollable text area. These functions are useful for displaying messages and calculations while your user-added functions are executing. They are used by several of the standard unit operation models. They are also useful for debugging purposes.
Prototypes:
void Put_Scr_Line(char *scr_line); void Clear_Scr_Wndo(void); void Close_Scr_Wndo(void);
Reporting Functions
The following functions can be used to generate reports from your user-added modules. Typically, this is not done unless you are in the process of debugging your code. If you use these functions, the output is sent to the current report device, as specified by the Control/Reports menu option. This is the screen, a file, a printer, or a "NUL" device (meaning that no output is physically produced). It is your responsibility to call the Close_Report function when you are finished producing your report.
Starting a Report
You specify the name of a function, which is to be used to print page headings at the start of each page, and, if necessary, the address of a parameter block of values required by this page headings function.
typedef void (*HEADER_FN)(void *parm_block);
void Open_Report(HEADER_FN header_fn, void *hdr_parm_block);
The following code illustrates how the Open_Report function and a page headings function are specified.
/* this is the parameter block used to pass parameters to the / / function which prints the header lines at the top of each / / page of the report */ typedef struct {
CHEMCAD Version 5.1 User Added Modules
This function dumps a form-feed to the report.
void Put_Rpt_Line(char *rpt_line); Put_Rpt_Line("Example of a report line");
This function dumps a line to the report and appends this line with a carriage-return / line-feed.
void Put_Rpt_String(char *rpt_line); Put_Rpt_String("Waiting for the rest of the string ....");
This function dumps a string to the report but does NOT append a carriage-return / line-feed to the end of the line.
void Put_Rpt_PageNo(void); Put_Rpt_PageNo();
This function right-justifies the current page number on the page.
Determining the Current Report Status
int Get_Rpt_Dest(void); switch (Get_Rpt_Dest()) { case 'S': /* report is going to the screen / break; case 'P': / report is going to the printer / break; case 'F': / report is going to a file / break; case 'L': / report is going to a Lotus file / break; case 'N': / report is going nowhere (NUL output device) */ break; }
This function returns the current report destination, as specified in the Control/Reports menu option.
void Set_Rpt_Dest(int dest); Set_Rpt_Dest('S'); // send report output to the screen Set_Rpt_Dest('P'); // send report output to the printer Set_Rpt_Dest('F'); // send report output to a file Set_Rpt_Dest('N'); // discard report output
This function sets the report destination, temporarily overriding the destination specified in the Control/Reports menu option.
int Get_Rpt_Handle(void); if (Get_Rpt_Handle()) // do some output
User Added Modules CHEMCAD Version 5.
This function indicates whether or not the report output device is ready for output, i.e. whether or not you have already called Open_Report and have not yet called Close_Report.
int Get_Top_Margin(void); top_rows = Get_Top_Margin();
This function returns the top margin as a number of rows.
int Get_Bottom_Margin(void); bottom_rows = Get_Bottom_Margin();
This function returns the bottom margin as a number of rows.
int Get_Rpt_Rows(void); page_rows = Get_Rpt_Rows();
This function returns the number of rows per page. This value includes the top margin and bottom margin. The number of useable rows per page can be calculated as follows:
use_rows = Get_Rpt_Rows() - Get_Top_Margin() - Get_Bottom_Margin();
int Get_Rpt_Cols(void); char_cols = Get_Rpt_Cols();
This function returns the page width (in characters).
int Get_Rpt_LineNo(void); cur_line = Get_Rpt_LineNo();
This function returns the current line number (on the current page).
int Get_Rpt_PageNo(void); cur_page = Get_Rpt_PageNo();
This function returns the current report page number.
Function: Browse_File
Browse an ASCII file in read-only mode
Prototypes:
CALL Browse_File('TEST.CL'//nullchar, ' COMPONENT LIST '//nullchar) int Browse_File(char *file_path, char *window_title);
Parameters: Input: DOS Filespec, Browse Window Title (or NULL) Return Value: 0 = file browsed OK, non-zero = file not found Description: This function allows you to browse any file from within the CHEMCAD graphics interface.
Function: Check_Stream_Rec Check the validity of a stream (.STR) file record Prototypes:
ierr = Check_Stream_Rec(ID)
