modified: Manifest.toml Update Unitful git-tree, repo-url format

modified:   Project.toml                   Julia 1.5 adds a line
modified:   README.md                      New: Installation, Adding or removing units
new file:   examples/readme_example.jl     Example from Readme.md
new file:   examples/torpedo_hangglider.jl New example
modified:   test/pretty-print.jl           Test column vector

Manifest.toml

@@ -46,8 +46,8 @@ uuid = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 
 [[Unitful]]
 deps = ["ConstructionBase", "LinearAlgebra", "Random"]
-git-tree-sha1 = "e2363764450d18e7f7c6ba66dbf30a067f7d44db"
+git-tree-sha1 = "9d9674441ebaa9a23810252c35aa1d446bb7327c"
 repo-rev = "master"
-repo-url = "https://github.com/hustf/Unitful.jl.git"
+repo-url = "https://github.com/hustf/Unitful.jl"
 uuid = "1986cc42-f94f-5a68-af5c-568840ba703d"
 version = "1.3.0"

Project.toml

@@ -18,4 +18,4 @@ Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 Unitful = "1986cc42-f94f-5a68-af5c-568840ba703d"
 
 [compat]
-julia = "1.3.0"
+julia = "1.3.0"

README.md

@@ -4,6 +4,7 @@
 [![Coveralls](https://coveralls.io/repos/github/hustf/MechanicalUnits.jl/badge.svg?branch=master)](https://coveralls.io/github/hustf/MechanicalUnits.jl?branch=master)
 
   - [Units](#units)
+  - [Dimensions](#dimensions)
   - [Usage](#usage)
   - [Goals](#goals)
   - [Alternatives](#alternatives)
@@ -13,17 +14,21 @@
 
 
 ### Convenient units in the REPL
-Units can be part of the side calculations mechanical and other engineers do every few minutes of a work day. Using units must be quick, nice and easy. That's the aim of this package, built on a slight modification of [Unitful.jl](https://github.com/hustf/Unitful.jl).
+Using units should be quick, nice and easy. That's the aim of this package, built on a slight modification of [Unitful.jl](https://github.com/hustf/Unitful.jl).
 
-The benefits?
+We enhance readability with colors, and we don't throw errors at meaningful input:
+```
+julia> 1kg∙m∙s⁻¹ |> N
+1N∙s
+```
+
+Benefits to using quantities rather than just numbers:
 * Fewer mistakes
 * More pattern recognition
 * Hints to find wrong input
 * Quicker problem solving
 * More ways to understand a problem or read a calculation
-* You could pick plot recipes based on units
-* You could pick table formats based on units
-
+* Functions can dispatch based on input dimensions: You would plot a force vector differently to a position.
 
 ## Units
 | Units | (Derived) dimension | Dimensions |
@@ -40,8 +45,8 @@ The benefits?
 | l dl cl ml                                    | Volume        | ᴸ³ | 
 | g                                             | Acceleration  | ᴸ ∙ ᵀ⁻² | 
 
-## Derived dimensions
-These are mostly useful for dispatching. We avoid defining common and ambigious derived dimensions. For example, the derived dimension for Length³ = ᴸ³ could be a volume, or just as usefully a first area moment.
+## Dimensions
+Dimensions are useful for defining specialized functions, e.g. `plot(F::Force)`. 
 
 | Derived dimension | Dimensions | 
 | ------------- | ------------- |
@@ -52,11 +57,32 @@ These are mostly useful for dispatching. We avoid defining common and ambigious
 | Pressure     | ᴹ / (ᵀ² ∙ ᴸ ) |
 | Density      | ᴹ / ᴸ³        |
 
+We avoid defining common and ambigious derived dimensions. For example, the derived dimension for Length³ = ᴸ³ could be a volume, or just as usefully a first area moment.
+
 ## Usage
-```
-julia > ]add MechanicalUnits
-```
-Colors won't show here. But let us do some side calculations:
+
+### Installation
+
+To use the correct version of Unitful for this package:
+´´´
+(v1.5) pkg> add https://github.com/hustf/Unitful.jl
+
+(v1.5) pkg> add https://github.com/hustf/MechanicalUnits.jl.git
+´´´
+
+If you get error messages saying that MechanicalUnits can't import packages, you probably had the original Unitful installed already. This may fix that:
+
+´´´
+(v1.5) pkg> rm Unitful
+
+(v1.5) pkg> add https://github.com/hustf/Unitful.jl
+
+´´´
+
+
+### Example REPL workflow
+
+Let us do some side calculations (other examples in that folder):
 ```julia
 julia> using MechanicalUnits
 
@@ -155,59 +181,50 @@ julia> u*1.5A |> J
   266.97560814373264 - 193.9691332565162im
 
 ```
-
-As we encountered above, the global namespace is quite cluttered with units by default. For clarity, import just what you need:
+### Adding or removing units
+If you want fewer globally defined variables, @import_expand just what you need: 
 ```julia
-import MechanicalUnits: N, kg, m, s, MPa
+julia> import MechanicalUnits: @import_expand, ∙
+
+julia> @import_expand ~m     # ~ : also import SI prefixes
+
+julia> (1.0cm², 2.0mm∙m, 3.0dm⁴/m² ) .|> mm²
+(100.0, 2000.0, 300.0)mm²
+
+julia> @import_expand dyn    # This unit is not exported by default
+
+julia> typeof(dyn)
+Unitful.FreeUnits{(dyn,), ᴸ∙ ᴹ∙ ᵀ⁻²,nothing}
+
+julia> 1dyn |> μm
+10kg∙μm∙s⁻²
 ```
 
 ## Goals
-This adaption of [Unitful.jl](https://github.com/PainterQubits/Unitful.jl) aims to be a preferable tool for quick side calculations in an office computer with limited user permissions.
+This adaption of a [fork](https://github.com/hustf/Unitful.jl) of [Unitful.jl](https://github.com/PainterQubits/Unitful.jl) aims to be a tool for quick side calculations in an office computer.
 
 This means:
-* We adapt to the limitations of Windows Powershell, Julia REPL or VSCode. Substitute symbols which can't be displayed.: `𝐓 -> ᵀ`
-* Units have color, which are sort of tweakable: `show(IOContext(stderr, :unitsymbolcolor=>:bold), 1minute)`
 * We pick a set of units as commonly used in mechanical industry
 * `h` is an hour, not Planck's constant
 * `in` is reserved by Julia; `inch` is a unit
 * `g` is gravity's acceleration, not a gramme
 * Prefer `mm` and `MPa`
-* Support division in a similar way as multiplication  , thus: `[1,2]m/s`
-* REPL output can always be parsed as input. We define the bullet operator `∙` (U+2219, \vysmblkcircle + tab) and print e.g. `2.32m∙s⁻¹`
-* Export dimensions to get shorter type signatures:
-```julia
-julia> 1m |> typeof
-Quantity{Int64, ᴸ,FreeUnits{(Unit{:Meter, ᴸ}(0, 1//1),), ᴸ,nothing}
-```
-* Units are never plural
-* Array output moves the units outside or to the header:
+* Non-decorated REPL output can always be parsed as input. We define the bullet operator `∙` (U+2219, \vysmblkcircle + tab) and print e.g. `2.32m∙s⁻¹`
+* Substitute symbols which can't be displayed in Windows without installing CygWin or VSCode. .: `𝐓 -> ᵀ`
+* Units show with color (although not in a text file)
+* Array and tuple output moves common units outside brackets or to the header:
 ```julia
 julia> dist = [900mm, 1.1m]
-2-element Array{Float64{mm},1}:
+2-element Array{Quantity{Float64, ᴸ,FreeUnits{(mm,), ᴸ,nothing}},1}:
   900.0
  1100.0
-
-julia> print(dist)
-[900.0, 1100.0]mm
 ```
-  * support unitful complex numbers
-
-* We would like to:
-  * tweak dimension sorting to customary order, thus: `m∙N -> N∙m`. A good alternative is e.g. 
-  ```julia
-julia> 43N*mm |> Nmm
-(43//1)Nmm
-
-```
-  * support rounding and customary engineering number formatting, but in a separate package.
-  * have supporting plot recipes, but in a separate package.
-  * return, instead of an error: `10m |>s -> 10m∙s^-1∙s` 
-  * support colorful units with Atom's mime type
-  * not rely on a tweaked fork of Unitful, but the original
-  * register the package and have full test coverage
+We would like to:
+* not rely on a tweaked fork of Unitful, but the original
+* register the package and have full test coverage
 
 ## Alternatives
-[Unitful.jl](https://github.com/PainterQubits/Unitful.jl) lists similar adaptions for other fields.
+See [Unitful.jl](https://github.com/PainterQubits/Unitful.jl)
 
 
 ## Am I missing some essential feature?
@@ -216,16 +233,6 @@ julia> 43N*mm |> Nmm
 
 - *Bug reports, feature requests, patches, and well-wishes are always welcome.* 
 
-## FAQ
-
-- ***Is this for real?***
-
-Yes. And for imaginary units as well. What about dual numbers? We have not tested yet.
-
-*What does this cost?*
-
-Your time. It may save some, too.
-
 ## Contributing
 
 It's the usual github way: fork, develop locally, push a commit to your fork, make a pull request.

examples/readme_example.jl

@@ -0,0 +1,35 @@
+# Run line by line in the REPL, or ctrl + enter in VSCode
+using MechanicalUnits
+m_air = 1000kg; c_p = 1.00kJ/(kg*K)
+@import_expand ~W   # Watt = Joule / Second is not exported by default.
+Q_cp(T1, T2) = m_air*c_p*(T2-T1) |> (kW*h)
+Q_cp(20°C, 985°C)
+dm |> upreferred
+preferunits(m)
+m_s = [30kg/m 28.8lb/ft]
+l_s = 93ft*[3 4]m/s
+m_s.*l_s |> (kg*m)
+E=206GPa; h_y = 100mm; b = 30mm; I = 1/12 * b * h_y^3
+L = 2m; F=100kg*g |> N
+F*L^3/(3E*I) |> mm
+l_wire = 20m
+k(d) = E * 0.691 * π/4 * d^2 / l_wire |> N/mm
+k.([5 6 8]mm)
+δ(d)= F / k(d) |> mm
+δ.([5, 6, 8]mm)
+d = 6mm
+dimension(d)
+1d |> s
+@import_expand ~V ~W ~A  G
+sqrt(1G²)
+[1V*12.0A 2W 1kg*g*1m/2s]*30minute |> kJ
+ω = 50*2π*rad/s
+t = (0:0.006:0.02)s
+u = 220V*exp.(im∙(ω∙t))
+u*1.5A |> J
+import MechanicalUnits: @import_expand, ∙
+@import_expand ~m     # ~ : also import SI prefixes
+(1.0cm², 2.0mm∙m, 3.0dm⁴/m² ) .|> mm²
+@import_expand dyn    # This unit is not exported by default
+typeof(dyn)
+1dyn |> μm

examples/torpedo_hangglider.jl

@@ -0,0 +1,45 @@
+# What would the battery range be? The local start-up competition
+# considers a battery powered torpedo pulling a hang-glider!
+#
+# Run line by line in the REPL, or ctrl + enter in VSCode
+
+using MechanicalUnits
+@import_expand ~W
+kWh = kW*h
+
+begin
+    "Battery capability"
+    E_battery = 200kWh
+    "Diameter torpedo"
+    D_torpedo = 0.5m
+    "Area, hangglider"
+    A_hangglider = 20m²
+    "Glide ratio, hangglider"
+    Cl_per_Cd = 15
+    "Mass, hangglider and pilot"
+    m_t = 22kg + 70kg
+    "Efficiency, torpedo"
+    η = 0.3
+    "Drag coefficient, torpedo"
+    C_d = 0.2
+    "Density, water"
+    ρ_w = 1026kg/m³
+    "Density, air"
+    ρ_a = 1.25kg/m³
+    "Velocity, torpedo and hangglider"
+    v = 50km/h
+
+    "
+    resistance(C, ρ::Density, v::Velocity, A::Area)
+    -> ::Force
+    "
+    resistance(C, ρ::Density, v::Velocity, A::Area) = (1/2) * ρ * C  * A * v^2 |> N
+end
+
+lift = m_t * g
+
+drag_hangglider = lift / Cl_per_Cd |> N
+
+drag_torpedo = resistance(C_d, ρ_w, v, (π / 4) * D_torpedo^2 )
+
+range_torpedo_hangglider = E_battery * η / (drag_torpedo + drag_hangglider) |> km

test/pretty-print.jl

@@ -79,8 +79,6 @@ end
     dimdi = Dict([m => " ᴸ", s => " ᵀ", kg => " ᴹ",
             Ra => " ᶿ", K => " ᶿ", h => " ᵀ",
             μm => " ᴸ", minute => " ᵀ"])
-    #expdidi = Dict(["⁻⁴" => "^-4", "⁻³" => "^-3", "⁻²" => "^-2", "⁻¹" => "^-1",
-    #           "²" => "^2", "³" => "^3", "⁴" => "^4"])
     for bu in ["m", "s", "kg", "Ra", "K", "h", "μm", "minute"],
         di in ["⁻⁴" , "⁻³", "⁻²" , "⁻¹", "²", "³", "⁴"]
         res = shortp(typeof(eval(Symbol(bu*di))))
@@ -101,6 +99,11 @@ end
     st = "[2 4]\e[36mm\e[39m∙\e[36ms⁻¹\e[39m"
     @test shortp(2a2) == st
     st = "1×2 Array{Quantity{" * sInt * ", ᴸ∙ ᵀ⁻¹,FreeUnits{(\e[36mm\e[39m, \e[36ms⁻¹\e[39m), ᴸ∙ ᵀ⁻¹,nothing}},2}:\n 2  4"
+    a3 = [10, 6, 2, -2]m
+    st = "[20, 12, 4, -4]\e[36mm\e[39m"
+    @test shortp(2a3) == st
+    st = "4-element Array{Quantity{Int64, ᴸ,FreeUnits{(\e[36mm\e[39m,), ᴸ,nothing}},1}:\n 20\n 12\n  4\n -4"
+    @test longp(2a3) == st
 end
 
 @testset "Tuples with units" begin
@@ -111,8 +114,21 @@ end
     a2 = (1, 2)m*s^-1
     st = "(2, 4)\e[36mm\e[39m∙\e[36ms⁻¹\e[39m"
     @test shortp(2 .*a2) == st
-    st = "1×2 Array{Quantity{" * sInt * ", ᴸ∙ ᵀ⁻¹,FreeUnits{(\e[36mm\e[39m, \e[36ms⁻¹\e[39m), ᴸ∙ ᵀ⁻¹,nothing}},2}:\n 2  4"
+    a3 = (10, 6, 2, -2)m
+    st = "(10, 6, 2, -2)\e[36mm\e[39m"
+    @test shortp(a3) == st
+end
+
+@testset "Ranges" begin
+    a1 = 1m:2m:5m
+    st = "(2:4:10)\e[36mm\e[39m"
+    @test shortp(2 .*a1) == st
+    @test longp(2 .*a1) == st
+    a2 = (5:-2:-1)m*s^-1
+    st = "[10, 6, 2, -2]\e[36mm\e[39m∙\e[36ms⁻¹\e[39m"
+    @test shortp(collect(2 .*a2)) == st
 end
+
 #
 @testset "Dimensions" begin
     u  = s*m*kg*K