eXept Software AG Logo

Smalltalk/X Webserver

Documentation of class 'MeasurementValue':

Home

Documentation
www.exept.de
Everywhere
for:
[back]

Class: MeasurementValue


Inheritance:

   Object
   |
   +--Magnitude
      |
      +--ArithmeticValue
         |
         +--MeasurementValue

Package:
stx:libbasic
Category:
Magnitude-Numbers
Version:
rev: 1.38 date: 2023/06/11 14:54:01
user: cg
file: MeasurementValue.st directory: libbasic
module: stx stc-classLibrary: libbasic

Description:


A MeasurementValue is a numeric value with an error, such as returned
by measurement devices (Volt-Meter). For example, if a measurement-device has
an error of 10%, a measured value of 20 could be any value between 18 and 22.

Arithmetic operations keep track of the error; if any operand is a MeasurementValue,
the operation returns a MeasurementValue as result.

This class is possibly unfinished and needs more arithmetic methods.
For now, the stuff found here represents our needs and more might be added in the future.

Also notice, that instances do not keep the error as a fraction, but instead a min. and maxValue.
That means, that we can handle the case where the error is different in
the positive and negative directions.
I am not sure if this is more flexibility than needed in the long run.

copyright

COPYRIGHT (c) 2007 by eXept Software AG All Rights Reserved This software is furnished under a license and may be used only in accordance with the terms of that license and with the inclusion of the above copyright notice. This software may not be provided or otherwise made available to, or used by, any other person. No title to or ownership of the software is hereby transferred.

Class protocol:

coercing & converting
o  coerce: aNumber
convert the argument aNumber into an instance of the receiver's class and return it.

instance creation
o  value: valueArg absoluteError: absoluteError
return a new measurementValue with a given value and an error absolute

Usage example(s):

     10 with an error of 20%:
        MeasurementValue value:10 absoluteError:2    -> (10 ± 2)
        MeasurementValue value:10 error:(20 / 100)   -> (10 ± 2)
        MeasurementValue value:10 error:(20 percent) -> (10 ± 2)

     pi within 1%:
        MeasurementValue value:(Float pi) error:1e-2 -> (3.14159265358979 ± 0.0314159265358978) 
     pi within +/- 1e-3:
        MeasurementValue value:(Float pi) absoluteError:1e-3  

o  value: valueArg error: errorArg
return a new measurementValue with a given value and an error (fraction)

Usage example(s):

     10 with an error of 20%:
        MeasurementValue value:10 error:0.2 
     pi within 1%:
        MeasurementValue value:(Float pi) error:1e-1 

o  value: valueArg relativeError: errorFraction
return a new measurementValue with a given value and an error (fraction)

Usage example(s):

     10 with an error of 20%:
        MeasurementValue value:10 error:0.2 
     pi within 1%:
        MeasurementValue value:(Float pi) error:1e-1 


Instance protocol:

accessing
o  absoluteError
the absolute error

Usage example(s):

     (100 +/- 10) relativeError    => (1/10)
     (100 +/- 10) absoluteError    => 10

     (1000 +/- 10) relativeError   => (1/100)
     (1000 +/- 10) absoluteError   => 10

o  maxValue
the maximum possible value, considerung what has been measured and what the measurement error is

o  minValue
the minimum possible value, considerung what has been measured and what the measurement error is

o  relativeError
the relative error as a fraction (i.e. 0.05 for a 5% error)

Usage example(s):

     (100 +/- 10) relativeError    => (1/10)
     (100 +/- 10) absoluteError    => 10

     (1000 +/- 10) relativeError   => (1/100)
     (1000 +/- 10) absoluteError   => 10

o  value
the measured value

arithmetic
o  * aNumber
return the product of the receiver and the argument.
Care for the error to propagate into the result.

Usage example(s):

     (MeasurementValue value:10 error:0.2) * (MeasurementValue value:10 error:0.2) 

     (MeasurementValue value:10 error:0.2) * 2    -> (20 ± 4)
     2 * (MeasurementValue value:10 error:0.2)    -> (20 ± 4)

     (MeasurementValue value:10 error:0.2) * 2 meter -> (20 ± 4) m
     2 meter * (MeasurementValue value:10 error:0.2) -> (20 ± 4) m

     (MeasurementValue value:10 error:0.2) meter     -> (10 ± 2) m

