Merge pull request #72 from SymbolicML/construction-base

Clean up type utilities: `constructorof`, `with_type_parameters`, `dimension_names`

Author: MilesCranmer

docs/make.jl

@@ -1,5 +1,6 @@
 using DynamicQuantities
-import DynamicQuantities.Units
+using DynamicQuantities.Units
+using DynamicQuantities: constructorof, with_type_parameters, dimension_names
 using Documenter
 
 DocMeta.setdocmeta!(DynamicQuantities, :DocTestSetup, :(using DynamicQuantities); recursive=true)

docs/src/types.md

@@ -43,3 +43,15 @@ AbstractGenericQuantity
 UnionAbstractQuantity
 DynamicQuantities.ABSTRACT_QUANTITY_TYPES
 ```
+
+## Custom behavior in abstract quantities
+
+There are a few functions you may need to overload
+when subtyping `AbstractDimensions`, `AbstractQuantity`,
+or `AbstractGenericQuantity`.
+
+```@docs
+constructorof
+with_type_parameters
+dimension_names
+```

src/arrays.jl

@@ -47,7 +47,7 @@ struct QuantityArray{T,N,D<:AbstractDimensions,Q<:UnionAbstractQuantity{T,D},V<:
     dimensions::D
 
     function QuantityArray(v::_V, d::_D, ::Type{_Q}) where {_T,_N,_D<:AbstractDimensions,_Q<:UnionAbstractQuantity,_V<:AbstractArray{_T,_N}}
-        Q_out = constructor_of(_Q){_T,_D}
+        Q_out = with_type_parameters(_Q, _T, _D)
         return new{_T,_N,_D,Q_out,_V}(v, d)
     end
 end
@@ -89,15 +89,15 @@ function Base.convert(::Type{QA}, A::QA) where {QA<:QuantityArray}
     return A
 end
 function Base.convert(::Type{QA1}, A::QA2) where {QA1<:QuantityArray,QA2<:QuantityArray}
-    Q = quantity_type(QA1)
     V = array_type(QA1)
-    N = ndims(QA1)
-
-    raw_array = Base.Fix1(convert, Q).(A)
-    output = QuantityArray(convert(constructor_of(V){Q,N}, raw_array))
-    # TODO: This will mess with static arrays
+    D = dim_type(QA1)
+    Q = quantity_type(QA1)
 
-    return output::QA1
+    return QuantityArray(
+        convert(V, ustrip(A)),
+        convert(D, dimension(A)),
+        Q,
+    )::QA1
 end
 
 @inline ustrip(A::QuantityArray) = A.value

src/internal_utils.jl

@@ -3,11 +3,6 @@ This file contains utility functions that are not specific to the
 library, but are used throughout.
 """
 
-@generated function fieldnames_equal(::Type{T1}, ::Type{T2}) where {T1,T2}
-    # Needs to be a generated function to ensure hardcoded
-    return Base.propertynames(T1) == Base.propertynames(T2)
-end
-
 const SUPERSCRIPT_MAPPING = ('⁰', '¹', '²', '³', '⁴', '⁵', '⁶', '⁷', '⁸', '⁹')
 const INTCHARS = ('0', '1', '2', '3', '4', '5', '6', '7', '8', '9')
 

src/symbolic_dimensions.jl

@@ -39,7 +39,7 @@ struct SymbolicDimensions{R} <: AbstractDimensions{R}
     nzvals::Vector{R}
 end
 
-static_fieldnames(::Type{<:SymbolicDimensions}) = ALL_SYMBOLS
+@inline dimension_names(::Type{<:SymbolicDimensions}) = ALL_SYMBOLS
 function Base.getproperty(d::SymbolicDimensions{R}, s::Symbol) where {R}
     nzdims = getfield(d, :nzdims)
     i = get(ALL_MAPPING, s, INDEX_TYPE(0))
@@ -53,7 +53,9 @@ function Base.getproperty(d::SymbolicDimensions{R}, s::Symbol) where {R}
 end
 Base.propertynames(::SymbolicDimensions) = ALL_SYMBOLS
 Base.getindex(d::SymbolicDimensions, k::Symbol) = getproperty(d, k)
-constructor_of(::Type{<:SymbolicDimensions}) = SymbolicDimensions
+
+constructorof(::Type{<:SymbolicDimensions}) = SymbolicDimensions
+with_type_parameters(::Type{<:SymbolicDimensions}, ::Type{R}) where {R} = SymbolicDimensions{R}
 
 SymbolicDimensions{R}(d::SymbolicDimensions) where {R} = SymbolicDimensions{R}(getfield(d, :nzdims), convert(Vector{R}, getfield(d, :nzvals)))
 SymbolicDimensions(; kws...) = SymbolicDimensions{DEFAULT_DIM_BASE_TYPE}(; kws...)
@@ -71,7 +73,7 @@ end
 for (type, _, _) in ABSTRACT_QUANTITY_TYPES
     @eval begin
         function Base.convert(::Type{Q}, q::UnionAbstractQuantity{<:Any,<:Dimensions}) where {T,Q<:$type{T,SymbolicDimensions}}
-            return convert(constructor_of(Q){T,SymbolicDimensions{DEFAULT_DIM_BASE_TYPE}}, q)
+            return convert(with_type_parameters(Q, T,SymbolicDimensions{DEFAULT_DIM_BASE_TYPE}), q)
         end
         function Base.convert(::Type{Q}, q::UnionAbstractQuantity{<:Any,<:Dimensions}) where {T,R,Q<:$type{T,SymbolicDimensions{R}}}
             syms = (:m, :kg, :s, :A, :K, :cd, :mol)
@@ -82,14 +84,14 @@ for (type, _, _) in ABSTRACT_QUANTITY_TYPES
             permute!(I, p)
             permute!(V, p)
             dims = SymbolicDimensions{R}(I, V)
-            return constructor_of(Q)(convert(T, ustrip(q)), dims)
+            return constructorof(Q)(convert(T, ustrip(q)), dims)
         end
         function Base.convert(::Type{Q}, q::UnionAbstractQuantity{<:Any,<:SymbolicDimensions}) where {T,D<:Dimensions,Q<:$type{T,D}}
-            result = constructor_of(Q)(T(ustrip(q)), D())
+            result = constructorof(Q)(convert(T, ustrip(q)), D())
             d = dimension(q)
             for (idx, value) in zip(getfield(d, :nzdims), getfield(d, :nzvals))
                 if !iszero(value)
-                    result = result * convert(constructor_of(Q){T,D}, ALL_VALUES[idx]) ^ value
+                    result = result * convert(with_type_parameters(Q, T, D), ALL_VALUES[idx]) ^ value
                 end
             end
             return result
@@ -108,7 +110,7 @@ for converting to specific symbolic units, or `convert(Quantity{<:Any,<:Symbolic
 for assuming SI units as the output symbols.
 """
 function uexpand(q::Q) where {T,R,D<:SymbolicDimensions{R},Q<:UnionAbstractQuantity{T,D}}
-    return convert(constructor_of(Q){T,Dimensions{R}}, q)
+    return convert(with_type_parameters(Q, T, Dimensions{R}), q)
 end
 uexpand(q::QuantityArray) = uexpand.(q)
 # TODO: Make the array-based one more efficient

src/types.jl

@@ -1,4 +1,4 @@
-import Tricks: static_fieldnames, static_fieldtypes
+using Tricks: static_fieldnames
 
 const DEFAULT_DIM_BASE_TYPE = FixedRational{DEFAULT_NUMERATOR_TYPE,DEFAULT_DENOM}
 const DEFAULT_VALUE_TYPE = Float64
@@ -17,7 +17,7 @@ the need to define many other functions.
 The key function that one could wish to overload is
 `DynamicQuantities.dimension_name(::AbstractDimensions, k::Symbol)` for mapping from a field name
 to a base unit (e.g., `length` by default maps to `m`). You may also need to overload
-`DynamicQuantities.constructor_of(::Type{T})` in case of non-standard construction.
+`constructorof(::Type{T})` in case of non-standard construction.
 """
 abstract type AbstractDimensions{R} end
 
@@ -103,13 +103,13 @@ struct Dimensions{R<:Real} <: AbstractDimensions{R}
     amount::R
 end
 
-(::Type{D})(::Type{R}; kws...) where {R,D<:AbstractDimensions} = constructor_of(D){R}((tryrationalize(R, get(kws, k, zero(R))) for k in static_fieldnames(D))...)
-(::Type{D})(; kws...) where {R,D<:AbstractDimensions{R}} = constructor_of(D)(R; kws...)
+(::Type{D})(::Type{R}; kws...) where {R,D<:AbstractDimensions} = with_type_parameters(D, R)((tryrationalize(R, get(kws, k, zero(R))) for k in dimension_names(D))...)
+(::Type{D})(; kws...) where {R,D<:AbstractDimensions{R}} = constructorof(D)(R; kws...)
 (::Type{D})(; kws...) where {D<:AbstractDimensions} = D(DEFAULT_DIM_BASE_TYPE; kws...)
 function (::Type{D})(d::D2) where {R,D<:AbstractDimensions{R},D2<:AbstractDimensions}
-    fieldnames_equal(D, D2) ||
+    dimension_names_equal(D, D2) ||
         error("Cannot create a dimensions of `$(D)` from `$(D2)`. Please write a custom method for construction.")
-    D((getproperty(d, k) for k in static_fieldnames(D))...)
+    D((getproperty(d, k) for k in dimension_names(D))...)
 end
 
 const DEFAULT_DIM_TYPE = Dimensions{DEFAULT_DIM_BASE_TYPE}
@@ -175,28 +175,79 @@ const ABSTRACT_QUANTITY_TYPES = ((AbstractQuantity, Number, Quantity), (Abstract
 
 for (type, base_type, _) in ABSTRACT_QUANTITY_TYPES
     @eval begin
-        (::Type{Q})(x::T, ::Type{D}; kws...) where {D<:AbstractDimensions,T<:$base_type,T2,Q<:$type{T2}} = constructor_of(Q)(convert(T2, x), D(; kws...))
-        (::Type{Q})(x::$base_type, ::Type{D}; kws...) where {D<:AbstractDimensions,Q<:$type} = constructor_of(Q)(x, D(; kws...))
-        (::Type{Q})(x::T; kws...) where {T<:$base_type,T2,Q<:$type{T2}} = constructor_of(Q)(convert(T2, x), dim_type(Q)(; kws...))
-        (::Type{Q})(x::$base_type; kws...) where {Q<:$type} = constructor_of(Q)(x, dim_type(Q)(; kws...))
+        (::Type{Q})(x::T, ::Type{D}; kws...) where {D<:AbstractDimensions,T<:$base_type,T2,Q<:$type{T2}} = constructorof(Q)(convert(T2, x), D(; kws...))
+        (::Type{Q})(x::$base_type, ::Type{D}; kws...) where {D<:AbstractDimensions,Q<:$type} = constructorof(Q)(x, D(; kws...))
+        (::Type{Q})(x::T; kws...) where {T<:$base_type,T2,Q<:$type{T2}} = constructorof(Q)(convert(T2, x), dim_type(Q)(; kws...))
+        (::Type{Q})(x::$base_type; kws...) where {Q<:$type} = constructorof(Q)(x, dim_type(Q)(; kws...))
     end
     for (type2, _, _) in ABSTRACT_QUANTITY_TYPES
         @eval begin
-            (::Type{Q})(q::$type2) where {T,D<:AbstractDimensions,Q<:$type{T,D}} = constructor_of(Q)(convert(T, ustrip(q)), convert(D, dimension(q)))
-            (::Type{Q})(q::$type2) where {T,Q<:$type{T}} = constructor_of(Q)(convert(T, ustrip(q)), dimension(q))
-            (::Type{Q})(q::$type2) where {Q<:$type} = constructor_of(Q)(ustrip(q), dimension(q))
+            (::Type{Q})(q::$type2) where {T,D<:AbstractDimensions,Q<:$type{T,D}} = constructorof(Q)(convert(T, ustrip(q)), convert(D, dimension(q)))
+            (::Type{Q})(q::$type2) where {T,Q<:$type{T}} = constructorof(Q)(convert(T, ustrip(q)), dimension(q))
+            (::Type{Q})(q::$type2) where {Q<:$type} = constructorof(Q)(ustrip(q), dimension(q))
         end
     end
 end
 
 const DEFAULT_QUANTITY_TYPE = Quantity{DEFAULT_VALUE_TYPE, DEFAULT_DIM_TYPE}
 
-new_dimensions(::Type{D}, dims...) where {D<:AbstractDimensions} = constructor_of(D)(dims...)
-new_quantity(::Type{Q}, l, r) where {Q<:UnionAbstractQuantity} = constructor_of(Q)(l, r)
+new_dimensions(::Type{D}, dims...) where {D<:AbstractDimensions} = constructorof(D)(dims...)
+new_quantity(::Type{Q}, l, r) where {Q<:UnionAbstractQuantity} = constructorof(Q)(l, r)
 
 dim_type(::Type{Q}) where {T,D<:AbstractDimensions,Q<:UnionAbstractQuantity{T,D}} = D
 dim_type(::Type{<:UnionAbstractQuantity}) = DEFAULT_DIM_TYPE
-constructor_of(::Type{T}) where {T} = Base.typename(T).wrapper
+
+"""
+    constructorof(::Type{<:AbstractDimensions})
+    constructorof(::Type{<:UnionAbstractQuantity})
+
+Return the constructor of the given type. This is used to create new objects
+of the same type as the input. Overload a method for a new type, especially
+if you need custom behavior.
+"""
+constructorof(::Type{<:Dimensions}) = Dimensions
+constructorof(::Type{<:Quantity}) = Quantity
+constructorof(::Type{<:GenericQuantity}) = GenericQuantity
+
+"""
+    with_type_parameters(::Type{<:AbstractDimensions}, ::Type{R})
+    with_type_parameters(::Type{<:UnionAbstractQuantity}, ::Type{T}, ::Type{D})
+
+Return the type with the given type parameters instead of the ones in the input type.
+This is used to get `Dimensions{R}` from input `(Dimensions{R1}, R)`, for example.
+Overload a method for a new type, especially if you need custom behavior.
+"""
+function with_type_parameters(::Type{<:Dimensions}, ::Type{R}) where {R}
+    return Dimensions{R}
+end
+function with_type_parameters(::Type{<:Quantity}, ::Type{T}, ::Type{D}) where {T,D}
+    return Quantity{T,D}
+end
+function with_type_parameters(::Type{<:GenericQuantity}, ::Type{T}, ::Type{D}) where {T,D}
+    return GenericQuantity{T,D}
+end
+
+# The following functions should be overloaded for special types
+function constructorof(::Type{T}) where {T<:Union{UnionAbstractQuantity,AbstractDimensions}}
+    return Base.typename(T).wrapper
+end
+function with_type_parameters(::Type{D}, ::Type{R}) where {D<:AbstractDimensions,R}
+    return constructorof(D){R}
+end
+function with_type_parameters(::Type{Q}, ::Type{T}, ::Type{D}) where {Q<:UnionAbstractQuantity,T,D}
+    return constructorof(Q){T,D}
+end
+
+"""
+    dimension_names(::Type{<:AbstractDimensions})
+
+Return a tuple of symbols with the names of the dimensions of the given type.
+This should be static so that it can be hardcoded during compilation.
+The default is to use `fieldnames`, but you can overload this for custom behavior.
+"""
+@inline function dimension_names(::Type{D}) where {D<:AbstractDimensions}
+    return static_fieldnames(D)
+end
 
 struct DimensionError{Q1,Q2} <: Exception
     q1::Q1

src/utils.jl

@@ -1,14 +1,13 @@
-import Tricks: static_fieldnames
 import Compat: allequal
 
 function map_dimensions(f::F, args::AbstractDimensions...) where {F<:Function}
     dimension_type = promote_type(typeof(args).parameters...)
-    dimension_names = static_fieldnames(dimension_type)
+    dim_names = dimension_names(dimension_type)
     return new_dimensions(
         dimension_type,
         (
             f((getproperty(arg, dim) for arg in args)...)
-            for dim in dimension_names
+            for dim in dim_names
         )...
     )
 end
@@ -48,9 +47,14 @@ function Base.promote_rule(::Type{<:AbstractQuantity}, ::Type{<:Number})
     return Number
 end
 
-Base.keys(d::AbstractDimensions) = static_fieldnames(typeof(d))
+Base.keys(d::AbstractDimensions) = dimension_names(typeof(d))
 Base.getindex(d::AbstractDimensions, k::Symbol) = getfield(d, k)
 
+@generated function dimension_names_equal(::Type{T1}, ::Type{T2}) where {T1,T2}
+    # Needs to be a generated function to ensure hardcoded
+    return dimension_names(T1) == dimension_names(T2)
+end
+
 # Compatibility with `.*`
 Base.size(q::UnionAbstractQuantity) = size(ustrip(q))
 Base.length(q::UnionAbstractQuantity) = length(ustrip(q))
@@ -116,8 +120,8 @@ end
 for f in (:one, :typemin, :typemax)
     @eval begin
         Base.$f(::Type{Q}) where {T,D,Q<:UnionAbstractQuantity{T,D}} = new_quantity(Q, $f(T), D)
-        Base.$f(::Type{Q}) where {T,Q<:UnionAbstractQuantity{T}} = $f(constructor_of(Q){T, DEFAULT_DIM_TYPE})
-        Base.$f(::Type{Q}) where {Q<:UnionAbstractQuantity} = $f(Q{DEFAULT_VALUE_TYPE, DEFAULT_DIM_TYPE})
+        Base.$f(::Type{Q}) where {T,Q<:UnionAbstractQuantity{T}} = $f(with_type_parameters(Q, T, DEFAULT_DIM_TYPE))
+        Base.$f(::Type{Q}) where {Q<:UnionAbstractQuantity} = $f(with_type_parameters(Q, DEFAULT_VALUE_TYPE, DEFAULT_DIM_TYPE))
     end
     if f == :one  # Return empty dimensions, as should be multiplicative identity.
         @eval Base.$f(q::Q) where {Q<:UnionAbstractQuantity} = new_quantity(Q, $f(ustrip(q)), one(dimension(q)))

test/unittests.jl

@@ -519,6 +519,13 @@ end
     @test typeof(MyDimensions(1, 1, 1)) == MyDimensions{Int}
     @test typeof(MyDimensions{Float64}(1, 1, 1)) == MyDimensions{Float64}
 
+    # Can use the default constructorof, with_type_parameters, and dimension_names:
+    @test DynamicQuantities.constructorof(MyDimensions{Float64}) == MyDimensions
+    @test DynamicQuantities.constructorof(MyQuantity{Float64}) == MyQuantity
+    @test DynamicQuantities.with_type_parameters(MyDimensions{Float64}, Rational{Int}) == MyDimensions{Rational{Int}}
+    @test DynamicQuantities.with_type_parameters(MyQuantity{Float64,DEFAULT_DIM_TYPE}, Float32, MyDimensions{Float64}) == MyQuantity{Float32,MyDimensions{Float64}}
+    @test DynamicQuantities.dimension_names(MyDimensions{Float64}) == (:length, :mass, :time)
+
     # But, we always need to use a quantity when mixing with mathematical operations:
     @test_throws ErrorException MyQuantity(0.1) + 0.1 * MyDimensions()
 end
@@ -545,7 +552,7 @@ end
         end
 
         # Internal constructor
-        @test DynamicQuantities.constructor_of(typeof(sym)) === SymbolicDimensions
+        @test DynamicQuantities.constructorof(typeof(sym)) === SymbolicDimensions
 
         # Equality comparisons
         @test sym == sym
@@ -625,6 +632,7 @@ end
     y = 0.5us"km/s"
     qa = [x, y]
     @test qa isa Vector{Quantity{Float64,SymbolicDimensions{Rational{Int}}}}
+    DynamicQuantities.with_type_parameters(SymbolicDimensions{Float64}, Rational{Int}) == SymbolicDimensions{Rational{Int}}
 end
 
 @testset "uconvert" begin
@@ -1069,4 +1077,15 @@ end
         # TODO: Currently this converts to a `Vector` of `GenericQuantity`
         @test_skip x .* z isa QuantityArray{Float32,1,<:Dimensions,<:GenericQuantity{Float32}}
     end
+
+    @testset "Array conversion" begin
+        x = SArray{Tuple{3}}(randn(3))
+        y = SArray{Tuple{3}}(randn(Float32, 3))
+        qx = QuantityArray(x, Dimensions(Rational{Int}, length=1))
+        qy = QuantityArray(y; length=1)
+
+        @test typeof(convert(typeof(qx), qy)) == typeof(qx)
+        @test convert(typeof(qx), qy)[1] isa Quantity{Float64}
+        @test convert(typeof(qx), qy)[1] == convert(Quantity{Float64}, qy[1])
+    end
 end