Potash Properties Utility

From SysCAD Documentation
Jump to navigation Jump to search

Related Links: Potash Solubility, Potash Species Model


General Description

The SysCAD Potash Properties Utility is a separate utility, which may be used to calculate some of the properties of an aqueous stream containing KCl and NaCl, and optionally MgCl2, CaCl2 and CaSO4.

This utility is distributed as a library SysCADPotashProps.dll (32 bit) or SysCADPotashProps64.dll (64 bit) and may be called by any third party software that supports making calls to a DLL, including from any programing language, Excel (using VBA), some laboratory software, DCS systems, etc.

Also distributed:

  • A simple user interface console application, SysCADPotash.exe, which may be used as a stand alone calculator to display Potash properties.
  • An example Excel spreadsheet with VBA macro code examples that call the Potash Properties library and returns the calculated properties.

Notes:

  1. The saturated values of KCl(aq) and NaCl(aq) in solutions are obtained from values available in published data by D'Ans. Please see Potash Solubility for more information and the relevant references).
  2. Equivalent MgCl2 for the extended range is used in calculations.
  3. The specific heat, Cp, and density are calculated using the Low Fidelity water calculations and the equations defined in papers by Laliberte et al1,2,3. (The Laliberte equations are given in the Potash Species Model).
  4. The underlying calculations are the same as the ones used in the full SysCAD software, with the same temperature ranges, limitations on MgCl2 concentrations, etc. Please see the Potash Solubility section for more details.

Installing the Utility Files

There are three files that Kenwalt distributes with the Potash Properties Utility:

  • SysCADPotashProps.dll;
  • SysCADPotash.exe; and
  • PotashPropertiesDemo.xlsm

The SysCADPotashProps.dll is the file that does all of the calculations.

  • This file should be saved where the required 3rd party software can find it:
    • The documentation of the software will define the search path, or the user may be able to define the full path for the SysCADPotashProps.dll.
    • For example, if the calling software is Excel, then this file can simply be saved in the c:\Windows folder.

The SysCADPotash.exe and PotashPropertiesDemo.xlsm files may be stored anywhere on the computer. These are interface files for a user to see the results.

Other Files that are Required

The user must also have the Microsoft Visual c++ 2017 Redistributable package installed on their computer. Many software packages (including SysCAD) require this package and most users will already have it installed on their computer. If it is not installed, please follow one these steps:

  • Go to the Microsoft downloads web page and download the required Visual C++ 2017 Redistributable Package. Once it is downloaded please install it on your computer; OR
  • If SysCAD is installed on your computer, go to C:\SysCADNNN\Setup\MS VC Redist and run vcredist_x86.exe.

Input Data

The user is required to specify the following data when calling the SysCAD Potash Properties Utility:

  • Specify if the species will be entered as Mass Fraction, Mass Ratio (g/100g water) or Concentration;
  • Temperature in Kelvin;
  • Each of the following species as Mass Fraction, Mass Ratio or Concentration, depending on what the user has defined:
  • Aqueous KCl in solution;
  • Aqueous NaCl in solution;
  • Aqueous MgCl2 in solution;
  • Aqueous CaCl2 in solution; and
  • Aqueous CaSO in solution4.

Notes:

  1. The user MUST specify all of the above data.
  2. All of the species must be entered in the same mass specification, i.e. all as Mass Fraction, or all as Concentration, etc.
  3. The amount of any of the species may be zero.
  4. The Potash Properties Utility carries out all of the calculations using SI units and the calls to the utility must be in these units. The user interface, such as Excel, may be configured to display different units, if required.

Calculated Properties

The SysCAD Potash Properties Library allows third party software to call any one or all of the following properties:

Property Description
Density Density of solution in kg/m2.
Cp Specific Heat of solution in kJ/kg.C.
Region The region in which the solution is located - this will be a numerical value that corresponds to the regions described in the table below.
MgCl2 equiv The MgCl2 equivalent value - this is used to depress the solubility values of KCl and NaCl. Calculated as g/100g water.
Both Sat The Saturated values if both KCl and NaCl were saturated at the solution temperature. Calculated as g/100g water.
One Sat The saturated value of KCl with NaCl at either it's actual value, or it's saturated value, whichever is the lowest.
Similarly, the saturated value of NaCl with KCl at either it's actual value, or it's saturated value, whichever is the lowest.
Calculated as g/100g water.
Sat Frac The fraction of saturation of KCl and NaCl in the solution. These are calculated as the Actual values / Sat values (where Sat value = One Sat value).
Region Description Short text description for given region.
Version Major and minor version numbers of the SysCAD Potash Properties Utility.
Water Density Low fidelity density in kg/m2 of water at given temperature.
Water Cp Low fidelity Specific Heat in kJ/kg.C of water at given temperature.