o  + aNumber
return the sum of the receiver and the argument.
Care for the error to propagate into the result.

Usage example(s):

     (MeasurementValue value:-10 error:0.2) + 2 (-8 ± -2) 
     2 + (MeasurementValue value:-10 error:0.2) (-8 ± -2) 

     (MeasurementValue value:-10 error:0.2) + (MeasurementValue value:-10 error:0.2) 
              (-20 ± -4)

o  - aNumber
return the difference of the receiver and the argument.
Care for the error to propagate into the result.

Usage example(s):

     (MeasurementValue value:-10 error:0.2) - (MeasurementValue value:-10 error:0.2) 
     (MeasurementValue value:-10 error:0.2) - 10                                     
     (MeasurementValue value:10 error:0.2) - 10                                     

o  / aNumber
return the quotient of the receiver and the argument.
Care for the error to propagate into the result.

Usage example(s):

     (10 +/- 2) / 2   

Usage example(s):

Modified (comment): / 21-11-2020 / 10:32:58 / cg

o  abs
(-10 ± 2) abs -> (10 ± 2)
(-10 ± 2) negated -> (10 ± 2)
0 - (-10 ± 2) -> (10 ± 2)
-1 * (-10 ± 2) -> (10 ± 2)
(-10 ± 2) * -1 -> (10 ± 2)

(10 ± 2) volt -> (10 ± 2) V

coercing & converting
o  +-% moreRelativeError
add an additional relative error to this MeasurementValue;
Use this if a measured value with some error
is further processed and another relative error gets added to it.
Q: I think, this is not correct; can someone help here

Usage example(s):

     (100.0 +-% 1)            -> (100.0 ± 1)
     (100.0 +-% 1) +-% 1      -> (100.0 ± 2)
     (100.0 +-% 1) +-% 2      -> (100.0 ± 3)
     (100.0 +-% 1) +-% 10     -> (100.0 ± 11.0)

o  +/- moreAbsoluteError
add an additional absolute error to this MeasurementValue.
Use this if a measured value with some error
is further processed and another absolute error gets added to it.
Q: I think, this is not correct; can someone help here

Usage example(s):

     (10 +/- 1)         (10 ± 1)
     (10 +/- 1) +/- 2   (10 ± 3)
     (150 +/- 5) +/- 2  (150 ± 7)
     (150 +-% 5) +-% 2  (150 ± (21/2))

o  coerce: aNumber
convert the argument aNumber into an instance of the receiver's class and return it.

o  generality
return the generality value - see ArithmeticValue>>retry:coercing:

Usage example(s):

adding 1 to the value's generality has the subtle side effect of enforcing 

o  ± error
add an additional absolute error to this MeasurementValue

o  ±% errorPercentage
add an additional relative error to this MeasurementValue

comparing
o  < aNumber
return true, if the receiver's value is less than aNumber.
Does NOT care for the error, but compares the central measurement value.
- i.e. you should probably compare against minValue/maxValue.

Usage example(s):

     (100 ± 10) < 50  -> false 
     (100 ± 10) < 100  -> false 
     (100 ± 10) < 110  -> true  (although it is in the range)

o  <= aNumber
return true, if the receiver's value is less or equal to aNumber.
Does NOT care for the error, but compares the central measurement value.
- i.e. you should probably compare against minValue/maxValue.

Usage example(s):

     (100 ± 10) <= 50  -> false 
     (100 ± 10) <= 80  -> false 
     (100 ± 10) <= 90  -> false 
     (100 ± 10) <= 100  -> true 
     (100 ± 10) <= 110  -> true  -- although it is in the range

o  = aNumberOrMeasuredValue
hard to tell, what we want here...
Here, we return true if my error is zero
i.e. the value is absolute correct.
How about: aNumber between:minValue and:maxValue ???

o  > aNumber
return true, if the receiver's value is greater than aNumber.
Does NOT care for the error, but compares the central measurement value.
- i.e. you should probably compare against minValue/maxValue.

Usage example(s):

     (100 ± 10) > 80  -> true 
     (100 ± 10) > 100  -> false  - although it is in the range 
     (100 ± 10) > 110  -> false 

o  >= aNumber
return true, if the receiver's value is greater or equal to aNumber.
Does NOT care for the error, but compares the central measurement value.
- i.e. you should probably compare against minValue/maxValue.

