# Difference between revisions of "PhysicalValues/en"

Line 1: | Line 1: | ||

Starting with version 19.2, |
Starting with version 19.2, |
||

− | expecco |
+ | 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 |
+ | 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.

## Contents

- 1 Base Units
- 2 Derived Units
- 3 SI Prefix
- 4 Unit API
- 5 Defining Additional Unit Converters
- 6 Arithmetic
- 7 Formula Evaluation
- 8 Nature Constants
- 9 Equation Solving
- 10 Physical Values in Activity Diagrams
- 11 Examples

## 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'