Regions

The region in which the solution is located is displayed as a numerical value. The regions to which the values refer are described below:

Region KCl state NaCl State
0 No KCl No NaCl
1 No KCl NaCl is present and is not saturated.
2 No KCl NaCl is present and saturated.
3 No KCl NaCl is present and supersaturated.
4 KCl is present and is not saturated. No NaCl.
5 KCl is present and is not saturated. NaCl is present and is not saturated.
6 KCl is present and is not saturated. NaCl is present and is saturated.
7 KCl is present and is not saturated. NaCl is present and is supersaturated.
8 KCl is present and is saturated. No NaCl.
9 KCl is present and is saturated. NaCl is present and is not saturated.
10 KCl is present and is saturated. NaCl is present and is saturated.
11 KCl is present and is saturated. NaCl is present and is supersaturated.
12 KCl is present and is supersaturated. No NaCl.
13 KCl is present and is supersaturated. NaCl is present and is not saturated.
14 KCl is present and is supersaturated. NaCl is present and is saturated.
15 KCl is present and is supersaturated. NaCl is present and is supersaturated.

Potash Properties Library

The SysCADPotashProps.dll library should be saved where the required 3rd party software can find it. The documentation of the software will define the search path, or the user may be able to define the full path for the SysCADPotashProps.dll.

For an example of the calls to the SysCADPotashProps.dll, please see the VBA code in the example Excel spreadsheet. The properties can be calculated and returned individually in multiple calls to the DLL, but it is significantly more efficient to make a single call which returns all of the results.

For the more efficient function calls that return full result sets, there are three forms for the input data as mass fractions, mass ratios or concentrations.

C API

Main API functions are:

  • long PotashSolub(double T, double fracKCl, double fracNaCl, double fracMgCl2, double fracCaSO4, double fracCaCl2, PotashSolubOut& result);
  • long PotashSolubMR(double T, double KCl, double NaCl, double MgCl2, double CaSO4, double CaCl2, PotashSolubOut& result);
  • long PotashSolubConc(double T, double concKCl, double concNaCl, double concMgCl2, double concCaSO4, double concCaCl2, PotashSolubOut& result);
  • long PotashAll(double T, double fracKCl, double fracNaCl, double fracMgCl2, double fracCaSO4, double fracCaCl2, PotashPropsOut& result);
  • long PotashAllMR(double T, double KCl, double NaCl, double MgCl2, double CaSO4, double CaCl2, PotashPropsOut& result);
  • long PotashAllConc(double T, double concKCl, double concNaCl, double concMgCl2, double concCaSO4, double concCaCl2, PotashPropsOut& result);
  • long PotashRatioToFrac(double T, double KCl, double NaCl, double MgCl2, double CaSO4, double CaCl2, PotashPropsIn& result);
  • long PotashConcToFrac(double T, double concKCl, double concNaCl, double concMgCl2, double concCaSO4, double concCaCl2, PotashPropsIn& result);
  • long PotashVersion(long Index);
  • void PotashRegionDescA(long Region, char* zBuffer, long bufferSize);
  • void PotashRegionDescW(long Region, wchar_t* zBuffer, long bufferSize);
  • double WaterCp(double T);
  • double WaterDensity(double T);

The data structure for results for PotashSolub is:

struct PotashSolubOut
 {
 public:
   long Region;
   double KSat_NaAct;
   double NaSat_KAct;
   double KSat_NaSat;
   double NaSat_KSat;
   double KSatFrac;
   double NaSatFrac;
   double MgCl2_Equiv;
 };

The data structure for results for PotashAll is:

struct PotashPropsOut
 {
 public:
   double Cp;
   double Density;
   long Region;
   double KSat_NaAct;
   double NaSat_KAct;
   double KSat_NaSat;
   double NaSat_KSat;
   double KSatFrac;
   double NaSatFrac;
   double MgCl2_Equiv;
 };

The data structure for results for PotashRatioToFrac and PotashConcToFrac is:

struct PotashPropsOut
 {
 public:
   double T;
   double KCl;
   double NaCl;
   double MgCl2;
   double CaSO4;
   double CaCl2;
 };

