From be7afc7c734299e764b0247dc8043ea934ed6a7d Mon Sep 17 00:00:00 2001 From: Gertjan van Zwieten Date: Sun, 9 Jan 2022 15:47:56 +0100 Subject: [PATCH] update readme The patch removes left-over references to Quantity as a univeral constructor, a role that has been taken over by the parse function. --- README.md | 54 +++++++++++++++++++++++++----------------------------- 1 file changed, 25 insertions(+), 29 deletions(-) diff --git a/README.md b/README.md index a45f498..35d8196 100644 --- a/README.md +++ b/README.md @@ -24,16 +24,15 @@ components of the Nutils suite, from where it should be imortable as `SI`: ## Usage The SI module defines all base units and derived units of the International -System of Units (SI) are predefined, as well as the full set of metric -prefixes. Dimensional values are generated primarily by instantiating the -Quantity type with a string value. +System of Units (SI) plus an Angle dimension, as well as the full set of metric +prefixes. Dimensional values are generated primarily by parsing a string value. >>> v = SI.parse('7μN*5h/6g') -The Quantity constructor recognizes the multiplication (\*) and division (/) -operators to separate factors. Every factor can be prefixed with a scale and -suffixed with a power. The remainder must be either a unit, or else a unit with -a metric prefix. +The parser recognizes the multiplication (\*) and division (/) operators to +separate factors. Every factor can be prefixed with a scale and suffixed with a +power. The remainder must be either a unit, or else a unit with a metric +prefix. In this example, the resulting object is of type "L/T", i.e. length over time, which is a subtype of Quantity that stores the powers L=1 and T=-1. Many @@ -43,9 +42,9 @@ through manipulation. >>> type(v) == SI.Velocity == SI.Length / SI.Time True -While Quantity can instantiate any subtype, we could have created the same -object by instantiating Velocity directly, which has the advantage of verifying -that the specified quantity is indeed of the desired dimension. +While `parse` can instantiate any subtype of Quantity, we could have created +the same object by instantiating Velocity directly, which has the advantage of +verifying that the specified quantity is indeed of the desired dimension. >>> w = SI.Velocity('8km') Traceback (most recent call last): @@ -56,7 +55,7 @@ Explicit subtypes can also be used in function annotations: >>> def f(size: SI.Length, load: SI.Force): pass -The Quantity type acts as an opaque container. As long as a quantity has a +The Quantity types act as an opaque container. As long as a quantity has a physical dimension, its value is inaccessible. The value can only be retrieved by dividing out a reference quantity, so that the result becomes dimensionless and the Quantity wrapper falls away. @@ -64,8 +63,9 @@ and the Quantity wrapper falls away. >>> v / SI.parse('m/s') 21.0 -To simplify this fairly common situation, any operation involving a Quantity -and a string is handled by parsing the latter automatically. +To simplify the fairly common situation that the reference quantity is a unit +or another parsed value, any operation involving a Quantity and a string is +handled by parsing the latter automatically. >>> v / 'm/s' 21.0 @@ -101,36 +101,32 @@ In case the predefined set of dimensions and units are insufficient, both can be extended. For instance, though it is not part of the official SI system, it might be desirable to add an angular dimension. This is done by creating a new Dimension instance, using a symbol that avoids the existing symbols T, L, M, I, -Θ, N and J: +Θ, N, J and A: - >>> Angle = SI.Dimension.create('Φ') + >>> Xonon = SI.Dimension.create('X') At this point, the dimension is not very useful yet as it lacks units. To -rectify this we define the radian by its abbreviation 'rad' in terms of the -provided reference quantity, and assign it to the global table of units: +rectify this we define the unit yam as being internally represented by a unit +value: - >>> SI.units.rad = Angle.reference_quantity + >>> SI.units.yam = Xonon.reference_quantity -Additional units can be defined by relating them to pre-existing ones: +Additional units can be defined by relating them to pre-existing ones. Here we +define the unit zop as the equal of 15 kilo-yam: >>> import math - >>> SI.units.deg = math.pi / 180 * SI.units.rad + >>> SI.units.zop = 15 * SI.units.kyam Alternatively, units can be defined using the same string syntax that is used by the Quantity constructor. Nevertheless, the following statement fails as we cannot define the same unit twice. - >>> SI.units.deg = '0.017453292519943295rad' + >>> SI.units.zop = '15kyam' Traceback (most recent call last): ... - ValueError: cannot define 'deg': unit is already defined + ValueError: cannot define 'zop': unit is already defined Having defined the new units we can directly use them: - >>> angle = SI.parse('30deg') - -Any function that accepts angular values will expect to receive them in a -specific unit. The new Angle dimension makes this unit explicit: - - >>> math.sin(angle / SI.units.rad) - 0.49999999999999994 + >>> SI.parse('24mzop/h') + 0.1[X/T]