0.1.1 WaterMix

Author: RobTillaart

libraries/WaterMix/CHANGELOG.md

@@ -6,6 +6,16 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
 
+## [0.1.1] - 2023-08-30
+- add **void addExact(float volume, float temperature)** (works only for water).
+- add **float mass()** (works only for water).
+- add **float volume2mass(float volume, float temperature)** (works only for water).
+- add **float mass2volume(float mass, float temperature)** (works only for water).
+- update readme.md
+- fix keywords.txt
+- minor edits
+
+
 ## [0.1.0] - 2023-08-29
 - initial version
 

libraries/WaterMix/README.md

@@ -20,43 +20,46 @@ Arduino library for mixing water with different temperatures.
 
 Experimental library for elementary math of mixing water with different temperatures.
 
-The library does some indicative math of mixing a volume of water with temperature T1
+The library provides math for mixing a volume of water with temperature T1
 with a another volume with temperature temperature T2.
-In fact the library will work for any single liquid (TODO: liquidMix class).
+In fact the library will work for any single liquid (TODO: liquidMix class),
+although some functions are **water specific**.
+
+This library is useful e.g. by doing "water math" for aquaria or cooking.
+Also the library is well suited for basic educational purposes.
+
+
+#### Limitations
 
 The library uses a generic volume parameter instead of gallons or liters as
 this way any user selected unit can be used.
-However you must use the chosen units consistently as you cannot use different
-units simultaneously. 
+However you must use the chosen units consistently as the library cannot handle
+different units simultaneously.
 
-To use different units for volume you can get some help of the volume conversion 
-library named **VolumeConverter** to convert the units.
+To use different units for volume you can convert them with the library named
+**VolumeConverter**.
 
 The temperature unit can also be chosen by the user and can be Kelvin, Celsius,
 Fahrenheit or other.
-However you must use the chosen units consistently as you cannot use different
-units simultaneously. Check **Temperature** library below.
-
-This library could be useful e.g. by doing "water math" for aquaria or cooking.
-Also the library is well suited for basic educational purposes.
+However you must use the chosen units consistently as the library cannot handle
+different units simultaneously. Check **Temperature** library below for conversion.
 
 
 #### Accuracy
 
 The working range for temperature is not tested with real water.
-It is expected to work (roughly) for water with a range from 5°C to 80°C.
-In the (0.1.0) math it is assumed there is no expansion so the mass / volume is
-identical for "both volumes of waters".
+It is expected to work quite well for water with a range from 5°C to 80°C.
+In the basic math the **add()** function assumes there is no expansion so
+the density is identical for "both volumes of waters".
 
-Of course this is incorrect, therefore it is expected to have a difference 
+Of course this is incorrect, therefore it is expected to have a difference
 between the theoretical values and doing the mixing in practice.
 However the delta's are expected to be small, less than 1% in many cases.
 Given the accuracy of volume measurement and temperature measurement,
 this delta is often acceptable.
 
-TODO: 
-- investigate in the effect of the volume expansion and contraction of 
-  the water due to the temperature delta, and how to handle it.
+If one wants a more exact answer, one should use the **addExact()** function
+as this compensates for the density of the water at a given temperature.
 
 
 #### Related
@@ -75,29 +78,71 @@ TODO:
 #### Constructor
 
 - **WaterMix()** constructor, starts with no water of 0°
-- **void begin()** resets to no water of 0°.
+- **void begin(float volume = 0, float temperature = 0)**
+sets initial values, default no water of 0°.
+
+#### Math
+
 - **void add(float volume, float temperature)** add an amount of water
 with temperature to the "WaterMix".
+- **void addExact(float volume, float temperature)**  Water only!
+add an amount of water with temperature to the "WaterMix".
+The math is calculated including using the density of the water.
+This is slower as **add()** but more exact.
+Note the temperature must be in °C.
 - **void sub(float volume)** subtract a volume from the "WaterMix".
 Temperature won't change.
 - **void div(float nr)** divide the amount of liquid, same temperature.
 - **void mul(float nr)** multiply the amount of liquid, same temperature.
