Difference between revisions of "PhysicalValues/en"

From expecco Wiki (Version 2.x)
Jump to navigation Jump to search
 
Line 1: Line 1:
 
Starting with version 19.2,
 
Starting with version 19.2,
expecco will support values with units to represent physical values such as length, acceleration, area, volume, mass, temperature, electric current etc.
+
expecco supports values with Units, to represent physical values such as length, acceleration, area, volume, mass, temperature, electric current etc.
   
 
Physical values are useful for a nicer presentation of measurement values (eg. in a report) and to convert between unit systems (eg. metric vs. imperial vs. US).
 
Physical values are useful for a nicer presentation of measurement values (eg. in a report) and to convert between unit systems (eg. metric vs. imperial vs. US).
   
Physical values are implemented by the underlying Smalltalk system and can be used in JavaScript and Smalltalk elementary blocks. Similar public domain packages are available for Node and Python actions - these have to be installed with "npm"or "pip".<br>There are currently no plans to support exchange of physical value objects transparently with Python, Node or Java actions. If required, these should be passed as { amount: unit: } objects and converted in the bridge as required.
+
Physical values are implemented by the underlying Smalltalk system and can be used both in Smalltalk and in JavaScript elementary blocks. Similar public domain packages are available for Node and Python actions - these have to be installed with "npm"or "pip".<br>There are currently no plans to support exchange of physical value objects transparently with Python, Node or Java actions. If required, these should be passed as { amount: unit: } objects and converted in the bridge as required.
   
 
The following document describes the programmer's API for elementary Smalltalk and JavaScript actions.
 
The following document describes the programmer's API for elementary Smalltalk and JavaScript actions.
Line 298: Line 298:
   
 
*''number'' '''newton''' <br>Generates a force-value of n newton.
 
*''number'' '''newton''' <br>Generates a force-value of n newton.
  +
  +
==== Unit Converting ====
  +
  +
*''force'' '''asGramForce''' <br>Presents itself as gf
  +
  +
*''force'' '''asPoundsForce''' <br>Presents itself as lbf
   
 
=== Area ===
 
=== Area ===
Line 508: Line 514:
 
equation solveFor:'b' -> 'b = (a - c) / 5'.
 
equation solveFor:'b' -> 'b = (a - c) / 5'.
   
  +
For example, from the wellknown Formula "U = R * I",
  +
equation := Physics::Parser parse:'U = R * I".
  +
we can derive:
  +
equation2 := equation solveFor:'R'.
  +
and get "R = U/I".<br>Of which the right side:
  +
formulaForR := equation2 rightSide
  +
is:
  +
U/I
  +
  +
Applying this formulaForR to concrete values:
  +
formulaForR valueIn:{ 'U' -> 5 volt . 'I' -> 20 milliAmpere }
  +
we get the result:
  +
250 Ω
  +
  +
  +
 
== Physical Values in Activity Diagrams ==
 
== Physical Values in Activity Diagrams ==
   

Latest revision as of 14:33, 11 February 2020

Starting with version 19.2, expecco supports values with Units, to represent physical values such as length, acceleration, area, volume, mass, temperature, electric current etc.

Physical values are useful for a nicer presentation of measurement values (eg. in a report) and to convert between unit systems (eg. metric vs. imperial vs. US).

Physical values are implemented by the underlying Smalltalk system and can be used both in Smalltalk and in JavaScript elementary blocks. Similar public domain packages are available for Node and Python actions - these have to be installed with "npm"or "pip".
There are currently no plans to support exchange of physical value objects transparently with Python, Node or Java actions. If required, these should be passed as { amount: unit: } objects and converted in the bridge as required.

The following document describes the programmer's API for elementary Smalltalk and JavaScript actions.

Base Units[edit]

All base units are measured in their corresponding SI standard units and print with an appropriate scaling prefix.

For example, a mass, which has a base unit of kilogram ("kg") will print itself as "kg', 'mg', 'µg' etc. depending on its magnitude. Explicit converters can be used to enforce a particular unit printing (eg. if you insist on printing a mass in pounds, in grams, etc.). See examples below on how those converters affect the printout of a value.

