Smalltalk/X Webserver

Documentation of class 'MeasurementValue':

Class: MeasurementValue

Inheritance
Description
Class protocol
- coercing & converting
- instance creation
Instance protocol
Examples

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.

copyrightCOPYRIGHT (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

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

instance creation

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

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

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

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

maxValue

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

minValue

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

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

value

the measured value

arithmetic

* 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

+ 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)

- 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

/ 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

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

+-% 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)

+/- 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))

coerce: aNumber

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

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

± error

add an additional absolute error to this MeasurementValue

±% errorPercentage

add an additional relative error to this MeasurementValue

comparing

< 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)

<= 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

= 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 ???

> 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

>= 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

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

hash

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

isAlmostEqualTo: aMagnitude nEpsilon: nEpsilon

lessFromFloat: aFloat

aFloat < self ?

lessFromInteger: anInteger

anInteger < self ?

double dispatching

differenceFromMeasurementValue: aMeasurementValue: return the difference of aMeasurementValue and the receiver.
Care for the error to propagate into the result.
differenceFromNumber: aNumber: aFloat - self
isAlmostEqualToFromMeasurementValue: aMeasurementValue nEpsilon: nEpsilon: mhmh: what is this?
productFromMeasurementValue: aMeasurementValue: return the product of aMeasurementValue and the receiver.
Care for the error to propagate into the result.
productFromNumber: aNumber: aNumber * self
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
quotientFromMeasurementValue: aMeasurementValue: return the quotient of aMeasurementValue and the receiver.
Care for the error to propagate into the result.
quotientFromNumber: aNumber: aNumber / self
quotientFromPhysicalValue: aPhysicalValue: physicalValue / self
sumFromMeasurementValue: aMeasurementValue: return the sum of aMeasurementValue and the receiver.
Care for the error to propagate into the result.
sumFromNumber: aNumber: aNumber * self

printing & storing

printOn: aStream

deltaMax storeOn:aStream

Usage example(s):

value printOn:aStream.

Usage example(s):

"/ value printOn:aStream.

private accessing

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)

value: valueArg error: errorFraction

setup the receiver, given a measurement value and a relative error +/- fraction

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

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

roundedToScale: scale: return a new measurement value with scaled values
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; Sat, 21 Dec 2024 14:02:26 GMT