This gem converts MathML incorporating UnitsML expressions (based on the Ascii representation provided by NIST) into MathML complying with https://www.w3.org/TR/mathml-units/[], with UnitsML markup embedded in it, and with unique identifiers for each distinct unit, prefix, and dimension. Dimensions are automatically inserted corresponding to each unit. Units expressions are identified in MathML as <mtext>unitsml(...)</mtext>, which in turn can be identified in AsciiMath as "unitsml(...)".

The consuming document is meant to deduplicate the instances of UnitsML markup with the same identifier, and potentially remove them to elsewhere in the document or another document.

== Notation

The unitsml() expression consists of a unit string. The units used in unitsml() are taken from the UnitsDB database as updated by Ribose: https://github.com/unitsml/unitsdb[]. Units are given as an ASCII based code, consisting of multiplication or division of single units, each of which is defined as a Prefix (taken from https://github.com/unitsml/unitsdb/blob/master/prefixes.yaml[]), unit (taken from https://github.com/unitsml/unitsdb/blob/master/units.yaml[]), and exponent; e.g. mm*s^-2.

The conventions used for writing units are:

^ for exponents, e.g. m^-2
* to combine two units by multiplication; e.g. m*s^-2.
/ to combine two units by division;
u for μ (micro-)

For more on units notation, see <<units_notation,Units Notation>>.

The unitsml() can take additional optional parameters, giving further information for the UnitsML to be generated:

unitsml(unit-string, quantity: ID) provides the UnitsDB identifier for the quantity being measured (taken from https://github.com/unitsml/unitsdb/blob/master/quantities.yaml[]). For example, unitsml(s, quantity: NISTq109) indicates that the second is used to measure period duration. If a single quantity is associated with the unit in UnitsDB (as given in https://github.com/unitsml/unitsdb/blob/master/units.yaml[]), that quantity is added automatically; otherwise, no quantity is added unless explicitly nominated in this way.
unitsml(unit-string, name: NAME) provides a name for the unit, if one is not already available from UnitsDB. For example, unitsml(cal_th/cm^2, name: langley).
unitsml(unit-string, symbol: SYMBOL) provides an alternate symbol for the unit, in AsciiMath. The unit-string gives the canonical representation of the unit, but SYMBOL is what will be rendered. For example, unitsml(cal_th/cm^2, name: langley, symbol: La), or unitsml(mm*s^-2, symbol: mm cdot s^-2). (All variables in SYMBOL are rendered upright, as is the default for units.)
unitsml(unit-string, multiplier: SYMBOL) provides an alternate symbol for the multiliper of units. The options are an XML entity, or the values space or nospace (for which see discussion under Usage).

Standalone prefixes can be recognised by replacing the unit with hyphen; so unitsml(p-) corresponds to the standalone prefix "pico" (and is rendered as "p").

The gem also supports fundamental units, e.g. unitsml(e) for the atomic unit of charge, e, and symbols for dimensions. The latter are entered as dim_XXX, where XXX is their established symbol:

|=== |Symbol | Dimension

e.g. unitsml(dim_I) for the dimension of electric current, 𝖨.

== Rendering

The output of the gem is MathML, with MathML unit expressions (expressed as <mi>, complying with https://www.w3.org/TR/mathml-units/[MathML Units]) cross-referenced to UnitsML definitions embedded in the MathML.

The gem follows the MathML Units convention of inserting a spacing invisible times operator (<mo rspace='thickmathspace'>⁢</mo>) between any numbers (<mn>) and unit expressions in MathML, and representing units in MathML as non-italic variables (<mi mathvariant='normal'>).

Space is not inserted between a number and a unit expression, when that unit expression wholly consists of punctuation: 1 m, 1 °C, but 9° 7′ 22″.

== Example

[source]

9 "unitsml(C^3*A)"

is converted into:

[source,xml]

9 ⁢ C 3 · A

     <Unit xmlns='http://unitsml.nist.gov/2005' xml:id='U_C3.A' dimensionURL='#D_T3I4'>
       <UnitSystem name='SI' type='SI_derived' xml:lang='en-US'/>
       <UnitName xml:lang='en'>C^3*A</UnitName>
       <UnitSymbol type='HTML'>C<sup>3</sup> &#xB7; A</UnitSymbol>
       <UnitSymbol type='MathML'>
         <math xmlns='http://www.w3.org/1998/Math/MathML'>
           <mrow>
             <msup>
               <mrow>
                 <mi mathvariant='normal'>C</mi>
               </mrow>
               <mrow>
                 <mn>3</mn>
               </mrow>
             </msup>
             <mo>&#xB7;</mo>
             <mi mathvariant='normal'>A</mi>
           </mrow>
         </math>
       </UnitSymbol>
       <RootUnits>
         <EnumeratedRootUnit unit='coulomb' powerNumerator='3'/>
         <EnumeratedRootUnit unit='ampere'/>
       </RootUnits>
     </Unit>
     <Dimension xmlns='http://unitsml.nist.gov/2005' xml:id='D_T3I4'>
       <Time symbol='T' powerNumerator='3'/>
       <ElectricCurrent symbol='I' powerNumerator='4'/>
     </Dimension>

----

== Usage

The converter is run as:

[source,ruby]

c = Asciimath2UnitsML::Conv.new() c.Asciimath2UnitsML('1 "unitsml(mm*s^-2)"') # AsciiMath string containing UnitsML c.MathML2UnitsML("7"
"unitsml(kg^-2)") # AsciiMath string containing unitsml() c.MathML2UnitsML(Nokogiri::XML("7"
"unitsml(kg^-2)")) # Nokogiri parse of MathML document containing unitsml()

