api11.c - Instructions for use

Revision: Mar 12, 2006

URL: http://www.felib.com

E-mail: info@felib.com

api11.c is the C source code implementation of the calculation of temperature and pressure volume correction factors for crude oils, refined products and lubricating oils in accordance with Manual of Petroleum Measurement Standards, Published by American Petroleum Institute, May 2004.

References:

1. Manual of Petroleum Measurement Standards,

Chapter 11: Physical Properties Data,

Section 1: Temperature and Pressure Volume Correction Factors for Generalized Crude Oils, Refined Products, and Lubricating Oils.

The software is written in a C-language.

1. Function declaration

The following is the definition of the function and the structure in the header file ‘api11.h’:

/* declaration of the function api11 */

void api11(

/* input/output parameters */

struct api *); /* input-output parameters */

/* IN CASE OF SINGLE FLOATING POINT NUMBER PRECISION */

/* #define fpnp float */

/* IN CASE OF Double FLOATING POINT NUMBER PRECISION */

/* #define fpnp double */

#define fpnp float

/* declaration of the structure */

struct api

{

/* INPUT PARAMETERS */

unsigned short Alternate; /* Alternate condition switch */

/* Alternate = 0 – Alternate conditions switched OFF */

/* Alternate = 1 – Alternate conditions switched ON */

unsigned short Rounding; /* Rounding switch */

/* Rounding = 0 – Calculate both un-rounded and rounded values and store separately */

/* Rounding = 1 – Calculate rounded values only and store in both locations */

/* Rounding = 2 – Calculate un-rounded values only and store in both locations */

unsigned short Commodity; /* Commodity */

/* Commodity = 0 – Specialized Liquid */

/* Commodity = 1 – Crude Oil */

/* Commodity = 2 – Lubricating Oil */

/* Commodity = 3 – Refined Product */

unsigned short Alpha60_unit; /* Units for thermal expansion coefficient at 60°F if Commodity=0, else ignore */

/* Alpha60_unit = 0 – Thermal coefficient given in °F-1 */

/* Alpha60_unit = 1 – Thermal coefficient given in °C-1 */

fpnp Alpha60; /* If Commodity=0, then set Alpha60 in units defined by ‘Alpha60_unit’, else ignore */

unsigned short Temperature_unit; /* Definition of temperature units */

/* Temperature_unit = 0 – All temperatures in °F */

/* Temperature_unit = 1 – All temperatures in °C */

/* Temperature_unit = 2 – All temperatures in K */

/* Temperature_unit = 3 – All temperatures in °R */

fpnp To; /* Observed temperature in units defined by ‘Temperature_unit’ */

fpnp Ta; /* Alternate temperature in units defined by ‘Temperature_unit’ */

fpnp Tb; /* Base temperature in units defined by ‘Temperature_unit’ */

unsigned short Pressure_unit; /* Definition of pressure units */

/* Pressure_unit = 0 – All pressures in psig */

/* Pressure_unit = 1 – All pressures in kPa (gauge) */

/* Pressure_unit = 2 – All pressures in bar (gauge) */

fpnp Po; /* Observed pressure in units defined by ‘Pressure_unit’ */

fpnp Pa; /* Alternate pressure in units defined by ‘Pressure_unit’ */

unsigned short Density_type; /* Definition of density type and the corresponding units */

/* Density_type = 0 – Observed density in kg/m3 at To and Po */

/* Density_type = 1 – Observed relative density at To and Po */

/* Density_type = 2 – Observed API gravity at To and Po */

/* Density_type = 3 – Base density in kg/m3 at Tb */

/* Density_type = 4 – Base relative density at Tb */

/* Density_type = 5 – Base density in °API at Tb */

/* Density_type = 6 – Density in kg/m3 at 60 °F */

/* Density_type = 7 – Relative density at 60 °F */

/* Density_type = 8 – Density in °API at 60 °F */

fpnp Density; /* Base density, observed density or density at 60 °F, depending on ‘Density_type’ */

fpnp Volume_To_Po; /* Volume at To and Po, in any valid units */

/* OUTPUT PARAMETERS */

unsigned long int error_status; /* Error status */

unsigned short int Commodity_out; /* Commodity of the product*/

/* Commodity_out = 0 – Specialized Liquid */

/* Commodity_out = 1 – Crude Oil */

/* Commodity_out = 2 – Lubricating Oil */

/* Commodity_out = 3 – Refined Product */

/* Commodity_out = 4 – Fuel Oil */

/* Commodity_out = 5 – Jet Fuel */

/* Commodity_out = 6 – Transition Zone */

/* Commodity_out = 7 – Gasoline */

fpnp Fp_o_psi; /* Scaled compressibility factor for observed temperature To per psi */

fpnp Fp_a_psi; /* Scaled compressibility factor for alternate temperature Ta per psi */

fpnp Fp_o_spu; /* Scaled compressibility factor for observed temperature To per selected ‘Pressure_unit’ */

fpnp Fp_a_spu; /* Scaled compressibility factor for alternate temperature Ta per selected ‘Pressure_unit’ */

fpnp Ctl_60_b; /* Correction factor to correct density & volume at 60 °F to base temperature Tb */

fpnp Ctpl_60_o; /* Combined correction factor to correct density & volume at 60 °F to observed Po, To */

fpnp Ctpl_60_o_r; /* Combined rounded correction factor to correct density & volume at 60 °F to observed Po, To */

fpnp Ctpl_60_a; /* Combined correction factor to correct density & volume at 60 °F to alternate Pa, Ta */

fpnp Ctpl_60_a_r; /* Combined rounded correction factor to correct density & volume at 60 °F to alternate Pa, Ta */

fpnp Ctpl_Tb_o; /* Combined correction factor to correct density & volume at Tb to observed Po, To */

fpnp Ctpl_Tb_o_r; /* Combined rounded correction factor to correct density & volume at Tb to observed Po, To */

fpnp Ctpl_Tb_a; /* Combined correction factor to correct density & volume at Tb to alternate Pa, Ta */

fpnp Ctpl_Tb_a_r; /* Combined rounded correction factor to correct density & volume at Tb to alternate Pa, Ta */

fpnp Density_60_kg_cum; /* Density in kg/cu m at 60 °F */

fpnp Density_60_API; /* Density in °API at 60 °F */

fpnp Density_60_rel; /* Relative density at 60 °F */

fpnp Density_Tb_kg_cum; /* Density in kg/cu m at base temperature Tb */

fpnp Density_Tb_API; /* Density in °API at base temperature Tb */

fpnp Density_Tb_rel; /* Relative density at base temperature Tb */

fpnp Density_To_Po_kg_cum; /* Un-rounded density in kg/cu m at observed conditions To and Po */

fpnp Density_To_Po_kg_cum_r; /* Rounded density in kg/cu m at observed conditions To and Po */

fpnp Density_To_Po_API; /* Un-rounded density in °API at observed conditions To and Po */

fpnp Density_To_Po_API_r; /* Rounded density in °API at observed conditions To and Po */

fpnp Density_To_Po_rel; /* Un-rounded relative density at observed conditions To and Po */

fpnp Density_To_Po_rel_r; /* Rounded relative density at observed conditions To and Po */

fpnp Density_Ta_Pa_kg_cum; /* Un-rounded density in kg/cu m at alternate conditions Ta and Pa */

fpnp Density_Ta_Pa_kg_cum_r; /* Rounded density in kg/cu m at alternate conditions Ta and Pa */

fpnp Density_Ta_Pa_API; /* Un-rounded density in °API at alternate conditions Ta and Pa */

fpnp Density_Ta_Pa_API_r; /* Rounded density in °API at alternate conditions Ta and Pa */

fpnp Density_Ta_Pa_rel; /* Un-rounded relative density at alternate conditions Ta and Pa */

fpnp Density_Ta_Pa_rel_r; /* Rounded relative density at alternate conditions Ta and Pa */

fpnp Volume_60; /* Volume at 60 °F in the same units as ‘Volume_To_Po’ */

fpnp Volume_60_r; /* Rounded volume at 60 °F in the same units as ‘Volume_To_Po’ */

fpnp Volume_Tb; /* Volume at base temperature Tb in the same units as ‘Volume_To_Po’ */

fpnp Volume_Tb_r; /* Rounded volume at base temperature Tb in the same units as ‘Volume_To_Po’ */

fpnp Volume_Ta_Pa_60; /* Un-rounded volume at (Ta, Pa) obtained from ‘Volume_60’ */

fpnp Volume_Ta_Pa_60_r; /* Rounded volume at (Ta, Pa) obtained from Volume_60_r in units as ‘Volume_To_Po’ */

fpnp Volume_Ta_Pa_Tb; /* Un-rounded volume at (Ta, Pa) obtained from Volume_Tb in units as ‘Volume_To_Po’ */

fpnp Volume_Ta_Pa_Tb_r; /* Rounded volume at (Ta, Pa) obtained from Volume_Tb_r in units as ‘Volume_To_Po’

};

2. Input and output parameters

The following Table shows the description of input and output parameters.

Table 2.1

Input parameters
Data type	Parameter name	Parameter description	Unit of measure
unsigned short int	Alternate	Alternate condition switch	dimensionless
unsigned short int	Rounding	Rounding switch	dimensionless
unsigned short int	Commodity	Commodity	dimensionless
unsigned short int	Alpha60_unit	Units for thermal expansion factor	dimensionless
double	Alpha60	Thermal expansion factor at 60 °F	Alpha60_unit
unsigned short int	Temperature_unit	Selection of temperature unit	dimensionless
double	To	Observed temperature	Temperature_unit
double	Ta	Alternate temperature	Temperature_unit
double	Tb	Base temperature	Temperature_unit
unsigned short int	Pressure_unit	Selection of pressure unit	dimensionless
double	Po	Observed pressure	Pressure_unit
double	Pa	Alternate pressure	Pressure_unit
unsigned short int	Density_type	Selection of density type and unit	dimensionless
double	Density	Density selected by Density_type	Density_type
double	Volume_To_Po	Observed volume	Any unit
Output parameters
unsigned long int	error_status	Error status	dimensionless
unsigned short int	Commodity_out	Commodity after calculation	dimensionless
double	Fp_o_psi	Scaled compressibility factor for To	Per psi
double	Fp_a_psi	Scaled compressibility factor for Ta	Per psi
double	Fp_o_spu	Scaled compressibility factor for To	Per ‘Pressure_unit'
double	Fp_a_spu	Scaled compressibility factor for Ta	Per ‘Pressure_unit’
double	Ctl_60_b	Correction from 60°F to Tb	dimensionless
double	Ctpl_60_o	Combined correction from 60°F to To,Po	dimensionless
double	Ctpl_60_o_r	Rounded correction from 60°F to To,Po	dimensionless
double	Ctpl_60_a	Combined correction from 60°F to Ta,Pa	dimensionless
double	Ctpl_60_a_r	Rounded correction from 60°F to Ta,Pa	dimensionless
double	Ctpl_Tb_o	Combined correction from Tb to To,Po	dimensionless
double	Ctpl_Tb_o_r	Rounded correction from Tb to To,Po	dimensionless
double	Ctpl_Tb_a	Combined correction from Tb to Ta,Pa	dimensionless
double	Ctpl_Tb_a_r	Rounded correction from Tb to Ta,Pa	dimensionless
double	Density_60_kg_cum	Density at 60 °F	kg/m^3
double	Density_60_API	Density at 60 °F	°API
double	Density_60_rel	Relative density at 60 °F	dimensionless
double	Density_Tb_kg_cum	Density at base temperature Tb	kg/m^3
double	Density_Tb_API	Density at base temperature Tb	°API
double	Density_Tb_rel	Relative density at base temperature Tb	dimensionless
double	Density_To_Po_kg_cum	Observed density at To, Po	kg/m^3
double	Density_To_Po_kg_cum_r	Rounded density at To, Po	kg/m^3
double	Density_To_Po_API	Un-rounded density at To, Po	°API
double	Density_To_Po_API_r	Rounded density at To, Po	°API
double	Density_To_Po_rel	Un-rounded relative density at To, Po	dimensionless
double	Density_To_Po_rel_r	Rounded relative density at To, Po	dimensionless
double	Density_Ta_Pa_kg_cum	Rounded density at Ta, Pa	kg/m^3
double	Density_Ta_Pa_kg_cum_r	Un-rounded density at Ta, Pa	kg/m^3
double	Density_Ta_Pa_API	Rounded density at Ta, Pa	°API
double	Density_Ta_Pa_API_r	Un-rounded density at Ta, Pa	°API
double	Density_Ta_Pa_rel	Un-rounded relative density at Ta, Pa	dimensionless
double	Density_Ta_Pa_rel_r	Rounded relative density at Ta, Pa	dimensionless
double	Volume_60	Volume at 60 °F	Same as Volume_Ta_Pa
double	Volume_60_r	Rounded volume at 60 °F	Same as Volume_Ta_Pa
double	Volume_Tb	Volume at base temperature Tb	Same as Volume_Ta_Pa
double	Volume_Tb_r	Volume at base temperature Tb	Same as Volume_Ta_Pa
double	Volume_Ta_Pa	Volume at alternate conditions Ta, Pa	Same as Volume_Ta_Pa
double	Volume_Ta_Pa_60_r	Rounded volume at Ta, Pa obtained by dividing Volume_60_r by Ctpl_60_a_r	Same as Volume_Ta_Pa
double	Volume_Ta_Pa_Tb_r	Rounded volume at Ta, Pa obtained by dividing Volume_Tb_r by Ctpl_Tb_a_r	Same as Volume_Ta_Pa

3. Parameter ranges

Table 3.1 shows the (Density_60_kg_cmu) input range limits (Rho60min and Rho60max) and the corresponding minimum and maximum densities (Density60_min and Density60_max) and the coefficients K0, K1 and K2 for the various commodity groups.

Table 3.1

The range limits (Rho60min and Rho60max), range limits (Rhomin and Rhomax) and the coefficients K0, K1 and K2 and Da for different commodity groups
Commodity			Rho60min kg/m^3	Rho60max kg/m^3	Rhomin kg/m^3	Rhomax kg/m^3	K0	K1	K2	Da
Index	Type
0	Specialized Liquid		³610.6	<1163.5	³470.4	<1209.5	-	-	-	0.0
1	Crude Oil		³610.6	<1163.5	³470.5	<1201.8	341.0957	0.0	0.0	2.0
2	Lubricating Oil		³800.9	<1163.5	³714.3	<1208.3	0.0	0.34878	0.0	1.0
3	General Refined Product		³610.6	≤1163.5	³470.4	≤1209.5	depends on	depends on	depends on	-
	4	Fuel Oils	³838.3127	≤1163.5	-	-	103.8720	0.2701	0.0	1.3
	5	Jet Fuels	³787.5195	<838.3127	-	-	330.3010	0.0	0.0	2.0
	6	Transition Zone	³770.3520	<787.5195	-	-	1489.0670	0.0	-0.00186840	8.5
	7	Gasolines	³610.6	<770.3520	-	-	192.4571	0.2438	0.0	1.5

Table 3.2 shows the range limits for temperatures (To, Ta and Tb), pressures (Po and Pa) and thermal expansion factor at 60 °F ().

Table 3.2

Valid ranges of application
Parameter	Range of application
Temperatures: To, Ta and Tb	-58 °F ≤ (To, Ta and Tb) ≤ 302 °F
Pressures: Po and Pa	0 psig ≤ (Po or Pa) ≤ 1500 psig
Thermal expansion factor at 60 °F:	230.0·10^-6 °F^-1 ≤ ≤ 930.0·10^-6 °F^-1

4. Calculation procedure

The following Table shows the simplified diagram of the ‘API Chapter 11’ calculation procedure.

Table 4.1

api11 calculation procedure
Step
1	Verify input parameters and set the corresponding error_status flags in case of range limit violations
1.a	Clear ‘error_status’ flags and output parameters. Force negative pressures (Po and Pa) to zero. Set density of water at 60 °F: Rho60_w = 999.016 kg/m^3. Convert temperatures (To, Ta and Tb) into °F, pressures (Po and Pa) into psig and density (Density) into kg/m^3 : To[Temperature_unit] → Tox [°F], Ta[Temperature_unit] → Tax [°F], Tb[Temperature_unit] → Tbx [°F], Po[Pressure_unit] → Pox[psig], Pa[Pressure_unit] → Pax[psig], Density[Density_type] → Densityx[kg/m^3]
1.b	If (-58 °F > (Tox, Tax or Tbx) > 302 °F) or If ( (Pox or Pax) > 1500 psig) Then set the ‘error_status’ flags (Tox: 0x1, Tax: 0x2, Tbx: 0x4, Pox: 0x8, Pax: 0x10) If (Commodity < 0 or Commodity > 3) Then set ‘error_status’ flag (Commodity: 0x11) If error_status != 0 Then Exit
1.c	If (Tox=60°F and Pox=0 psig and if density given at 60 °F) or if (Tox=60°F and Pox=0 psig and if density given at Tbx and if Tbx=60 °F) or if (Tox=60°F and Pox=0 psig and if density given at Tox and if Tox=60 °F), Then Density_60_kg_cum = Densityx[kg/m^3] Else Go To Step 2
1.d	If (Commodity = 0) Then convert Alpha60 into °F^-1 (Alpha60[Alpha60_type] → Alpha60x[°F^-1]) and set error_status flag If (Alpha60min > Alpha60x > Alpha60max): (Alpha60x: 0x12) Else If (Commodity != 0 & Rho60min(Commodity) > Density_60_kg_cum > Rho60max(Commodity) Then set the ‘error_status’ flag (Density_60_kg_cum: 0x14) If error_status != 0 Then Exit
1.e	Shift the base temperature Tbx[°F] observed temperature Tox[°F] and the alternate temperature Tax[°F] to the IPTS-68 basis (Tbx68[°F], Tox68[°F] and Tax68[°F]) TbxC = (Tbx-32.0)/1.8 Tau=Tbx/630.0 Tbx68=1.8*(TbxC-(a1+(a2+(a3+(a4+(a5+(a6+(a7+a8*Tau)*Tau)*Tau)*Tau)*Tau)*Tau)*Tau)*Tau)+32.0 ToxC = (Tox-32.0)/1.8 Tau=Tox/630.0 Tox68=1.8*(ToxC-(a1+(a2+(a3+(a4+(a5+(a6+(a7+a8*Tau)*Tau)*Tau)*Tau)*Tau)*Tau)*Tau)*Tau)+32.0 TaxC = (Tax-32.0)/1.8 Tau=Tax/630.0 Tax68=1.8*(TaxC-(a1+(a2+(a3+(a4+(a5+(a6+(a7+a8*Tau)*Tau)*Tau)*Tau)*Tau)*Tau)*Tau)*Tau)+32.0 where a1=-0.148759, a2=-0.267408, a3=1.080760, a4=1.269056, a5=-4.089591, a6=-1.871251, a7=7.438081 and a8=-3.536296.
1.f	If(Commodity != 0 and Rho60min[Commodity] > Density_60_kg_cum and Density_60_kg_cum > Rho60max[Commodity]) Then {error_status = error_status | 0x14;} Shift the Density_60_kg_cum value to the IPTS-68 basis Density68 If (Commodity=0) Then d60=0.01374979547 Density68=Density_60_kg_cmu*exp(0.5*Alpha60x*d60*(1.0+0.4*Alpha60x*d60)) Else Select the corresponding coefficients K0, K1 and K2 If (Commodity<3) Then Index=Commodity Else If (Commodity=3) Then If (Density_60_kg_cum <= Rho60max[4] & Density_60_kg_cum >= Rho60min[4]) Then Index=4 Else If (Density_60_kg_cum <= Rho60max[5] & Density_60_kg_cum >= Rho60min[5]) Then set Index=5 Else If (Density_60_kg_cum <= Rho60max[6] & Density_60_kg_cum >= Rho60min[6]) Then set Index=6 Else Index=7 K0x=K0[Index], K1x=K1[Index], K2x=K2[Index] Ax=0.5*d60*((K0x/Density_60_kg_cmu+K1x)/Density_60_kg_cmu+K2x) Bx=(2.0*K0x+K1x* Density_60_kg_cmu)/(K0x+(K1x+K2x*Density_60_kg_cmu)*Density_60_kg_cmu) Density68=Density_60_kg_cmu*(1.0+(exp(Ax*(1.0+0.8*Ax))-1.0)/(1.0+Ax*(1.0+1.6*Ax)*Bx)) Alpha60x=(K1x+K0x/Density68)/Density68+K2x
1.g	T68=60.0068749; If (Tbx >= 59.9999 & Tbx <= 60.0001) Then Ctl_60_b = 1.0 Else dT=Tbx68-T68; Ctl_60_b=exp(-Alpha60x*dT*(1.0+0.8*Alpha60x*( dT+d60))); If (Tox >= 59.9999 & Tox <= 60.0001) Then Ctl_60_o = 1.0 Else dT=Tox68-T68; and Ctl_60_o=exp(-Alpha60x*dT*(1.0+0.8*Alpha60x*( dT+d60))); If (Pox < 0.0001) then Fp_o=1.0; and Cpl_60_o=1.0; Else Fp_o=exp(-1.9947+0.00013427*Tox68+(793920+2326.0*Tox68)/(Density68*Density68)); Cpl_60_o=1.0/(1.0-0.00001*Fp_o*Pox); Ctpl_60_o=Ctl_60_o*Cpl_60_o; Ctpl_60_o_r = (fpnp)((int)(100000.0 * Ctpl_60_o+0.5))/100000.0; /* rounded correction factor */ If (Tax >= 59.9999 & Tax <= 60.0001) Then Ctl_60_a = 1.0 Else dT=Tax68-T68; and Ctl_60_a=exp(-Alpha60x*dT*(1.0+0.8*Alpha60x*( dT+d60))); If (Pax < 0.0001) then Fp_a=1.0; and Cpl_60_a=1.0; Else Fp_a=exp(-1.9947+0.00013427*Tax68+(793920+2326.0*Tax68)/(Density68*Density68)); Cpl_60_a=1.0/(1.0-0.00001*Fp_a*Pax); Ctpl_60_a=Ctl_60_a*Cpl_60_a;
1.h	Density_60_API=141.5 * Rho60_w / Density_60_kg_cum – 131.5; Density_60_rel= Density_60_kg_cum / Rho60_w; Density_Tb_kg_cum = Ctl_60_b * Density_60_kg_cum; Density_Tb_API=141.5 * Rho60_w / Density_Tb_kg_cum – 131.5; Density_Tb_rel= Density_Tb_kg_cum / Rho60_w; Density_To_Po_kg_cum = Ctpl_60_o * Density_60_kg_cum; Density_To_Po_API=141.5 * Rho60_w / Density_To_Po_kg_cum – 131.5; Density_To_Po_rel= Density_To_Po_kg_cum / Rho60_w; Density_Ta_Pa_kg_cum = Ctpl_60_a * Density_60_kg_cum; Density_Ta_Pa_API=141.5 * Rho60_w / Density_Ta_Pa_kg_cum – 131.5; Density_Ta_Pa_rel= Density_Ta_Pa_kg_cum / Rho60_w; Volume_60 = Volume_To_Po * Ctpl_60_o; Volume_Tb = Volume_60 / Ctl_60_b; Volume_Ta_Pa = Volume_60 / Ctpl_60_a;
2	Calculate density at 60 °F
2.a	If Commodity = 0 (specialized liquid) Then convert Alpha60 into °F^-1: Alpha60[Alpha_60_type] → Alpha60x[°F^-1] and test if Alpha60x within the range 230.0 10-6 °F^-1 ≤ Alpha60x ≤ 930.0 10-6 °F^-1 and set error_status flag 0x12 if not so
2.b	If (0 < Commodity < 7) Then determine K0x, K1x, K2x (K0x=K0[Commodity], K1x=K1[Commodity], K2x=K2[Commodity]) and compute Alpha60x in °F^-1

4. Error status

After completion of the routine the error_status (unsigned long integer) will be cleared if there were no errors during the calculation, or the corresponding bits will be set if certain errors were encountered. The description of the error_status bits is given in Table 4.1.

Table 4.1

Bit number	Hexadecimal address	Description
Bit 0	=1 (000001H)	If observed temperature To out of range, else =0
Bit 1	=1 (000002H)	If alternate temperature To out of range, else =0
Bit 2	=1 (000004H)	If base temperature out of range, else =0
Bit 3	=1 (000008H)	If observed pressure out of range, else =0.
Bit 4	=1 (000010H)	If observed pressure out of range, else =0.
Bit 5	=1 (000020H)	If commodity index out of range, else =0.
Bit 6	=1 (000040H)	If thermal expansion coefficient out of range, else =0.
Bit 7	=1 (000080H)	If density at 60°F out of range, else =0.
Bit 8	=1 (000100H)	If density out of maximum range, else =0.
Bit 9	=1 (000200H)	If the result did not converge but is valid (Refined Products), else =0.
Bit 10	=1 (000400H)	If the result did not converge and is invalid, else =0.
Bit 11,...	=x (000010H)	All higer bits are unused

The error_status is returned as unsigned long integer representing all the errors encountered in the calculation. If bits 0,...,10 are all cleared, or if only bit 9 (200H) was set during the calculation, the returned output results are valid, otherwise the results are invalid.

5. Example of a main program calling the function api11

/* **************************************** */

/* THE BEGINNING OF THE MAIN PROGRAM C-CODE */

/* **************************************** */

#include "api11.h"

void main(void)

{

struct api api0, *papi0; /* 'papi' - pointer to a structure 'api0' */

unsigned short int j, ii;

char ch;

char *text[56] = {

"Alternate (0-1) ", "Rounding (0-2) ", "Commodity (0-3) ",

"Alpha60_unit (0-1) ", "Alpha60 ", "Temperature_unit (0-3) ",

"To ", "Ta ", "Tb ",

"Pressure_unit (0-2) ", "Po ", "Pa ",

"Density_type (0-8) ", "Density ", "Volume_To_Po ",

"error_status ", "Commodity_out ", "Fp_o_psi ",

"Fp_a_psi ", "Fp_o_spu ", "Fp_a_spu ",

"Ctl_60_b ", "Ctpl_60_o ", "Ctpl_60_o_r ",

"Ctpl_60_a ", "Ctpl_60_a_r ", "Ctpl_Tb_o ",

"Ctpl_Tb_o_r ", "Ctpl_Tb_a ", "Ctpl_Tb_a_r ",

"Density_60_kg_cum ", "Density_60_API ", "Density_60_rel ",

"Density_Tb_kg_cum ", "Density_Tb_API ", "Density_Tb_rel ",

"Density_To_Po_kg_cum ", "Density_To_Po_kg_cum_r ", "Density_To_Po_API ",

"Density_To_Po_API_r ", "Density_To_Po_rel ", "Density_To_Po_rel_r ",

"Density_Ta_Pa_kg_cum ", "Density_Ta_Pa_kg_cum_r ", "Density_Ta_Pa_API ",

"Density_Ta_Pa_API_r ", "Density_Ta_Pa_rel ", "Density_Ta_Pa_rel_r ",

"Volume_60 ", "Volume_60_r ", "Volume_Tb ",

"Volume_Tb_r ", "Volume_Ta_Pa_60 ", "Volume_Ta_Pa_60_r ",

"Volume_Ta_Pa_Tb ", "Volume_Ta_Pa_Tb_r "

};

short nn[90][7] = {

/* API Chapter 11 examples */

/* Commodity, Alpha60_unit, Temperature_unit, Pressure_unit, Density_type */

/* 11.1.6.1 (Examples 1-15) */

0, 1, 1, 0, 0, 0, 8,

0, 1, 1, 0, 0, 0, 8,

0, 1, 3, 0, 0, 0, 8,

0, 1, 3, 0, 0, 0, 7,

0, 1, 3, 0, 0, 0, 8,

0, 1, 3, 0, 0, 0, 6,

0, 1, 0, 0, 0, 0, 7,

0, 1, 2, 0, 0, 0, 8,

0, 1, 1, 0, 0, 0, 8,

0, 1, 1, 0, 0, 0, 8,

0, 1, 1, 0, 0, 0, 8,

0, 1, 1, 0, 0, 0, 8,

0, 1, 3, 0, 0, 0, 8,

0, 1, 2, 0, 0, 0, 8,

0, 1, 1, 0, 0, 0, 8,

/* 11.1.6.2 (Examples 16-31) */

0, 1, 1, 0, 0, 0, 0,

0, 1, 1, 0, 0, 0, 1,

0, 1, 3, 0, 0, 0, 1,

0, 1, 3, 0, 0, 0, 2,

0, 1, 3, 0, 0, 0, 0,

0, 1, 3, 0, 0, 0, 1,

0, 1, 0, 0, 0, 0, 0,

0, 1, 2, 0, 0, 0, 2,

0, 1, 2, 0, 0, 0, 2,

0, 1, 1, 0, 0, 0, 2,

0, 1, 1, 0, 0, 0, 2,

0, 1, 3, 0, 0, 0, 0,

0, 1, 3, 0, 0, 0, 0,

0, 1, 2, 0, 0, 0, 2,

0, 1, 2, 0, 0, 0, 2,

0, 1, 2, 0, 0, 0, 2,

/* 11.1.6.3 (Examples 32-49) */

1, 1, 1, 0, 0, 0, 0,

1, 1, 1, 0, 0, 0, 1,

1, 1, 3, 0, 0, 0, 1,

1, 1, 3, 0, 0, 0, 2,

1, 1, 3, 0, 0, 0, 0,

1, 1, 3, 0, 0, 0, 0,

1, 1, 0, 0, 0, 0, 0,

1, 1, 2, 0, 0, 0, 2,

1, 1, 2, 0, 0, 0, 2,

1, 1, 1, 0, 0, 0, 2,

1, 1, 1, 0, 0, 0, 2,

1, 1, 1, 0, 0, 0, 2,

1, 1, 1, 0, 0, 0, 2,

1, 1, 3, 0, 0, 0, 1,

1, 1, 3, 0, 0, 0, 1,

1, 1, 2, 0, 0, 0, 2,

1, 1, 2, 0, 0, 0, 2,

1, 1, 2, 0, 0, 0, 2,

/* 11.1.7.1 (Examples 50-60) */

0, 1, 1, 0, 1, 2, 3,

0, 1, 1, 0, 1, 2, 3,

0, 1, 3, 0, 1, 1, 3,

0, 1, 3, 0, 1, 2, 3,

0, 1, 3, 0, 1, 2, 3,

0, 1, 3, 0, 1, 1, 3,

0, 1, 0, 0, 1, 2, 3,

0, 1, 1, 0, 1, 1, 3,

0, 1, 3, 0, 1, 1, 3,

0, 1, 2, 0, 1, 1, 3,

0, 1, 2, 0, 1, 2, 3,

/* 11.1.7.2 (Examples 61-77) */

0, 1, 3, 0, 1, 1, 0,

0, 1, 1, 0, 1, 1, 0,

0, 1, 1, 0, 1, 1, 0,

0, 1, 3, 0, 1, 2, 0,

0, 1, 3, 0, 1, 1, 0,

0, 1, 3, 0, 1, 1, 0,

0, 1, 3, 0, 1, 1, 0,

0, 1, 0, 0, 1, 1, 0,

0, 1, 2, 0, 1, 2, 0,

0, 1, 2, 0, 1, 1, 0,

0, 1, 1, 0, 1, 1, 0,

0, 1, 1, 0, 1, 2, 0,

0, 1, 3, 0, 1, 1, 0,

0, 1, 3, 0, 1, 1, 0,

0, 1, 2, 0, 1, 1, 0,

0, 1, 2, 0, 1, 1, 0,

0, 1, 2, 0, 1, 1, 0,

/* 11.1.7.3 (Examples 78-90) */

1, 1, 1, 0, 1, 1, 0,

1, 1, 1, 0, 1, 2, 0,

1, 1, 1, 0, 1, 1, 0,

1, 1, 3, 0, 1, 1, 0,

1, 1, 3, 0, 1, 1, 0,

1, 1, 3, 0, 1, 1, 0,

1, 1, 0, 0, 1, 1, 0,

1, 1, 2, 0, 1, 2, 0,

1, 1, 2, 0, 1, 1, 0,

1, 1, 1, 0, 1, 1, 0,

1, 1, 1, 0, 1, 2, 0,

1, 1, 3, 0, 1, 1, 0,

1, 1, 2, 0, 1, 1, 0

};

fpnp xx[90][8] = {

/* API Chapter 11 examples */

/* Alpha60, To, Ta, Tb, Po, Pa, Density, Volume_To_Po */

/* 11.1.6.1 */

0, -27.7, -27.7, -27.7, 0, 0, 17.785, 987.99,

0, 301.93, 301.93, 301.93, 1500, 1500, -10, 285.5,

0, 48.04, 48.04, 48.04, -7.3, -7.3, 19.4, 12002,

0, 85, 85, 85, 247.3, 247.3, 0.7943, 1000,

0, 55.9, 55.9, 55.9, 350, 350, 48.0015, 10000,

0, 27.3, 27.3, 27.3, 1234.5, 1234.5, 657.3, 14.72,

0.000732185, 97.7, 97.7, 97.7, 287.4, 287.4, 1.0537, 203.85,

0, 129.3, 129.3, 129.3, 138.8, 138.8, 42.9, 99.98,

0, -58.05, -58.05, -58.05, 0, 0, 100, 1000,

0, 302.05, 302.05, 302.05, 0, 0, 100, 1000,

0, 92, 92, 92, 1501, 1501, 100, 1000,

0, 72, 72, 72, 0, 0, 100.06, 100.06,

0, 302, 302, 302, 0, 0, -10.08, 1000,

0, 0, 0, 0, 0, 0, 45.08, 1000,

0, 200, 200, 200, 0, 0, 100, 1000,

/* 11.1.6.2 */

0, 80.3, 80.3, 80.3, -5, -5, 823.7, 1000,

0, -57.95, -57.95, -57.95, 113.5, 113.5, 0.72332, 637483,

0, 68, 68, 68, 11, 11, 0.8665, 28.45,

0, 72, 72, 72, 375, 375, 41.4, 200.5,

0, 25.3, 25.3, 25.3, 267, 267, 803.141, 9998.7,

0, 139, 139, 139, 100, 100, 0.7322, 1000,

0.00057634, 84.5, 84.5, 84.5, 573, 573, 853.7, 5000,

0, 78.7, 78.7, 78.7, 128, 128, 23.6, 2500,

0, 302, 302, 302, 1499.97, 1499.97, 62, 989.4,

0, -58.05, -58.05, -58.05, 0, 0, 169.16, 1000,

0, 302.08, 302.08, 302.08, 1500.12, 1500.12, -13.88, 1000,

0, -58.05, -58.05, -58.05, 0, 0, 470.17, 1000,

0, 302.08, 302.08, 302.08, 1500.05, 1500.05, 1209.52, 1000,

0, 60, 60, 60, 0, 0, -14.53, 1000,

0, 72.32, 72.32, 72.32, 0, 0, 66.48, 1000,

0, -57.97, -57.97, -57.97, 240.7, 240.7, -14.51, 1000,

/* 11.1.6.3 */

0, 80.25, -57.9, -57.9, -5, 0, 823.7, 1000,

0, -57.95, 301.95, 301.95, 113.5, 1342, 0.7233, 9988.7,

0, 68.02, 150.3, 150.3, 11, 534, 0.8665, 285.45,

0, 72.04, -58, -58, 375, 47.75, 41.4, 14.95,

0, 35.34, 127.98, 127.98, 38.4, 121.8, 790.53, 99998,

0, 74.33, -50, -50, 2, -2.33, 602.6, 501.7,

0.00057634, 84.5, 97.4, 97.4, 157, 0, 853.7, 10000,

0, -57.9, 60, 60, 233, 245, -14.1, 251.2,

0, 302, 98.65, 98.65, 1499.97, 568.33, 36.43, 999.6,

0, -58.05, -58.05, -58.05, -5, -5, 169.16, 1000,

0, 302.08, 302.06, 302.06, 1500.43, 0, -13.87, 1000,

0, 89.08, 97.06, 97.06, 0.43, 27.75, -9.1, 1000,

0, 87.9, 237.8, 237.8, 172.34, 0, 105.3, 1000,

0, -58.05, -58.05, -58.05, 0, 0, 470.17, 1000,

0, 302.08, 302.05, 302.05, 1500.5, 0, 1209.56, 1000,

0, -58.05, -58.05, -58.05, 0, 0, -10.05, 1000,

0, 302.05, 302.05, 302.05, 1500.5, 0, 45.08, 1000,

0, -57.95, 60, 60, 233.7, 245.66, -14.15, 1000,

/* 11.1.7.1 */

0, -32.8, -32.8, 15, 24.6, 24.6, 772.3, 9885,

0, -32.8, -32.8, 20, 24.65, 24.65, 772.3, 397498,

0, 87.32, 87.32, 15, 75, 75, 865.6, 48.75,

0, 27.37, 27.37, 15, 17.05, 17.05, 793.5, 200.2,

0, -36, -36, 20, 8.6, 8.6, 772.3, 1502.3,

0, 27.35, 27.35, 15, 1235, 1235, 657.3, 1000,

0.000446759, 89.9, 89.9, 15, 45.35, 45.35, 641.8, 47.85,

0, -50.025, -50.025, 15, -5, -5, 610.46, 1000,

0, 150.025, 150.025, 20, 10343, 10343, 1163.55, 1000,

0, -50.025, -50.025, 15, 0, 0, 800.849, 1000,

0, 150.025, 150.025, 20, 103.43, 103.43, 1163.55, 1000,

/* 11.1.7.2 */

0, 82.35, 82.35, 15, 10005, 10005, 721.1, 10000,

0, 26.8, 26.8, 15, -5, -5, 823.7, 1000,

0, -50, -50, 15, 115, 115, 722.6, 145902,

0, 20, 20, 15, 11.25, 11.25, 865.6, 99873,

0, 22.25, 22.25, 15, 2587.3, 2587.3, 817.59, 400.15,

0, 1.85, 1.85, 15, 1835, 1835, 798.9, 1998.7,

0, 5.47, 5.47, 15, 1710, 1710, 779.6, 89987,

0.0005763, 29.18, 29.18, 15, 395, 395, 853.7, 8501.3,

0, -49.97, -49.97, 15, 31.1, 31.1, 1204.6, 100,

0, 150, 150, 15, 100, 100, 734.3, 987.37,

0, -50.05, -50.05, 15, 0, 0, 470.27, 1000,

0, 150.03, 150.03, 15, 103.425, 103.425, 1201.85, 1000,

0, -50.05, -50.05, 15, 0, 0, 470.17, 1000,

0, 150.02, 150.02, 15, 10342.5, 10342.5, 1209.56, 1000,

0, 15.56, 15.56, 15, 10342.5, 10342.5, 1208.52, 1000,

0, 22.42, 22.42, 15, 0, 0, 714.245, 1000,

0, 0.42, 0.42, 15, 0, 0, 723.45, 1000,

/* 11.1.7.3 */

0, 26.82, 90, 15, -5, 0, 823.687, 1247.65,

0, -40, 90, 15, 2.15, 24.35, 758.7, 1000,

0, 26.82, 68.45, 20, -5, 0, 823.687, 243.85,

0, 22.25, 102.35, 15, 2585, 3505, 817.55, 9987.5,

0, 1.85, 45.95, 20, 1835, 10342, 799, 15.85,

0, 5.45, -44.95, 15, 1708, 348, 779.6, 201.5,

0.00057634, 29.2, 55.05, 15, 395, 6505, 853.7, 1000,

0, -49.95, 67.65, 15, 31.1, 13.65, 1204.65, 200.04,

0, 35.8, 150, 20, 140, 10340, 734.29, 12501,

0, -50.05, -50.05, 15, 0, 0, 470.27, 1000,

0, 150.03, 150.03, 15, 103.425, 103.425, 1201.85, 1000,

0, 150.02, 150.02, 15, 10342.5, 10342.5, 1209.56, 1000,

0, 25.56, 36.85, 15, 10342.5, 0, 1208.52, 1000

};

papi0 = &api0; /* Put the address of 'api0' structure into 'piev' */

for (j=0; ; ) {

ii=0;

printf("\n\nSelect input parameter setup '0' or API example '1-90'.\n Type number between 0 and 90: ");

scanf("%d", &(ii));

if(ii>0 && ii<=90) {

ii=ii-1;

api0.Alternate=nn[ii][0];

printf("%s = ", text[0]);

scanf("%d", &(api0.Alternate));

api0.Rounding=nn[ii][1];

printf("%s = ", text[1]);

scanf("%d", &(api0.Rounding));

api0.Commodity=nn[ii][2];

api0.Alpha60_unit=nn[ii][3];

api0.Temperature_unit=nn[ii][4];

api0.Pressure_unit=nn[ii][5];

api0.Density_type=nn[ii][6];

api0.Alpha60=xx[ii][0];

api0.To=xx[ii][1];

api0.Ta=xx[ii][2];

api0.Tb=xx[ii][3];

api0.Po=xx[ii][4];

api0.Pa=xx[ii][5];

api0.Density=xx[ii][6];

api0.Volume_To_Po=xx[ii][7];

}

else {

printf("%s = ", text[0]);

scanf("%d", &(api0.Alternate));

printf("%s = ", text[1]);

scanf("%d", &(api0.Rounding));

printf("%s = ", text[2]);

scanf("%d", &(api0.Commodity));

printf("%s = ", text[3]);

scanf("%d", &(api0.Alpha60_unit));

printf("%s = ", text[4]);

scanf("%lf", &(api0.Alpha60));

printf("%s = ", text[5]);

scanf("%d", &(api0.Temperature_unit));

printf("%s = ", text[6]);

scanf("%lf", &(api0.To));

printf("%s = ", text[7]);

scanf("%lf", &(api0.Ta));

printf("%s = ", text[8]);

scanf("%lf", &(api0.Tb));

printf("%s = ", text[9]);

scanf("%d", &(api0.Pressure_unit));

printf("%s = ", text[10]);

scanf("%lf", &(api0.Po));

printf("%s = ", text[11]);

scanf("%lf", &(api0.Pa));

printf("%s = ", text[12]);

scanf("%d", &(api0.Density_type));

printf("%s = ", text[13]);

scanf("%lf", &(api0.Density));

printf("%s = ", text[14]);

scanf("%lf", &(api0.Volume_To_Po));

}

api11(papi0); /* Call function by passing the pointer to structure */

/* Print input parameters */

printf("\nI N P U T P A R A M E T E R S:");

printf("\n%s = %d",text[0], api0.Alternate);

printf("\n%s = %d",text[1], api0.Rounding);

printf("\n%s = %d",text[2], api0.Commodity);

printf("\n%s = %d",text[3], api0.Alpha60_unit);

printf("\n%s = %lf",text[4], api0.Alpha60);

printf("\n%s = %d",text[5], api0.Temperature_unit);

printf("\n%s = %lf",text[6], api0.To);

printf("\n%s = %lf",text[7], api0.Ta);

printf("\n%s = %lf",text[8], api0.Tb);

printf("\n%s = %d",text[9], api0.Pressure_unit);

printf("\n%s = %lf",text[10], api0.Po);

printf("\n%s = %lf",text[11], api0.Pa);

printf("\n%s = %d",text[12], api0.Density_type);

printf("\n%s = %lf",text[13], api0.Density);

printf("\n%s = %lf",text[14], api0.Volume_To_Po);

printf("\nO U T P U T P A R A M E T E R S:");

printf("\n%s = %xH",text[15], api0.error_status);

printf("\n%s = %d",text[16], api0.Commodity_out);

printf("\n%s = %lf",text[17], api0.Fp_o_psi);

printf("\n%s = %lf",text[18], api0.Fp_a_psi);

printf("\n%s = %lf",text[19], api0.Fp_o_spu);

printf("\n%s = %lf",text[20], api0.Fp_a_spu);

printf("\n%s = %lf",text[21], api0.Ctl_60_b);

printf("\n%s = %lf",text[22], api0.Ctpl_60_o);

printf("\n%s = %lf",text[23], api0.Ctpl_60_o_r);

printf("\n%s = %lf",text[24], api0.Ctpl_60_a);

printf("\n%s = %lf",text[25], api0.Ctpl_60_a_r);

printf("\n%s = %lf",text[26], api0.Ctpl_Tb_o);

printf("\n%s = %lf",text[27], api0.Ctpl_Tb_o_r);

printf("\n%s = %lf",text[28], api0.Ctpl_Tb_a);

printf("\n%s = %lf",text[29], api0.Ctpl_Tb_a_r);

printf("\n%s = %lf",text[30], api0.Density_60_kg_cum);

printf("\n%s = %lf",text[31], api0.Density_60_API);

printf("\n%s = %lf",text[32], api0.Density_60_rel);

printf("\n%s = %lf",text[33], api0.Density_Tb_kg_cum);

printf("\n%s = %lf",text[34], api0.Density_Tb_API);

printf("\n%s = %lf",text[35], api0.Density_Tb_rel);

printf("\n%s = %lf",text[36], api0.Density_To_Po_kg_cum);

printf("\n%s = %lf",text[37], api0.Density_To_Po_kg_cum_r);

printf("\n%s = %lf",text[38], api0.Density_To_Po_API);

printf("\n%s = %lf",text[39], api0.Density_To_Po_API_r);

printf("\n%s = %lf",text[40], api0.Density_To_Po_rel);

printf("\n%s = %lf",text[41], api0.Density_To_Po_rel_r);

printf("\n%s = %lf",text[42], api0.Density_Ta_Pa_kg_cum);

printf("\n%s = %lf",text[43], api0.Density_Ta_Pa_kg_cum_r);

printf("\n%s = %lf",text[44], api0.Density_Ta_Pa_API);

printf("\n%s = %lf",text[45], api0.Density_Ta_Pa_API_r);

printf("\n%s = %lf",text[46], api0.Density_Ta_Pa_rel);

printf("\n%s = %lf",text[47], api0.Density_Ta_Pa_rel_r);

printf("\n%s = %lf",text[48], api0.Volume_60);

printf("\n%s = %lf",text[49], api0.Volume_60_r);

printf("\n%s = %lf",text[50], api0.Volume_Tb);

printf("\n%s = %lf",text[51], api0.Volume_Tb_r);

printf("\n%s = %lf",text[52], api0.Volume_Ta_Pa_60);

printf("\n%s = %lf",text[53], api0.Volume_Ta_Pa_60_r);

printf("\n%s = %lf",text[54], api0.Volume_Ta_Pa_Tb);

printf("\n%s = %lf",text[55], api0.Volume_Ta_Pa_Tb_r);

printf("\nPress X to exit or anything else to continue: ");

ch = getch();

if (( ch == 'X') || (ch == 'x'))

break;

}

}

/* ********************************** */

/* THE END OF THE MAIN PROGRAM C-CODE */

/* ********************************** */

6. Examples for the verification of the api11 routine

The examples for verification are given in:

API: Manual of Petroleum Measurement Standards

Chapter 11: Physical Properties Data

Section 1: Temperature and Pressure Correction Factors for Generalized Crude Oils, refined Products, and Lubricating Oils

The examples are built into the program given in section 5. The examples are numbered 1-90 in the order they appear in the manual from section 11.1.6.1, through 11.1.6.2, 11.1.6.3, 11.1.7.1, 11.1.7.2 to 11.1.7.3.