Base units are:

s	second	    time
m	metre	    length
kg	kilogram    mass
A	ampere	    electric current
K	kelvin	    temperature
mol	mole	    amount of substance
cd	candela	    luminous intensity

Derived Units[edit]

Additional derived units are:

V      volt                voltage
Hz     hertz               frequency
m/s    meter per second    speed, velocity
m/s²   m/s per second      acceleration
m²     square meter        area
m³     cubic meter         volume
pa     pascal              pressure
w      watt                power
N      newton              force
J      joule               energy
Ω      ohm                 electric resistance
C      coulomb             electric charge
F      farad               electric capacitance

SI Prefix[edit]

Numbers (in Smalltalk and JavaScript) can be scaled by an SI prefix message. For example, without si prefix:

1 gram -> '1 g'

whereas with a 'micro' prefix:

1 micro gram -> '1 µg'

and:

1 hecto liter -> '100 liter'

The corresponding JavaScript code is similar, but slightly less elegant looking:

1.gram()
1.micro().gram()
1.hecto().liter()

Possible scaling prefixes are:

yocto   1E-24   1 / 1000000000000000000000000 
zepto   1E-21   1 / 1000000000000000000000 
atto    1E-18   1 / 1000000000000000000
femto   1E-15   1 / 1000000000000000
pico    1E-12   1 / 1000000000000
nano    1E-9    1 / 1000000000
micro   1E-6    1 / 1000000
milli   1E-3    1 / 1000
centi   1E-2    1 / 100
deci    1E-1    1 / 10
deca    1E+1    10
hecto   1E+2    100
kilo    1E+3    1000
mega    1E+6    1000000
giga    1E+9    1000000000
tera    1E+12   1000000000000
peta    1E+15   1000000000000000
exa     1E+18   1000000000000000000
zetta   1E+21   1000000000000000000000
yotta   1E+24   1000000000000000000000000

Unit API[edit]

PhysicalValue instances can be created by sending the "amount:" message to a Unit.
For example:

Physic::PhysicalUnit energy amount:100

generates an energy instance of 100 joule.

Notice, that the "energy" message is a facade getter method of Physic::PhysicalUnit (i.e. the class named "PhysicalUnit" in the "Physic" namespace). It retrieves the Energy class, which is actually named "Physic::Energy" and is also located in the Physic namespace. Getters for well known unit classes are:

Physic::PhysicalUnit energy
Physic::PhysicalUnit acceleration
Physic::PhysicalUnit amountOfSubstance
Physic::PhysicalUnit area
Physic::PhysicalUnit currentDensity
Physic::PhysicalUnit electricCapacitance
Physic::PhysicalUnit electricCharge
Physic::PhysicalUnit electricConductance
Physic::PhysicalUnit electricCurrent
Physic::PhysicalUnit electricResistance
Physic::PhysicalUnit energy
Physic::PhysicalUnit force
Physic::PhysicalUnit frequency
Physic::PhysicalUnit length
Physic::PhysicalUnit luminousIntensity
Physic::PhysicalUnit mass
Physic::PhysicalUnit massDensity
Physic::PhysicalUnit power
Physic::PhysicalUnit pressure
Physic::PhysicalUnit specificVolume
Physic::PhysicalUnit temperature
Physic::PhysicalUnit time
Physic::PhysicalUnit velocity
Physic::PhysicalUnit voltage
Physic::PhysicalUnit volume
 
Physic::PhysicalUnit knownUnits

For the most common units, additional instance creation protocol is provided in the Number class (eg. "100 joules" will generate the same as "Physic::PhysicalUnit energy amount:100"). The additional protocol is described below.

When printed, physical values will scale and use an SI prefix as appropriate. Thus, by default, a value of 100 millimeter will print as "100 mm" instead of "0.1 m".

This print behavior can be changed by converting to an explicit unit via one of the "asXXX" messages listed below. However, the SI unit amount will be kept internally and used in arithmetic operations. Thus, eg. when adding a meter with inches, an SI meter value will be generated, and the result will be presented in the same unit as the receiver (first operand).
For example, "1 meter + 1 inch asInches" will print as meter, whereas "1 inch asInches + 1 meter" will print as inches.

