This provides units and creates a non-dimensionalization object

AbstractGeoUnit

Abstract supertype for geo units.

Structure that holds a GeoUnit parameter, and encodes the units and whether it is dimensional or not in the name.

Having that is useful, as non-dimensionalization removes the units from a number and we thus no longer know how to transfer it back to the correct units.
With the GeoUnit struct, this information is retained, and we can thus redimensionalize it at a later StepRange

GeoUnits

Structure that holds parameters used for non-dimensionalization

GEO_units(;length=1000km, temperature=1000C, stress=10MPa, viscosity=1e20Pas)

Creates a non-dimensionalization object using GEO units.

GEO units implies that upon dimensionalization, time will be in Myrs, length in km, stress in MPa, etc. which is more convenient for typical geodynamic simulations than SI units The characteristic values given as input can be in arbitrary units (km or m), provided the unit is specified.

Examples:

julia> CharUnits = GEO_units()
Employing GEO units 
Characteristic values: 
         length:      1000 km
         time:        0.3169 Myrs
         stress:      10 MPa
         temperature: 1000.0 °C
julia> CharUnits.velocity
1.0e-7 m s⁻¹

If we instead have a crustal-scale simulation, it is likely more appropriate to use a different characteristic length:

julia> CharUnits = GEO_units(length=10km)
Employing GEO units 
Characteristic values: 
         length:      10 km
         time:        0.3169 Myrs
         stress:      10 MPa
         temperature: 1000.0 °C

CharUnits = SI_units(length=1000m, temperature=1000K, stress=10Pa, viscosity=1e20)

Specify the characteristic values using SI units

Examples:

julia> CharUnits = SI_units(length=1000m)
Employing SI units 
Characteristic values: 
         length:      1000 m
         time:        1.0e19 s
         stress:      10 Pa
         temperature: 1000.0 K

Note that the same can be achieved if the input is given in km:

julia> CharUnits = SI_units(length=1km)

CharUnits = NO_units(length=1, temperature=1, stress=1, viscosity=1)

Specify the characteristic values in non-dimensional units

Examples:

julia> using GeoParams;
julia> CharUnits = NO_units()
Employing NONE units 
Characteristic values: 
         length:      1
         time:        1.0 
         stress:      1
         temperature: 1.0

This unpacks the numerical value of `GeoUnit` in a structure, without the units.
All requested variables must be GeoUnits.

This is a modification of the `@unpack` macro as implemented in the `UnPack.jl` package, which can be used to retrieve the full variables.

Example

julia> struct Density{T} 
        ρ::GeoUnit{T} 
        α::GeoUnit{T} 
       end
julia> r = Density(GeoUnit(100kg/m^3),GeoUnit(4e-5/K));
julia> @unpack_val ρ,α = r
julia> α
4.0e-5
julia> typeof(α)
Float64

This unpacks the numerical value with units of `GeoUnit` parameters in a structure
All requested variables must be GeoUnits.

This is a modification of the `@unpack` macro as implemented in the `UnPack.jl` package, which can be used to retrieve the full variables.

Example

julia> struct Density{T} 
        ρ::GeoUnit{T} 
        α::GeoUnit{T} 
       end
julia> r = Density(GeoUnit(100kg/m^3),GeoUnit(4e-5/K));
julia> @unpack_units ρ,α = r
julia> α
4.0e-5 K⁻¹·⁰
julia> typeof(α)
Quantity{Float64, 𝚯⁻¹·⁰, Unitful.FreeUnits{(K⁻¹·⁰,), 𝚯⁻¹·⁰, nothing}}

nondimensionalize(param, CharUnits::GeoUnits{TYPE})

Nondimensionalizes param using the characteristic values specified in CharUnits

Example 1

julia> using GeoParams;
julia> CharUnits =   GEO_units();
julia> v         =   3cm/yr
3 cm yr⁻¹ 
julia> v_ND      =   nondimensionalize(v, CharUnits) 
0.009506426344208684

Example 2

In geodynamics one sometimes encounters more funky units

julia> CharUnits =   GEO_units();
julia> A         =   6.3e-2MPa^-3.05*s^-1
0.063 MPa⁻³·⁰⁵ s⁻¹
julia> A_ND      =   nondimensionalize(A, CharUnits) 
7.068716262102384e14

In case you are interested to see how the units of A look like in different units, use this function from the Unitful package:

julia> uconvert(u"Pa^-3.05*s^-1",A) 
3.157479571851836e-20 Pa⁻³·⁰⁵

and to see it decomposed in the basic SI units of length, mass and time:

julia> upreferred(A)
3.1574795718518295e-20 m³·⁰⁵ s⁵·¹ kg⁻³·⁰⁵

param = nondimensionalize(param::NTuple{N,Quantity}, g::GeoUnits{TYPE})

nondimensionalizes a tuple of parameters

MatParam_ND = nondimensionalize(MatParam::AbstractMaterialParam, CharUnits::GeoUnits{TYPE})

Non-dimensionalizes a material parameter structure (e.g., Density, CreepLaw)

nondimensionalize(phase_mat::MaterialParams, g::GeoUnits{TYPE})

nondimensionalizes all fields within the Material Parameters structure that contain material parameters

MatParam_ND = nondimensionalize(MatParam::NTuple{N, AbstractMaterialParamsStruct}, CharUnits::GeoUnits)

Non-dimensionalizes a tuple of material parameter structures (e.g., Density, CreepLaw)

dimensionalize(param, param_dim::Unitful.FreeUnits, CharUnits::GeoUnits{TYPE})

Dimensionalizes param into the dimensions param_dim using the characteristic values specified in CharUnits.

Example

julia> CharUnits =   GEO_units();
julia> v_ND      =   nondimensionalize(3cm/yr, CharUnits) 
0.031688087814028945
julia> v_dim     =   dimensionalize(v_ND, cm/yr, CharUnits) 
3.0 cm yr⁻¹

dimensionalize(MatParam::AbstractMaterialParam, CharUnits::GeoUnits{TYPE})

Dimensionalizes a material parameter structure (e.g., Density, CreepLaw)

Dimensionalize(phase_mat::MaterialParams, g::GeoUnits{TYPE})

Dimensionalizes all fields within the Material Parameters structure that contain material parameters

dimensionalize(MatParam::NTuple{N, AbstractMaterialParamsStruct}, CharUnits::GeoUnits)

dimensionalizes a tuple of material parameter structures (e.g., Density, CreepLaw)

isDimensional(MatParam::AbstractMaterialParam)

true if MatParam is in dimensional units.