Evaluation of physical quantities (values with units of measure) expressions
npm install maana-physical-quantity-astwithQuantities
javascript
const { withQuantities } = require('maana-physical-quantity-ast')
// a simple physical model for the velocity of an object falling under the influence of gravity.
const velocity = withQuantities( function( t ) {
const g = 9.8 * ( meter / second / second )
const v = ( tsecond ) g
return PQMath.convertTo( v, mile/hour )
})
console.log( velocity( 10 )) // log the velocity after 10 seconds of freefall.
`
The withQuantities environment imports by default the PQMath utility object which exposes
mathematic functions similar to the Math js object, as well as many customary units of measure,
and their prefixes. It is intended for use within the maana-lambda-service expressions to perform
well dimensioned computations with physical quantities.
Installation
You can install the latest version of this package from npm:
`bash
npm i maana-physical-quantities-ast
`
The
withQuantities Function
The with quantities function takes four arguments:
func* - the function that you wish to evaluate using physical quantities.
units* - an optional collection of unit of measure definitions. This collection can be used to extend
or replace the units of measure that are included by default. If you do not include this parameter, the
environment will include 36 customary units of measure. For details, of the default values see (https://github.com/maana-io/maana-physical-quantity-ast/blob/master/lib/dsl/constants/UnitConstants.js)
prefixes* - an optional collection of unit of measure prefix definitions. This collection can be used to
extend or replace the unit of measure prefixes that are included by default. If you do not include this parameter
the environment will include the SI unit of measure prefix definitions. For details of the default values, see (https://github.com/maana-io/maana-physical-quantity-ast/blob/master/lib/dsl/constants/PrefixConstants.js)
dims* - an optional collection of physical dimensions that are included by default. This collection can be used to
extend or replace the physical quantities that are included by default. If you do not include this parameter
the environment will include the 65 physical dimensions commonly found in literature. For details of the default values, see (https://github.com/maana-io/maana-physical-quantity-ast/blob/master/lib/dsl/constants/DimensionConstants.js)
For example, the following code snippet introduces a new unit of measure, a new prefix and a new physical quantity to the
environment:
`javascript
const { withQuantities } = require('maana-physical-quantity-ast')
const myUnits = [{
unit: { factors:[{
exponent:1,
base:{
id:"cubit",
dimension: withQuantities( function(){ return LENGTH })(),
siUnitConversion:{multiplier:0.4572, offset:0}}
}]}}]
const myPrefixes = [{
name: "MM",
prefix: { id: "MM", multiplier: 1E6 }
}]
const myDims = [{
name: "ENTROPY",
dimension: withQuantities( function(){ return ENERGY / TEMPERATURE })(),
}]
const foo = withQuantities( function() {
const MMcubit = MM * cubit
return 1 * ( MMcubit / day)
}, myUnits, myPrefixes, myDims)
`
Computations With Quantities
Any ES6 programming constructs are supported with physical quantities. This includes conditional flow (if..else, do..while),
for loops (for, for in, for of). For convenience, arithmetic operators have been overloaded to allow computations with
physical quantities, as well as mixed computations with physical quanties, units of measure and numeric literals.
PQMath
The PQMath object is a utility object that provides additional mathematical operations on physical quantites, and is imported into the quasiquoting environment by default. The following functions are provided:
* asin, acos, atan, asinh, acosh, atanh, asin, acos, atan, asinh, acosh, atanh - trigonometric functions on unitless physical quantities
* exp, log - exponential and logs of unitless physical quantities
* pow - integer powers of physical quantities
* sqrt, cbt - roots of physical quantities (provided that all the unit's fators are integer powers of the selected root)
* round, trunc, ceil, floor, precise - rounding functions on the physical quantity's magnitude
* canBeConvertedTo, convertTo - dimensionally safe unit of measure conversions
Converting Units
We use a model for units of measure that is self descriptive; Each unit knows what its physical dimension is, and how to convert to a standard unit of measure for that dimension. You can use the dimensionOf() method of any physical quantity or unit of measure to obtain the physical dimension. Likewise, you can use the standardUnitConversion() method to inspect the conversion factors:
`javascript
withQuantities( function() {
console.log(( pound / inch /inch ).dimensionOf() === PRESSURE ) // returns true
console.log(( pound / inch / inch).standardUnitConversion().multiplier) // returns 6894.7547895095795
}
`
We can use the PQMath.convertTo function to convert any physical quantity to a dimensionally consistent unit of measure.
For example:
`javascript
const { withQuantities } = require('maana-physical-quantity-ast')
withQuantities( function() {
const P = 14.7 * ( pound / inch /inch )
if ( PQMath.canBeConvertedTo( P, Pascal ) )
console.log( PQMath.convertTo(P,Pascal ).toString() )
// outputs 101352.89540579081 Pa
})()
`
Casting Types
The withQuantities environment also imports by default 130 type casting functions that can be used to convert between
JSON objects and physical quantities while ensuring the correct physical dimension. For example:
`
const { withQuantities } = require('maana-physical-quantity-ast')
withQuantities( function ( input ) {
const elapsedTime = toQuantity( input.elapsedTime, TIME )
const initialPosition = toQuantity( input.height, LENGTH )
const initialVelocity = toQuantity( input.initialVelocity, VELOCITY )
const distanceTraveled = initialVelocity*time - initialPosition
return fromQuantity( distanceTraveled, LENGTH )
})( input )
`
Parsing physical quantities
The withQuantities supports parsing of physical quantity string literals using the
parse funtion. For example:
`
const { withQuantities } = require('maana-physical-quantity-ast')
withQuantities( function ( input ) {
const elapsedTime = parse('10 s')
const initialPosition = parse('15 ft')
const initialVelocity = parse('1 ft/s)
const distanceTraveled = initialVelocity*time - initialPosition
return fromQuantity( distanceTraveled, LENGTH )
})( input )
``