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:

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 =  ( t*second ) * 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:

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:

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:

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:

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.