Usage example(s):

     (100 ± 10) >= 90  -> true   although it is in range
     (100 ± 10) >= 100  -> true 
     (100 ± 10) >= 130  -> false 

o  between: min and: max
return true, if the receiver's value in [min..max].
Does NOT care for the error, but compares the central measurement value.
- i.e. you should probably compare against minValue/maxValue.

Usage example(s):

     (100 ± 10) between:90 and:95   -> false
     (100 ± 10) between:95 and:105  -> true 
     (100 ± 10) between:90 and:110  -> true 
     (100 ± 10) between:111 and:200 -> false 
     (100 ± 10) between:50 and:150  -> true 

o  hash
(comment from inherited method)
instances, for which #= answers true must answer the same hash

o  isAlmostEqualTo: aMagnitude nEpsilon: nEpsilon

o  lessFromFloat: aFloat
aFloat < self ?

o  lessFromInteger: anInteger
anInteger < self ?

double dispatching
o  differenceFromMeasurementValue: aMeasurementValue
return the difference of aMeasurementValue and the receiver.
Care for the error to propagate into the result.

o  differenceFromNumber: aNumber
aFloat - self

o  isAlmostEqualToFromMeasurementValue: aMeasurementValue nEpsilon: nEpsilon
mhmh: what is this?

o  productFromMeasurementValue: aMeasurementValue
return the product of aMeasurementValue and the receiver.
Care for the error to propagate into the result.

o  productFromNumber: aNumber
aNumber * self

o  productFromPhysicalValue: physicalValue
10 meter * (5 ± 1) (50 ± 10) m
(5 ± 1) * 10 meter (50 m ± 10 m)
(10 ± 2) meter (10 ± 2) m
(10 ± 2) meter * (10 ± 2) meter

o  quotientFromMeasurementValue: aMeasurementValue
return the quotient of aMeasurementValue and the receiver.
Care for the error to propagate into the result.

o  quotientFromNumber: aNumber
aNumber / self

o  quotientFromPhysicalValue: aPhysicalValue
physicalValue / self

o  sumFromMeasurementValue: aMeasurementValue
return the sum of aMeasurementValue and the receiver.
Care for the error to propagate into the result.

o  sumFromNumber: aNumber
aNumber * self

printing & storing
o  printOn: aStream
deltaMax storeOn:aStream

Usage example(s):

value printOn:aStream.

Usage example(s):

"/ value printOn:aStream.

private accessing
o  value: valueArg absoluteError: error
setup the receiver, given a measurement value and an absolute error

Usage example(s):

     MeasurementValue value:200 absoluteError:10  => (200 ± 10)
     MeasurementValue value:200 absoluteError:5   => (200 ± 5)

o  value: valueArg error: errorFraction
setup the receiver, given a measurement value and a relative error +/- fraction

o  value: valueArg relativeError: relativeError
setup the receiver, given a measurement value and a relative error +/- fraction

Usage example(s):

     MeasurementValue value:200 relativeError:0.1  => (200 ± 20)
     MeasurementValue value:200 relativeError:0.05 => (200 ± 10)

queries
o  error
marked as obsolete by exept MBP at 11-05-2023

** This is an obsolete interface - do not use it (it may vanish in future versions) **

truncation & rounding
o  roundedToScale: scale
return a new measurement value with scaled values

o  truncatedToScale: scale
return a new measurement value with scaled values


Examples:


Instance creation message in number:
  (10 +/- 1)
arithmetic; notice, how the errors accumulate:
   (100 +/- 5) * 2
   (100 +/- 5) * (100 +/- 10)
   (100 +/- 5) + (100 +/- 10)
   (100 +/- 5) - (100 +/- 10)
again see, how the errors accumulate...
  |voltage current power|

  voltage := MeasurementValue value:10 error:0.05.
  current := MeasurementValue value:2 error:0.1.
  power := voltage * current.
  power.                   
  power minValue.
  power maxValue.
  |voltage current power|

  voltage := MeasurementValue value:10 error:0.05.
  current := 2.
  power := voltage * current.
  power
  |voltage doubleVoltage|

  voltage := MeasurementValue value:10 error:0.1.
  doubleVoltage := 2 * voltage.
  doubleVoltage


ST/X 7.7.0.0; WebServer 1.702 at 20f6060372b9.unknown:8081; Mon, 14 Oct 2024 01:53:15 GMT