The converter class may be initialised with options:

multiplier is the symbol used to represent the multiplication of units. By default, following MathML Units, the symbol is middle dot (&#xB7). An arbitrary UTF-8 string can be supplied instead; it will be encoded as XML entities. The value :space is rendered as a spacing invisible times in MathML (<mo rspace='thickmathspace'>⁢</mo>), and as a non-breaking space in HTML. The value :nospace is rendered as a non-spacing invisible times in MathML (<mo>⁢</mo>), and is not rendered in HTML.

[[units_notation]] == Units Notation

The units used in unitsml() are taken from the UnitsDB database as updated by Ribose: https://github.com/unitsml/unitsdb[]. Units are given as an ASCII based code, consisting of multiplication or division of single units, each of which is defined as a Prefix (taken from https://github.com/unitsml/unitsdb/blob/master/prefixes.yaml[]), unit (taken from https://github.com/unitsml/unitsdb/blob/master/units.yaml[]), and exponent; e.g. mm*s^-2.

In case of ambiguity, the interpretation with no prefix is prioritised over the interpretation as a unit; so ct is interpreted as hundredweight, rather than centi-ton. Exceptionally, kg is decomposed into kilo-gram rather than treated as a basic unit, for consistency with other prefixes of grams. (Prefixed units appear in UnitsDB, and are indicated as prefixed: true.)

A unit may have multiple symbols; these are registered separately in https://github.com/unitsml/unitsdb/units.yaml[units.yaml], as entries under unit_symbols. These different symbols will be recognised as the same Unit in the UnitsML markup, but the original symbol will be retained in the MathML expression. So an expression like 1 unitsml(mL) will be recognised as referring to microlitres; the expression will be given under its canonical rendering ml in UnitsML markup, but the MathML rendering referencing that UnitsML expression will keep the notation mL.

The symbols used for units can be highly ambiguous; in order to guarantee accurate parsing, the symbols used to data enter units are unambiguous in https://github.com/unitsml/unitsdb/units.yaml[units.yaml]. They may be found as the entries for unit_symbols/id under each unit. For example, B is ambiguous between bel (as in decibel) and byte; they are kept unambiguous by using bel_B and byte_B to refer to them, although they will still both be rendered as B.

The following table is the current list of ambiguous symbols, which are disambiguated in the symbol ids used. This table can be generated (in Asciidoc format) through Asciimath2UnitsML::Conv.new().ambig_units:

FAQs

What is asciimath2unitsml?

Unknown package

Is asciimath2unitsml well maintained?

We found that asciimath2unitsml demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.

Package last updated on 10 Dec 2024

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install