+
+#### Getters
+
 - **float volume()** get the current volume.
 - **float temperature()** get the current temperature.
+- **float mass()** get the mass of the current volume. Water only!
+
+#### Converters
+
+- **float volume2mass(float volume, float temperature)** idem, Water only!
+Use volume == 1 to get the density at a certain temperature.
+- **float mass2volume(float mass, float temperature)** idem, Water only!
+
+
+## Performance
+
+Most functions are just fast, the only that do the core math are add() 
+and addExact(). 
+The WaterMix_exact.ino sketch provides some performance figures shown
+here. 
+Note that the **addExact()** differs in runtime as it uses a linear lookup
+for the density so the numbers below are indicative.
+
+|  Function    |  time (us)  |  Notes  |
+|:------------:|:-----------:|:--------|
+|   add()      |    72       |
+|  addExact()  |   576       |  most accurate  |
+
+Note it is possible to tune the linear lookup of the density by reducing 
+the amount of interpolation points in the tables (at your own risk).
+This will reduce the accuracy however still be better than the fast **add()**.
+
+Performance of **addExact()** can be improved by caching the mass of the water.
+To be investigated.
 
 
 ## Volumetric Coefficient of Expansion
 
 The VCE is not supported in the library.
+(0.1.1 supports an **addExact()** for water only, temperature in °C)
 
-It is useful as background information as the theoretical volumes calculated in this 
-library will differ from reality due to the VCE effect. 
-This difference depends on the liquid used and the delta temperature. 
+The VCE is useful as background information as the theoretical volumes calculated
+in this library will differ from reality due to the VCE effect.
+This difference depends on the liquid used and the delta temperature.
 
 
 #### Water
 
-The VCE of water depends on the temperature, doing the math needs to be investigated.
+The VCE of water depends on the temperature.
 
 Source: - https://www.engineeringtoolbox.com/water-density-specific-weight-d_595.html
 
@@ -158,45 +203,47 @@ Source: - https://www.engineeringtoolbox.com/cubical-expansion-coefficients-d_12
 #### Must
 
 - update documentation
+  - library can be used for water and salinity and other linear related things.
+- investigate linear expansion 
+  - VCE as parameter.
 
 
 #### Should
 
 - create base class **LiquidMix** and derive a specific **WaterMix** from it.
-  - code is quite identical
-  - **WaterMix** can include specific heat, VCE etc.
-- include expansion of water VCE effect due to heat.
-  - 4°C is smallest for water.
-  - must use defined liquid and temp scale.
-  - or add an expansion function?
-  - needs investigation
+  - code is quite identical, easy to split/strip water specific functions
+  - **WaterMix** can include specific heat, density, VCE etc.
+  - 0.2.0
+  - **WaterMixF()** Fahrenheit, as derived class too.
+  - **WaterMixK()** Kelvin?
+- do not make the library too complex (see could below).
+- extend unit tests
+- investigate the caching of the mass of the water.
+  - add Exact only, 4 bytes..
 
 
 #### Could
 
-- performance measurements
 - cool(time) == depends on many factors
   - need to configure curve constant (only option).
   - must use defined liquid and temp scale.
-- energy functions to calculate how hot an amount of water
-  should be to reach a certain temperature. 
-  - Think Aquaria or cooking.
-- add "unit string" + Printable interface?  
-  - -idem Temp scale?
-- extend unit tests
-- rename to **LiquidMix** class
-  - WaterMixCelsius as derived class?
-  - WaterMixFahrenheit as derived class? etc.
 - catch temperature below zero?
   - must use defined liquid and temp scale.
-- library can be used for water and salinity too
-  - other linear related things.
+  - user responsibility for now.
 - **void AddEnergy(float joule)** to raise temperature (joule)
   - must use defined liquid and temp scale.