Mass[edit]

Mass is measured in units of kilogram. The following operations return an instance of a mass (i.e. a value with a unit of "Mass"):

  • number kiloGram
    Generates a mass-value of n kilograms. Same as n kilo gram.
  • number gram
    Generates a mass-value of n grams.
  • number milliGram
    Generates a mass-value of n milligrams. Same as n milli gram.
  • number microGram
    Generates a mass-value of n micrograms. Same as n micro gram.
  • number pounds
    Generates a mass-value of n pounds. A pound is defined as 453.59237 gram.

Unit Conversion[edit]

  • aMass asGrams
    Returns the original mass but enforces explicit printing in grams (i.e. without any SI scaling prefix).
  • aMass asNanoGrams
    Enforces explicit printing in nanograms ("ng").
  • aMass asMicroGrams
    Enforces explicit printing in micrograms ("µg").
  • aMass asMilliGrams
    Enforces explicit printing in milligrams ("mg").
  • aMass asKiloGrams
    Enforces explicit printing in kilograms ("kg").
  • aMass asTonnes
    Enforces explicit printing in (metric) tonnes ("t").
  • aMass asKiloTonnes
    Enforces explicit printing in (metric) kilotonnes ("kt").
  • aMass asMegaTonnes
    Enforces explicit printing in (metric) megatonnes ("Mt").
  • aMass asPounds
    Enforces explicit printing in pounds ("lb").

Length[edit]

Length is measured in meters.

  • number meter
    Generates a length-value of n meters.
  • number centiMeter
    Generates a length-value of n centimeters. Same as n centi meter.
  • number milliMeter
    Generates a length-value of n millimeters. Same as n milli meter.
  • number microMeter
    Generates a length-value of n micrometers. Same as n micro meter.
  • number nanoMeter
    Generates a length-value of n nanometers. Same as n nano meter.
  • number kiloMeter
    Generates a length-value of n kilometers. Same as n kilo meter.
  • number inch
    Generates a length-value of n inches. An inch is 25.4 mm.
  • number feet
    Generates a length-value of n feet. A foot is 0.3048 m.
  • number landMiles
    Generates a length-value of n landMiles. A landMile is 5280 feet or 1609.344 m.
  • number nauticalMiles
    Generates a length-value of n nauticalMiles. A nauticalMile is 1852 m.
  • number astronomicalUnits
    Generates a length-value of n astronomical units. An au is 149597870.7 km.
  • number lightSeconds
    Generates a length-value of n lightseconds. An ls is 299792.458 km.
  • number lightYears
    Generates a length-value of n lightyears. An ly is 9460730472580.8 km.
  • number angstrom
    Generates a length-value of n angstroms. 1 Å = 0,1 = 10E−10 m.

Unit Conversion[edit]

  • aLength asMeters
    Returns the original length but enforces explicit printing in meters (i.e. prevents scaling prefix when printed).
  • aLength asMilliMeters
    Enforces explicit printing in millimeters ("mm").
  • aLength asMicroMeters
    Enforces explicit printing in micrometers ("µm").
  • aLength asNanoMeters
    Enforces explicit printing in nanometers ("nm").
  • aLength asKiloMeters
    Enforces explicit printing in kilometers ("km").
  • aLength asInches
    Enforces explicit printing in inches ("in").
  • aLength asFeet
    Enforces explicit printing in feet ("ft").
  • aLength asYards
    Enforces explicit printing in yards ("yd").
  • aLength asFeetAndInches
    Enforces explicit printing in feet and inches (inches rounded to 4 digits).
  • aLength asLightYears
    Enforces explicit printing in lightyears ("ly").

Temperature[edit]

  • number kelvin
    Generates an temperature-value of n Kelvin.
  • number degreesCelcius
    Generates an temperature-value of n degrees Celsius.
  • number degreesFahrenheit
    Generates an temperature-value of n degrees Fahrenheit.
  • number rankine
    Generates an temperature-value of n degrees Rankine.

Unit Conversion[edit]

  • aTemperature asFahrenheit
    Returns the original temperature but enforces explicit printing in Fahrenheit.
  • aTemperature asCelsius
    Enforces explicit printing in degrees celsius.

