typelevel / squants

Squants **The Scala API for Quantities, Units of Measure and Dimensional Analysis** Squants is a framework of data types and a domain specific language (DSL) for representing Quantities, their Units of Measure, and their Dimensional relationships. The API supports typesafe dimensional analysis, improved domain models and more. All types are immutable and thread-safe. GitHub | Wiki | | | Current Versions Current Release: **1.6.0** (API Docs) Development Build: **1.7.0-SNAPSHOT** (API Docs) Release History Build services provided by Travis CI NOTE - This README reflects the feature set in the branch it can be found. For more information on feature availability of a specific version see the Release History or the README for a that version Installation Repository hosting for Squants is provided by Sonatype. To use Squants in your SBT project add the following dependency to your build. "org.typelevel" %% "squants" % "1.6.0" or "org.typelevel" %% "squants" % "1.7.0-SNAPSHOT" To use Squants in your Maven project add the following dependency Beginning with Squants 0.4.x series, both Scala 2.10 and 2.11 builds are available. Beginning with Squants 1.x series, Scala 2.11, 2.12 and 2.13 builds are available. Scala.js is supported on version 0.6.31 and 1.0.0-RC1 To use Squants interactively in the Scala REPL, clone the git repo and run git clone https://github.com/typelevel/squants cd squants sbt squantsJVM/console Third-party integrations This is an incomplete list of third-party libraries that support squants: • PureConfig • Ciris If your library isn't listed here, please open a PR to add it! Type Safe Dimensional Analysis *The Trouble with Doubles* When building programs that perform dimensional analysis, developers are quick to declare quantities using a basic numeric type, usually Double. While this may be satisfactory in some situations, it can often lead to semantic and other logic issues. For example, when using a Double to describe quantities of Energy (kWh) and Power (kW), it is possible to compile a program that adds these two values together. This is not appropriate as kW and kWh measure quantities of two different dimensions. The unit kWh is used to measure an amount of Energy used or produced. The unit kW is used to measure Power/Load, the rate at which Energy is being used or produced, that is, Power is the first time derivative of Energy. *Power = Energy / Time* Consider the following code: This example not only adds quantities of different dimensions (Power vs Energy), it also fails to convert the scales implied in the val names (Mega vs Kilo). Because this code compiles, detection of these errors is pushed further into the development cycle. Dimensional Type Safety _Only quantities with the same dimensions may be compared, equated, added, or subtracted._ Squants helps prevent errors like these by type checking operations at compile time and automatically applying scale and type conversions at run-time. For example: The above sample works because Kilowatts and Megawatts are both units of Power. Only the scale is different and the library applies an appropriate conversion. Also, notice that keeping track of the scale within the value name is no longer needed: Invalid operations, like adding power and energy, no longer compile: By using stronger types, we catch the error earlier in the development cycle, preventing the error made when using Double in the example above. Dimensionally Correct Type Conversions _One may take quantities with different dimensions, and multiply or divide them._ Dimensionally correct type conversions are a key feature of Squants. Conversions are implemented by defining relationships between Quantity types using the and operators. Code samples in this section assume these imports: The following code demonstrates creating ratio between two quantities of the same dimension, resulting in a dimensionless value: This code demonstrates use of the method that takes a and returns an : This code demonstrates use of the method that takes a and returns a : Unit Conversions Code samples in this section assume these imports: Quantity values are based in the units used to create them. Since Squants properly equates values of a like dimension, regardless of the unit, there is usually no reason to explicitly convert from one to the other. This is especially true if the user code is primarily performing dimensional analysis. However, there are times when you may need to set a Quantity value to a specific unit (eg, for proper JSON encoding). When necessary, a quantity can be converted to another unit using the method. Sometimes you need to get the numeric value of the quantity in a specific unit (eg, for submission to an external service that requires a numeric in a specified unit or to perform analysis beyond Squant's domain) When necessary, the value can be extracted in the desired unit with the method. Most types include methods with convenient aliases for the methods. NOTE - It is important to use the method for extracting the numeric value, as this ensures you will be getting the numeric value for the desired unit. should not be accessed directly. To prevent improper usage, direct access to the field may be deprecated in a future version. Creating strings formatted in the desired unit: Creating that includes a numeric value and unit symbol: This can be useful for passing properly scaled quantities to other processes that do not use Squants, or require use of more basic types (Double, String) Simple console based conversions (using DSL described below) Mapping over Quantity values Apply a operation to the underlying value of a quantity, while preserving its type and unit. The method effectively expands to NOTE - For Money objects, use the method as this will retain the BigDecimal precision used there. Approximations Create an implicit Quantity value to be used as a tolerance in approximations. Then use the metho…