-  - specific heat needed.
-  
-  
-#### Wont
+  - specific heat needed.  (Water only?)
+- replace div and mul with operators \* and \/
+- use double iso float?
+
+
+#### Wont (or on special request)
+
+- add "unit string" + Printable interface?
+  -idem Temp scale?
+- energy functions to calculate how hot an amount of water
+  should be to reach a certain temperature.
+  - Think Aquaria or cooking.
 
 
 ## Support

libraries/WaterMix/WaterMix.h

@@ -3,14 +3,14 @@
 //    FILE: WaterMix.h
 //  AUTHOR: Rob Tillaart
 // PURPOSE: Arduino library for mixing water with different temperatures.
-// VERSION: 0.1.0
+// VERSION: 0.1.1
 //     URL: https://github.com/RobTillaart/WaterMix
 
 
 #include "Arduino.h"
 
 
-#define WATERMIX_LIB_VERSION     (F("0.1.0"))
+#define WATERMIX_LIB_VERSION     (F("0.1.1"))
 
 
 class WaterMix
@@ -23,10 +23,10 @@ class WaterMix
   }
 
 
-  void begin()
+  void begin(float volume = 0, float temperature = 0)
   {
-    _volume = 0;
-    _temperature = 0;
+    _volume = volume;
+    _temperature = temperature;
   }
 
 
@@ -39,12 +39,30 @@ class WaterMix
   }
 
 
+  void addExact(float volume, float temperature)
+  {
+    if (volume <= 0) return;  //  false
+    float mass0     = _volume * _density(_temperature);
+    float mass1     =  volume * _density(temperature);
+    float totalMass =  mass0 + mass1;
+
+    _temperature = (mass0 * _temperature + mass1 * temperature) / totalMass;
+    _volume = totalMass / _density(_temperature);
+  }
+
+
   void add(WaterMix &wm)
   {
     add(wm.volume(), wm.temperature());
   }
 
 
+  void addExact(WaterMix &wm)
+  {
+    addExact(wm.volume(), wm.temperature());
+  }
+
+
   void sub(float volume)
   {
     _volume -= volume;
@@ -67,7 +85,7 @@ class WaterMix
   }
 
 
-  float volume() 
+  float volume()
   {
     return _volume;
   }
@@ -79,9 +97,60 @@ class WaterMix
   }
 
 
+  float mass()
+  {
+    return _volume * _density(_temperature);
+  }
+
+
+  float volume2mass(float volume, float temperature)
+  {
+    return volume * _density(temperature);
+  }
+
+
+  float mass2volume(float mass, float temperature)
+  {
+    return mass / _density(temperature);
+  }
+
+
 private:
   float   _volume;
   float   _temperature;
+
+
+  //  _density is in fact multiMap code
+  float  _density(float temperature)
+  {
+    //  strip table size?
+    uint8_t size = 22;
+    uint8_t _in[]  = { 0, 1, 4, 10, 15, 20, 25, 30, 35, 40, 45, 50, 55, 60, 65, 70, 75, 80, 85, 90, 95, 100};
+    float _out[] = {
+      0.9998495,  0.9999017,  0.9999749,  0.9997000,  0.9991026,
+      0.9982067,  0.9970470,  0.9956488,  0.9940326,  0.9922152,
+      0.9902100,  0.9880400,  0.9856900,  0.9832000,  0.9805500,
+      0.9777600,  0.9748400,  0.9717900,  0.9686100,  0.9653100,
+      0.9618900,  0.9583500
+    };
+
+
+    //  take care the temperature is within range
+    //  temperature = constrain(temperature, _in[0], _in[size-1]);
+    if (temperature <= _in[0]) return _out[0];
+    if (temperature >= _in[size-1]) return _out[size-1];
+
+    //  search right interval
+    uint8_t pos = 1;  //  _in[0] already tested
+    while(temperature > _in[pos]) pos++;
+
+    //  this will handle all exact "points" in the _in array
+    if (temperature == _in[pos]) return _out[pos];
+
+    //  interpolate in the right segment for the rest
+    uint8_t pos1 = pos - 1;
+    return (temperature - _in[pos1]) * (_out[pos] - _out[pos1]) / (_in[pos] - _in[pos1]) + _out[pos1];
+  }
 };