Frequency[edit]

  • number hertz
    Generates an frequency-value of n hertz.
  • number kiloHertz
    Generates an frequency-value of n kilohertz. Same as n kilo hertz.
  • number megaHertz
    Generates an frequency-value of n megahertz. Same as n mega hertz.
  • number gigaHertz
    Generates an frequency-value of n gigahertz. Same as n giga hertz.

Unit Conversion[edit]

  • aFrequency asKiloHertz
    Returns the original frequency but enforces explicit printing in kilohertz ("kHz").
  • aFrequency asMegaHertz
    Enforces explicit printing in megahertz ("mHz").
  • aFrequency asGigaHertz
    Enforces explicit printing in gigahertz ("gHz").

Energy[edit]

  • number joule
    Generates an energy-value of n joule.
  • number kiloJoule
    Generates an energy-value of n kilojoule. Same as n kilo joule .
  • number megaJoule
    Generates an energy-value of n megajoule. Same as n mega joule .
  • number wattHours
    Generates an energy-value of n wattHours. Same as n watt * 1 hours.
  • number kiloWattHours
    Generates an energy-value of n kiloWattHours. Same as n kilo wattHours and also the same as n kilo watt * 1 hours.
  • number megaWattHours
    Generates an energy-value of n megaWattHours. Same as n mega wattHours and also the same as n mega watt * 1 hours.
  • number electronVolts
    Generates an energy-value of n electronVolts.
  • number btu
    Generates an energy-value of n BTUs (british thermal units).
  • number calories
    Generates an energy-value of n calories.
  • number kiloCalories
    Generates an energy-value of n kcal.

Unit Converting[edit]

  • energy asElectronVolts
    Present as electronVolts ("eV")
  • energy asKiloWattHours
    Present as kiloWattHours ("kWh")
  • energy asMegaWattHours
    Present as megaWattHours ("mWh")
  • energy asGigaWattHours
    Present as gigaWattHours ("gWh")
  • energy asBTUs
    Present as BTUs (British Thermal Units)
  • energy asCalories
    Present as calories ("cal")
  • energy asKiloCalories
    Present as kilo calories ("kcal")

Power[edit]

  • number watt
    Generates a power-value of n watt.
  • number kiloWatt
    Generates a power-value of n kiloWatt. Same as n kilo watt .
  • number megaWatt
    Generates a power-value of n megaWatt. Same as n mega watt .
  • number gigaWatt
    Generates a power-value of n gigaWatt. Same as n giga watt .

Unit Converting[edit]

  • power asKiloWatt
    Presents itself as kW
  • power asMegaWatt
    Presents itself as mW
  • area asGigaWatt
    Presents itself as gW

Force[edit]

  • number newton
    Generates a force-value of n newton.

Unit Converting[edit]

  • force asGramForce
    Presents itself as gf
  • force asPoundsForce
    Presents itself as lbf

Area[edit]

  • number squareMeter
    Generates an area-value of n square meters.
  • number hectare
    Generates an area-value of n hectares. Same as n hecto are .
  • number are
    Generates an area-value of n ares. 1 are being 10 m².
  • number squareFeet
    Generates an area-value of n square feet. 1 sq ft being 0.0929 m².
  • number acres
    Generates an area-value of n acres. 1 acre being 4046.856 m².

Converting[edit]

  • area asSquareFeet
    Presents itself as square feet ("m²")
  • area asHectare
    Presents itself as hectare ("ha")
  • area asAcres
    Presents itself as acres ("ac")

