Parameters.jl

Parameters.jl is designed for handling numerical-model parameters and provides several key capabilities:

• Keyword Constructors: Use @with_kw to define types with default values and keyword-based instantiation.
• Assertions: Allows defining assertions on field values directly within the type definition.
• Type-based Defaults: Supports creating type instances that inherit defaults from another existing type instance.
• Packing/Unpacking: Provides @unpack_* (specific to a type) and generic @unpack / @pack! macros for moving data between types and variables.
• Constant Definition: Use @consts for bulk constant declaration.

Parameters.jl is designed for handling numerical-model parameters and provides two primary capabilities:

1. Keyword type constructors with default values: Allows defining types where parameters can be passed as keywords with predefined defaults.
2. Unpacking and packing: Provides utilities to convert between composite types (structs) and dictionaries (Dict).

You can define invariants and relationships between fields directly within the @with_kw block:

1. Assertions: Use @assert (or @smart_assert from SmartAsserts.jl) inside the type definition to enforce constraints. These assertions are moved to the constructor.
2. Interdependence: Fields can depend on the values of other fields (e.g., c = a + b).
3. Default Types: Use @deftype to set a default type for all fields in the struct, reducing boilerplate. You can override this default for specific fields by providing an explicit type.

# Interdependence and Assertions
@with_kw struct Para{R<:Real}
    a::R = 5
    b::R
    c::R = a + b
    @assert a > 0
end

# Default Types (@deftype)
@with_kw struct Para2{R<:Real} @deftype R
    a = 5
    b::Any
    c = a + b
    d::Int = 4 # Overrides @deftype
end

The @with_kw macro automatically generates type-specific macros: @unpack_TypeName, @pack_TypeName!, and @pack_TypeName. These macros unpack or pack all fields of the specified type at once.

Warning: These are considered dangerous because:

• They can shadow local variables or input arguments if they share names with type fields.
• They can hijack existing names (e.g., adding a field pi to a type will shadow Base.pi).
• They only work with actual fields, not properties.

Recommendation: Use the generic @unpack and @pack! macros from UnPack.jl instead of these auto-generated type-specific versions.

# Auto-generated by @with_kw for type 'Para'
@unpack_Para pa
@pack_Para! pa  # Only for mutables
pa2 = @pack_Para # Creates a new instance (for immutables)

While keyword constructors are convenient for setting up parameters, they are currently slower in Julia than standard positional constructors.

Best Practice:

• Use keyword constructors for high-level configuration and setup.
• Do not use keyword constructors in performance-critical 'hot inner loops'.
• For performance-critical code, use the standard positional constructor provided by the package.

To work with the fields of a type (especially when passing them into functions), use the @unpack and @pack! macros from UnPack.jl. These are the preferred methods as they are generic and work with @with_kw structs, named tuples, modules, and dictionaries.

• @unpack field1, field2 = object is equivalent to field1, field2 = object.field1, object.field2.
• @pack! object = field1 is equivalent to object.field1 = field1 (works on mutable objects).

using UnPack

@with_kw mutable struct MPara{R<:Real}
    a::R = 5
    b::R
end

pa = MPara(b = 7)

function fn(pa::MPara)
    @unpack a, b = pa
    b = 77
    @pack! pa = b
end

The @with_kw macro can be used to decorate a named tuple expression, producing a constructor that returns a named tuple with default values. The resulting constructor is not type-locked, meaning you can pass different types of values to it.

# Define a named tuple constructor with defaults
MyNT = @with_kw (f = x -> x^3, y = 3, z = "foo")

# Use the constructor
nt = MyNT(f = x -> x^2, z = :foo)
# Result: (f = #12, y = 3, z = :foo)

# It is not type-locked
nt2 = MyNT(f = "string")
# Result: (f = "string", y = 3, z = "foo")

The @unpack macro allows you to extract multiple fields from a composite type (like a struct) into individual local variables. This is a concise alternative to manual field access.

Note: @unpack and @pack! are generic macros that work with any types via UnPack.jl.

struct B
    a
    b
    c
end

@unpack a, c = B(4, 5, 6)
# This is equivalent to:
# BB = B(4, 5, 6)
# a = BB.a
# c = BB.c

The @consts macro provides a way to define a block of multiple constants at once.

@consts begin
    a = 1
    b = 2.0
    c = "a"
end

You can use @with_kw to define a constructor for NamedTuples that includes default values. This is useful for creating templates for configuration or parameter sets.

using Parameters

MyNT = @with_kw (x = 1, y = "foo", z = :(bar))

MyNT()           # Returns (x = 1, y = "foo", z = :bar)
MyNT(x = 2)      # Returns (x = 2, y = "foo", z = :bar)

The @with_kw macro allows you to define structs or NamedTuples with default values for their fields. This creates a keyword constructor that lets you instantiate the type by specifying only the fields that differ from the defaults.

Important Performance Note: Keyword constructors are currently slower in Julia than standard positional constructors. Avoid using them in performance-critical hot inner loops. For such cases, use the standard positional constructor provided by the type.

using Parameters

@with_kw struct A
           a::Int = 6
           b::Float64 = -1.1
           c::UInt8
       end

# Usage:
A(c=4)          # Uses defaults for a and b
A(c=4, a=2)     # Overrides a, uses default for b