Alternate API calls for PotashSolub and PotashAll that don't return results in a structure are:

  • long PotashSolub_Ind(double T, double fracKCl, double fracNaCl, double fracMgCl2, double fracCaSO4, double fracCaCl2, long& Region, double& KSat_NaAct, double& NaSat_KAct, double& KSat_NaSat, double& NaSat_KSat, double& KSatFrac, double& NaSatFrac, double& MgCl2_Equiv);
  • long PotashAll_Ind(double T, double fracKCl, double fracNaCl, double fracMgCl2, double fracCaSO4, double fracCaCl2, double& Cp, double& Density, long& Region, double& KSat_NaAct, double& NaSat_KAct, double& KSat_NaSat, double& NaSat_KSat, double& KSatFrac, double& NaSatFrac, double& MgCl2_Equiv);

Other API functions for individual calculations (less efficient) are:

  • double PotashCp(double T, double fracKCl, double fracNaCl, double fracMgCl2, double fracCaSO4, double fracCaCl2);
  • double PotashCp_EC(double T, double fracKCl, double fracNaCl, double fracMgCl2, double fracCaSO4, double fracCaCl2, long& errorCode);
  • double PotashDensity(double T, double fracKCl, double fracNaCl, double fracMgCl2, double fracCaSO4, double fracCaCl2);
  • double PotashDensity_EC(double T, double fracKCl, double fracNaCl, double fracMgCl2, double fracCaSO4, double fracCaCl2, long& errorCode);
  • long PotashRegion(double T, double fracKCl, double fracNaCl, double fracMgCl2, double fracCaSO4, double fracCaCl2);
  • long PotashRegion_EC(double T, double fracKCl, double fracNaCl, double fracMgCl2, double fracCaSO4, double fracCaCl2, long& errorCode);
  • double PotashKSat_NaAct(double T, double fracKCl, double fracNaCl, double fracMgCl2, double fracCaSO4, double fracCaCl2);
  • double PotashKSat_NaAct_EC(double T, double fracKCl, double fracNaCl, double fracMgCl2, double fracCaSO4, double fracCaCl2, long& errorCode);
  • double PotashNaSat_KAct(double T, double fracKCl, double fracNaCl, double fracMgCl2, double fracCaSO4, double fracCaCl2);
  • double PotashNaSat_KAct_EC(double T, double fracKCl, double fracNaCl, double fracMgCl2, double fracCaSO4, double fracCaCl2, long& errorCode);
  • double PotashKSat_NaSat(double T, double fracKCl, double fracNaCl, double fracMgCl2, double fracCaSO4, double fracCaCl2);
  • double PotashKSat_NaSat_EC(double T, double fracKCl, double fracNaCl, double fracMgCl2, double fracCaSO4, double fracCaCl2, long& errorCode);
  • double PotashNaSat_KSat(double T, double fracKCl, double fracNaCl, double fracMgCl2, double fracCaSO4, double fracCaCl2);
  • double PotashNaSat_KSat_EC(double T, double fracKCl, double fracNaCl, double fracMgCl2, double fracCaSO4, double fracCaCl2, long& errorCode);
  • double PotashKSatFrac(double T, double fracKCl, double fracNaCl, double fracMgCl2, double fracCaSO4, double fracCaCl2);
  • double PotashKSatFrac_EC(double T, double fracKCl, double fracNaCl, double fracMgCl2, double fracCaSO4, double fracCaCl2, long& errorCode);
  • double PotashNaSatFrac(double T, double fracKCl, double fracNaCl, double fracMgCl2, double fracCaSO4, double fracCaCl2);
  • double PotashNaSatFrac_EC(double T, double fracKCl, double fracNaCl, double fracMgCl2, double fracCaSO4, double fracCaCl2, long& errorCode);
  • double PotashMgCl2Equiv(double T, double fracKCl, double fracNaCl, double fracMgCl2, double fracCaSO4, double fracCaCl2);
  • double PotashMgCl2Equiv_EC(double T, double fracKCl, double fracNaCl, double fracMgCl2, double fracCaSO4, double fracCaCl2, long& errorCode);

VBA API

Below are VBA (eg Excel) declarations for accassing some of the main SysCADPotashProps.dll Library functions.

Library version (Index=0 for major; Index=1 for minor):

  • Private Declare Function PotashVersion Lib "SysCADPotashProps.dll" (ByVal Index As Long) As Long