Volume[edit]

  • number cubicMeter
    Generates an volume-value of n cubic meters (1000 l).
  • number liter
    Generates an volume-value of n liters.
  • number milliLiter
    Generates a volume-value of n milliliters. Same as n milli liter.
  • number hectoLiter
    Generates a volume-value of n hectoliters. Same as n hecto liter.
  • number barrel
    Generates a volume of n barrels (oil volume measurement).
  • number flozGB
    Generates a volume of n imperial fluid ounces (0.02841 liter).
  • number flozUS
    Generates a volume of n US fluid ounces (0.02957 liter).
  • number pintGB
    Generates a volume of n imperial pints (568.26125 ml).
  • number pintUS
    Generates a volume of n US pints (473.176473 ml).
  • number quartGB
    Generates a volume of n imperial quarts (1.1365 liter).
  • number quartUS
    Generates a volume of n US quarts (946.353 ml).
  • number gallonGB
    Generates a volume of n imperial gallons (4.5461 liter).
  • number gallonUS
    Generates a volume of n US gallons (3.7854 liter).

Converting[edit]

  • volume asCubicMeters
    Presents itself as cubic meters ("mˆ3")
  • volume asFlozGB
    Presents itself as imperial fluid ounces ("imp fl oz")
  • volume asFlozUS
    Presents itself as US fluid ounces ("us fl oz")
  • volume asGallonsGB
    Presents itself as imperial gallons ("imp ga")
  • volume asGallonsUS
    Presents itself as US gallons ("us ga")
  • volume asHectoLiters
    Presents itself as hectoliters ("hl")
  • volume asMilliLiters
    Presents itself as milliliters ("ml")

Velocity (Speed)[edit]

  • number meterPerSecond
    Generates a velocity of n meters per second.
  • number kiloMeterPerHour
    Generates a velocity of n km per hour.
  • number milesPerHour
    Generates a velocity of n mph.
  • number knots
    Generates a velocity of n nautical miles per hour.

Converting[edit]

  • volume asKiloMetersPerHour
    Presents itself as km/h
  • volume asMilesPerHour
    Presents itself as mph

Acceleration[edit]

  • number metersPerSecondPerSecond
    Generates an acceleration of n m/s².

Pressure[edit]

  • number pascal
    Generates a pressure value of n pascal.
  • number hectoPascal
    Generates a pressure value of n hectoPascal.

Voltage[edit]

  • number volts
    Generates an electrical voltage of n volts.
  • number milliVolt
    Generates a voltage of n millivolt.
  • number microVolt
    Generates an voltage of n microvolt.
  • number kiloVolt
    Generates an voltage of n kilovolt.

Electric Current[edit]

  • number ampere
    Generates an electric current of n ampere.
  • number milliAmpere
    Generates an electric current of n milliampere.
  • number microAmpere
    Generates an electric current of n microampere.

Electric Resistance[edit]

  • number ohm
    Generates an electric resistance of n ohm.
  • number kiloOhm
    Generates an electric current of n kiloOhm.
  • number megaOhm
    Generates an electric current of n megaOhm.

Electric Capacitance[edit]

  • number farad
    Generates an electric capacitance of n farad.
  • number microFarad
    Generates an electric capacitance of n microfarad.
  • number nanoFarad
    Generates an electric capacitance of n nanofarad.
  • number picoFarad
    Generates an electric capacitance of n picofarad.

Electric Charge[edit]

  • number coulomb
    Generates an electric charge of n coulomb.

Defining Additional Unit Converters[edit]

You can define additional unit converters as ConvertedUnit as follows:

myUnit := Physic::ConvertedUnit 
            name:name 
            baseUnit:baseUnit 
            unitString:unitString 
            unitValueBlock:unitValueBlock

for example, to get volumes printed as cubic inches, define:

cI := Physic::ConvertedUnit
            name:'cubicInches'
            baseUnit:(Physic::Volume) 
            unitString:'in³' 
            unitValueBlock:[:cubicMeters | cubicMeters / 61023.7440947323]

(where 61023.7440947323 is the number of cubic inches per cubic meter, i.e. "1 cubicMeter / (1 inches raisedTo:3)")

Then create a new physical value for your volume with:

cI amount:volumeInCubicMeters

Arithmetic[edit]

Arithmetic on physical values will generate an appropriate physical value. Eg, when multiplying a velocity by a time, you will get a distance, or when dividing a distance by a time, you will get a velocity.

Acceleration[edit]

speed = acceleration * time

1 meterPerSecondPerSecond * 10 seconds -> 10 m/s  
(1 meterPerSecondPerSecond distanceAfter:1 hours) -> 6480.0 km
1 meterPerSecond / 10 seconds -> 0.1 m/s²

