api11 - Instructions for use
Revision:
URL: http://www.felib.com
E-mail: info@felib.com
api11 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 Standards,
Published by American Petroleum Institute, May 2004.
References:
1. Manual of Petroleum
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
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
/* Density_type
= 1 – Observed relative density at To and
/* Density_type
= 2 – Observed API gravity at To and
/* 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
/* 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
fpnp Ctpl_60_o_r; /* Combined rounded correction factor to
correct density & volume at 60 °F to observed
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
fpnp Ctpl_Tb_o_r; /* Combined rounded correction factor to
correct density & volume at Tb to observed
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
fpnp
Density_To_Po_kg_cum_r; /* Rounded density in
kg/cu m at observed conditions To and
fpnp
Density_To_Po_API; /*
Un-rounded density in °API at observed conditions To and
fpnp
Density_To_Po_API_r; /*
Rounded density in °API at observed conditions To and
fpnp
Density_To_Po_rel; /*
Un-rounded relative density at observed conditions To and
fpnp
Density_To_Po_rel_r; /*
Rounded relative density at observed conditions To and
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 |
|
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, |
dimensionless |
|
double |
Ctpl_60_o_r |
Rounded correction from 60°F
to To, |
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, |
dimensionless |
|
double |
Ctpl_Tb_o_r |
Rounded correction from Tb
to To, |
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/m3 |
|
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/m3 |
|
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, |
kg/m3 |
|
double |
Density_To_Po_kg_cum_r |
Rounded density at To, |
kg/m3 |
|
double |
Density_To_Po_API |
Un-rounded density at To, |
°API |
|
double |
Density_To_Po_API_r |
Rounded density at To, |
°API |
|
double |
Density_To_Po_rel |
Un-rounded relative density
at To, |
dimensionless |