Nondimensionalization

Create a nondimensionalization object in which we specify characteristic values, which are later employed to non-dimensionalize (or dimensionalize) all model parameters. Choose between GEO, SI or NO units:

• SI units assume all input and output is in SI units. Very general, but for typical geodynamic simulations often not so useful (as a million years has many seconds, resulting in large numbers).

• GEO units uses SI units throughout but assumes that input/output are in a format that is more convenient for typical geodynamic use cases, such as Myr,km or MPa

• NO units are nondimensional units. Note that for parameters to be correctly non-dimensionalized in this case, you still have to indicate units (such as that velocity is given in m/s).

A dimensional parameter can be transformed into a non-dimensional one with nondimensionalize.

Specify characteristic values

Characteristic values can be defined in 3 ways.

GeoParams.Units Module

This provides units and creates a non-dimensionalization object

source

GeoParams.Units.AbstractGeoUnit Type

AbstractGeoUnit

Abstract supertype for geo units.

source

GeoParams.Units.GeoUnit Type

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

source

GeoParams.Units.GeoUnits Type

GeoUnits

Structure that holds parameters used for non-dimensionalization

source

GeoParams.Units.GEO_units Function

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 Myr, 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 Myr
         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 Myr
         stress:      10 MPa
         temperature: 1000.0 °C

source

GeoParams.Units.SI_units Function

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)
Employing SI units
Characteristic values:
         length:      1000 m
         time:        1.0e19 s
         stress:      10 Pa
         temperature: 1000.0 K

source

GeoParams.Units.NO_units Function

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

source

GeoParams.Units.@unpack_val Macro

@unpack_val ρ, α = r
@unpack_val T ρ, α = r

Unpack the numerical values of GeoUnit fields, without their units. All requested variables must be GeoUnits.

The second form converts each value to evaluation type T, so a formula runs in the precision of its solver state rather than that of the stored parameters.

This is a modification of the @unpack macro from UnPack.jl, which retrieves 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
Density{Float64}(100.0, 4.0e-5)

julia> α
4.0e-5

julia> @unpack_val Float32 ρ,α = r
Density{Float64}(100.0, 4.0e-5)

julia> α
4.0f-5

source

GeoParams.Units.@unpack_units Macro

@unpack_units ρ, α = r
@unpack_units T ρ, α = r

Unpack GeoUnit fields as Quantitys, retaining their units. All requested variables must be GeoUnits.

The second form gives each quantity numerical type T.

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
Density{Float64}(100.0, 4.0e-5)

julia> α
4.0e-5 K⁻¹·⁰

source

(Non)-dimensionalize parameters

Once characteristic values have been defined, you can use them to non-dimensionalize or dimensionalize any parameter.

GeoParams.Units.nondimensionalize Function

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⁻³·⁰⁵ s⁻¹·⁰

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

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

source

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

nondimensionalizes a tuple of parameters

source

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

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

---

source

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

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

source

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

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

source

GeoParams.Units.dimensionalize Function

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.009506426344208684

julia> v_dim     =   dimensionalize(v_ND, cm/yr, CharUnits)
3.0 cm yr⁻¹·⁰

source

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

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

source

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

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

source

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

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

source

GeoParams.Units.isDimensional Function

isDimensional(MatParam::AbstractMaterialParam)

true if MatParam is in dimensional units.

source