Maana-physical-quantity-ast

The maana-physical-quantity-ast library is a javascript library for performing dimensionally consisistent
computations with physical-quantities ( measurements ). It exports a quasiquoting environment withQuantities
inside which the user can write standard javascript code containing arithmetic expressions containing
physical quantities. For example:

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

The above code uses the dimensionally safe physical quantity constructors to convert the given inputs to a time, a length and a velocity respecively. Prior to returning the final value, it ensures that the JSON object that is returned has a physical dimension of length. A complete list of the casting functions can be found here: https://github.com/maana-io/maana-physical-quantity-ast/blob/master/lib/dsl/Casts.js

Credits

The overloading of the type operators in this library was made possible by a fork of Kushal Likhi's operator-overloading package: https://github.com/kushal-likhi/operator-overloading-js. It has been extended to work with additional ES6 program flow structures and syntax.