Mass[edit]

force = mass * acceleration

1 kg * 1 meterPerSecondPerSecond -> 1 N

Formula Evaluation[edit]

Mathematical formula can be parsed and further processed by use of the Physics::Parser class.

  • Physics::Parser parse: aString
    generates a parse tree for further processing
  • Physics::Parser evaluate: aString
    parses and evaluates

Generated parse trees can be further processed with:

  • aParseTree value
    evaluates the tree
  • aParseTree simplify
    simplifies the tree (if possible)
  • aParseTree derivate
    generates a derivate

Examples[edit]

Physics::Parser evaluate:'10 kg * 9.81 m/sˆ2' -> 
(Physics::Parser parse:'a*x^2 + b*x + c') derivate ->

Nature Constants[edit]

The following constants are known to the parser and can be used in formula/equations:

pi
e
mass[X], for X in {earth, moon, mercure, venus, mars, jupiter}
volume[X], for X in {earth, moon, mercure, venus, mars, jupiter} 
surface[X], for X in {earth, moon, mercure, venus, mars, jupiter} 
DISTANCE_SUN_EARTH
DISTANCE_EARTH_MOON

Equation Solving[edit]

The solver can solve simple equations:

equation := Physics::Parser parse:'a = 5*b + c".
equation solveFor:'b' -> 'b = (a - c) / 5'.

For example, from the wellknown Formula "U = R * I",

equation := Physics::Parser parse:'U = R * I".

we can derive:

equation2 := equation solveFor:'R'.

and get "R = U/I".
Of which the right side:

formulaForR := equation2 rightSide 

is:

U/I

Applying this formulaForR to concrete values:

formulaForR valueIn:{ 'U' -> 5 volt . 'I' -> 20 milliAmpere }

we get the result:

250 Ω   


Physical Values in Activity Diagrams[edit]

Unfortunately, the arithmetic actions in the standard library where defined with pin types being "Number", instead of the more general "ArithmeticValue" (of which PhysicalValues inherit). Thus, they will not accept physical values if type checking is enabled on the pin values (although the underlying primitive code would handle those types).

We therefore provide a separate PhysicalValues library, with redefined arithmetic actions. Please use those when dealing with physical values (instead of "forcing" types or disabling type checks).

Freeze values can be given either using the above listed instance creation messages on number (eg. "10 meters" or "1 kilo joule") or by using a unit suffix, possibly with an appreciated SI prefix, as in "10 kV" or "10 mA".

Examples[edit]

Smalltalk code + printed representation.
For JavaScript, write "n.X()" instead of "n X" (eg. "1.kilogram() + 10.0.gram()" instead of "1 kiloGram + 10.0 gram".

1 kiloGram + 10.0 gram -> '1.01 kg' 
10 gram -> '10 g'
10 gram asKiloGrams -> '0.01 kg'
10 gram asMilliGrams -> '10000 mg'
1 microGram -> '1 µg'
1 micro gram -> '1 µg'
1 pound -> '453.59237 g'
1 pound asKiloGrams -> '0.45359237 kg'
1 pound asPounds -> '1.0 lb' 
1 kiloGram asPounds -> '2.20462262184878 lb'
10 kiloMeters asMeters -> '10000 m'
1 micro inch -> '25.4 nm'
1.80 meter asFeetAndInches -> '5′10.866″'
1 yards -> '0.9144 m'
0 degreesCelsius -> '273.16 K'
0 degreesCelsius asFahrenheit -> '32.018 °F'
40 degreesFahrenheit -> '277.59 K'
60 degreesFahrenheit asCelsius -> '15.556 °C'
40 degreesFahrenheit asKelvin -> '277.59 K'
10 kelvin -> '10 K'
100 rankine -> '55.556 K'
1 joule asElectronVolts -> '6.24150912550149E+18 eV'
10 electronVolts -> 1.6021766208E-18 J
1000 joule asKiloWattHours -> '0.000278 kWh'
1000.0 kiloJoule asKiloWattHours -> '0.2778 kWh'



Copyright © 2014-2018 eXept Software AG