Calculations with non-decimal units and mixed bases

Many units of measurement in use today have not yet been decimalized, and work in non-decimal and mixed bases. Arithmetic using these units can be convoluted, requiring either conversion or error-prone carrying. Abacist builds upon the representations of physical quantities provided by Quantitative to support compound units in mixed bases.

• allows arbitrary constructions of cascading units of the same dimension, such as (miles, yards, feet and inches)
• provides addition, subtraction and scalar multiplication operations on those units
• allows conversion to and from decimal Quantity values
• unit types are opaque aliases of Long for performance

All terms and types are defined in the abacist package, and are exported to the soundness package, and build upon definitions in Quantitative. You can import from either:

syntax scala
transform
  before   selective imports
  after    universal soundness import
  replace  abacist.*, quantitative.*  soundness.*
##
import abacist.*, quantitative.*

Prior to the adoption of the metric system for quantities of mass and length, other systems based on non-decimal (but exact) multiples of other units were widely used. These are commonly called "the Imperial System", particularly for lengths, and for masses, "Avoirdupois", but actually represent several different systems (often with units of the same name representing different physical amounts, confusingly) adopted in various jurisdictions with varying degrees of officiality.

Abacist can accommodate all such systems through a single type which defines a cascade of units (of the same dimension), in a tuple. The unit types are defined in Quantitative, and Abacist makes it possible to use them in discrete multiples.

For example, one variant of the Imperial System measuring human heights could be defined as,

syntax scala
##
type ImperialHeight = (Feet[1], Inches[1])

or for longer distances,

syntax scala
##
type ImperialDistance = (Miles[1], Yards[1], Inches[1])

that is, a number of miles, yards and inches, represented as a Tuple of these units' types (each raised to the power 1). Another example for mass is,

syntax scala
##
type Avoirdupois = (Hundredweights[1], Stones[1], Pounds[1], Ounces[1], Drams[1])

or alternatively:

syntax scala
##
type SimpleAvoirdupois = (Pounds[1], Ounces[1])

Each type, a tuple of subtypes of Measure, statically represents a system of discrete cascading units, provided that,

• each element of the tuple has the same dimensionality (i.e. represents the same sort of physical quantity)
• the elements are ordered by decreasing magnitude and furthermore, for most useful operations, that contextual Ratio instances exist between each unit and the principal unit for their common dimension.

With a valid definition, such as one of the above, we can represent values in its units, called a Count (because it's a count of integer multiples of each of the units).

To construct a new Count, simply call its factory method with the appropriate tuple type, and as many integer arguments as necessary. The rightmost Int argument will be interpreted as the multiple of the rightmost unit in the tuple, and additional arguments will represent (right-to-left) multiples of units of increasing magnitude. For example, Count[ImperialDistance](180, 24) represents, "180 yards and 24 inches", while, Count[ImperialDistance](1, 180, 24) represents, "1 mile, 180 yards and 24 inches".

Individual units from a Count may be extracted by applying the units value to extract, without its dimension, to the Count value, like so:

syntax scala
##
type Height = (Feet[1], Inches[1])
val height: Count[Height] = Count(6, 4)
val feet = height[Feet]
val inches = height[Inches]

The value feet will be set to 6, and the value inches will be 4.

Counts of identical units may be added and subtracted, and multiplied and divided by numbers, but not by other quantities. They may be converted to Quantitys with the quantity method, much as a Quantity can be converted, or constructed from a Quantity by calling count on the Quantity, e.g.

syntax scala
##
(18*Kilo(Gram)).count[Avoirdupois]

Note that in many cases, the discrete units of a Count will not be able to precisely represent a Quantity. A Quantity will be rounded to the nearest whole Count value. Converting back to a Quantity will include this rounding error.

For example, note how the error changes when more precise Count units are used:

syntax scala
transform
  before  Imprecise height
  after   Precise height
  replace  Inches[1]  Inches[1], Points[1]
  replace  0.00460  0.0000139
##
type Height = (Feet[1], Inches[1])
val height: Quantity[Metres[1]] = Quantity(1.3)
val error = height - height.count[Height].quantity

assert(error == 0.00460)

A Count is an opaque type alias for a Long, meaning that operations involving Counts do not involve any heap objects. The underlying value of a count represents an integer multiple of the smallest unit in the cascade. For example, a length of 1ft 3in would be stored as 15, being the sum of the 12 inches in one foot, plus 3 inches.

Abacist is classified as fledgling. For reference, Soundness projects are categorized into one of the following five stability levels:

• embryonic: for experimental or demonstrative purposes only, without any guarantees of longevity
• fledgling: of proven utility, seeking contributions, but liable to significant redesigns
• maturescent: major design decisions broady settled, seeking probatory adoption and refinement
• dependable: production-ready, subject to controlled ongoing maintenance and enhancement; tagged as version 1.0.0 or later
• adamantine: proven, reliable and production-ready, with no further breaking changes ever anticipated

Projects at any stability level, even embryonic projects, can still be used, as long as caution is taken to avoid a mismatch between the project's stability level and the required stability and maintainability of your own project.

Abacist is designed to be small. Its entire source code currently consists of 315 lines of code.

Abacist will ultimately be built by Fury, when it is published. In the meantime, two possibilities are offered, however they are acknowledged to be fragile, inadequately tested, and unsuitable for anything more than experimentation. They are provided only for the necessity of providing some answer to the question, "how can I try Abacist?".

1. Copy the sources into your own project

   Read the fury file in the repository root to understand Abacist's build structure, dependencies and source location; the file format should be short and quite intuitive. Copy the sources into a source directory in your own project, then repeat (recursively) for each of the dependencies.

   The sources are compiled against the latest nightly release of Scala 3. There should be no problem to compile the project together with all of its dependencies in a single compilation.

2. Build with Wrath

   Wrath is a bootstrapping script for building Abacist and other projects in the absence of a fully-featured build tool. It is designed to read the fury file in the project directory, and produce a collection of JAR files which can be added to a classpath, by compiling the project and all of its dependencies, including the Scala compiler itself.

   Download the latest version of wrath, make it executable, and add it to your path, for example by copying it to /usr/local/bin/.

   Clone this repository inside an empty directory, so that the build can safely make clones of repositories it depends on as peers of abacist. Run wrath -F in the repository root. This will download and compile the latest version of Scala, as well as all of Abacist's dependencies.

   If the build was successful, the compiled JAR files can be found in the .wrath/dist directory.

Contributors to Abacist are welcome and encouraged. New contributors may like to look for issues marked beginner.

We suggest that all contributors read the Contributing Guide to make the process of contributing to Abacist easier.

Please do not contact project maintainers privately with questions unless there is a good reason to keep them private. While it can be tempting to repsond to such questions, private answers cannot be shared with a wider audience, and it can result in duplication of effort.

Abacist was designed and developed by Jon Pretty, and commercial support and training on all aspects of Scala 3 is available from Propensive OÜ.

An abacist is a person who operates an abacus, for counting and arithmetic. Counting of mixed-base units is the purpose of Abacist.

In general, Soundness project names are always chosen with some rationale, however it is usually frivolous. Each name is chosen for more for its uniqueness and intrigue than its concision or catchiness, and there is no bias towards names with positive or "nice" meanings—since many of the libraries perform some quite unpleasant tasks.

Names should be English words, though many are obscure or archaic, and it should be noted how willingly English adopts foreign words. Names are generally of Greek or Latin origin, and have often arrived in English via a romance language.

The logo shows a single bead on a rod of an abacus, the device an abacist specializes in.

Abacist is copyright © 2024 Jon Pretty & Propensive OÜ, and is made available under the Apache 2.0 License.