Calculate various solubility results. Three formats with inputs as mass fraction, concentration (g/L) and mass ratio (g/100g). Return error:

  • Private Declare Function PotashSolub Lib "SysCADPotashProps.dll" (ByVal T As Double, ByVal fracKCl As Double, ByVal fracNaCl As Double, ByVal fracMgCl2 As Double, ByVal fracCaSO4 As Double, ByVal fracCaCl2 As Double, ByRef Results As SolubResults) As Long
  • Private Declare Function PotashSolubConc Lib "SysCADPotashProps.dll" (ByVal T As Double, ByVal concKCl As Double, ByVal concNaCl As Double, ByVal concMgCl2 As Double, ByVal concCaSO4 As Double, ByVal concCaCl2 As Double, ByRef Results As SolubResults) As Long
  • Private Declare Function PotashSolubMR Lib "SysCADPotashProps.dll" (ByVal T As Double, ByVal KCl As Double, ByVal NaCl As Double, ByVal MgCl2 As Double, ByVal CaSO4 As Double, ByVal CaCl2 As Double, ByRef Results As SolubResults) As Long

Calculate various properties and solubility results. Three formats with inputs as mass fraction, concentration (g/L) and mass ratio (g/100g). Return error:

  • Private Declare Function PotashAll Lib "SysCADPotashProps.dll" (ByVal T As Double, ByVal fracKCl As Double, ByVal fracNaCl As Double, ByVal fracMgCl2 As Double, ByVal fracCaSO4 As Double, ByVal fracCaCl2 As Double, ByRef Results As PotashResults) As Long
  • Private Declare Function PotashAllConc Lib "SysCADPotashProps.dll" (ByVal T As Double, ByVal concKCl As Double, ByVal concNaCl As Double, ByVal concMgCl2 As Double, ByVal concCaSO4 As Double, ByVal concCaCl2 As Double, ByRef Results As PotashResults) As Long
  • Private Declare Function PotashAllMR Lib "SysCADPotashProps.dll" (ByVal T As Double, ByVal KCl As Double, ByVal NaCl As Double, ByVal MgCl2 As Double, ByVal CaSO4 As Double, ByVal concCaCl2 As Double, ByRef Results As PotashResults) As Long

Convert inputs to Frac format:

  • Private Declare Function PotashConcToFrac Lib "SysCADPotashProps.dll" (ByVal T As Double, ByVal concKCl As Double, ByVal concNaCl As Double, ByVal concMgCl2 As Double, ByVal concCaSO4 As Double, ByVal concCaCl2 As Double, ByRef Fracs As PotashData) As Long
  • Private Declare Function PotashRatioToFrac Lib "SysCADPotashProps.dll" (ByVal T As Double, ByVal KCl As Double, ByVal NaCl As Double, ByVal MgCl2 As Double, ByVal CaSO4 As Double, ByVal CaCl2 As Double, ByRef Fracs As PotashData) As Long


Calculate Water Cp and Density:

  • Private Declare Function WaterCp Lib "SysCADPotashProps.dll" (ByVal T As Double) As Double
  • Private Declare Function WaterDensity Lib "SysCADPotashProps.dll" (ByVal T As Double) As Double

See example VBA code provided for further details.

Stand-alone Application

A simple useful stand alone console application "SysCADPotash.exe" is provided that can be used as a calculator for entering data and displaying Potash Properties. Stream data can also be copied and pasted between the utility and SysCAD or Excel. This console application has a simple interface, with limited options.

This file may be located in the SysCAD bin folder or at any location on the users computer.

The interface is shown below:

PotashUtility.png

Entering data

When the user starts the interface it will display the values for default data. To update the results:

  1. Enter a key to define how the masses of the species will be entered:
    • Push any key ('Enter' works well) to enter the species by Concentration; OR
    • Type F to enter the species as Fractions; OR
    • Type R to enter the species as Mass Ratios (g/100g water);
  2. The first required input, Temperature, will be displayed with the current value, in 0C;
  3. The user may push the 'Enter' key to keep the current value for any of the required inputs;
  4. To enter a different value, type in the required value and then push the 'Enter' key;
  5. Continue until all the inputs have been updated (or left as current values).

Once all of the required inputs are entered, the calculated values will be displayed.

To exit, push 'Q' or close the application console window.

Importing and Exporting data

To copy inputs and results to clipboard which can then be pasted to Excel push 'C'.

Rather than entering data manually it is possible to paste data from either SysCAD or Excel using the clipboard:

  • From SysCAD on the Access window in any pipe or unit showing stream data (eg Qi, Qo, QFeed, QProd, etc) select the "Copy to Clipboard" button; or
  • From Excel select (from previously pasted data) and copy to clipboard. The selection would typically be three columns by a number of rows.
  • Then in Potash Console Application push 'P' to paste the data. The inputs from the clipboard will be used and the results re-calculated. Any unrecognised data in clipboard is ignored.