Implementation details

This page covers performance considerations, caching mechanisms, precompilation, and other implementation details of Semisimple.jl.

Caching

Semisimple.jl uses several internal caches to avoid recomputing expensive results. Understanding these caches is important for benchmarking and memory management.

Available caches

Semisimple.jl maintains ten internal caches. Six are unbounded Dict caches for small singletons and lookup tables; four are bounded LRU caches (from LRUCache.jl) whose total memory budget is configurable at runtime via configure_caches!.

The six Dict caches are unbounded and persist for the lifetime of the Julia session. The four LRU caches have a configurable memory budget (default: 25 % of system RAM, minimum 256 MiB) and automatically evict least-recently-used entries when the budget is exceeded.

Inspecting caches

Use cache_info to get a snapshot of cache occupancy:

using Semisimple

# Snapshot before any work
info = cache_info()
println("Tensor cache: ", info.tensor.length, " entries (max ", info.tensor.maxsize, " bytes)")

# Populate some caches by doing computations
ω₁ = fundamental_weight(TypeE{8}, 1)
freudenthal_formula(ω₁)
tensor_product(ω₁, ω₁)

# Snapshot after
info = cache_info()
println("Dominant character cache: ", info.dominant_character.length, " entries")
println("Tensor cache: ", info.tensor.length, " entries")

Clearing caches

Use clear_caches! (or its alias clear_all_caches!) to empty every cache at once:

using Semisimple

# Do some computations
ω₁ = fundamental_weight(TypeA{2}, 1)
tensor_product(ω₁, ω₁)
freudenthal_formula(ω₁)
symmetric_power(ω₁, 3)

# Clear everything
clear_caches!()

This is particularly useful for:

• Benchmarking cold-start performance — measure how long operations take without cached results
• Memory management — free memory after large computations (e.g., after computing many E₈ tensor products)
• Reproducible testing — ensure tests start from a clean state

Individual cache variables have underscored names and are internal implementation details. Prefer the public clear_caches! and configure_caches! APIs.

Configuring cache budgets

Use configure_caches! to resize the LRU caches at runtime. The budget (in bytes) controls the total memory envelope; the four fraction arguments determine how it is divided:

using Semisimple

# Give caches 512 MiB total
configure_caches!(budget = 512 * 1024^2)

# Custom split: 50 % tensor, 30 % dominant, 10 % each for Sym/⋀
configure_caches!(
  budget = 512 * 1024^2,
  dominant_frac = 0.30,
  tensor_frac = 0.50,
  sym_power_frac = 0.10,
  ext_power_frac = 0.10,
)

Default fractions: dominant 30 %, tensor 40 %, symmetric 15 %, exterior 15 %. The default total budget is 25 % of system RAM (minimum 256 MiB). These defaults can also be set persistently via Julia's Preferences.jl (keys: cache_budget, dominant_frac, tensor_frac, sym_power_frac, ext_power_frac).

Cache invalidation

Caches are never invalidated by code changes — all cached functions are pure (same inputs always produce same outputs). However, cached entries can disappear in three ways:

• You explicitly clear a cache (via clear_caches! or empty!(...))
• An LRU cache evicts least-recently-used entries when its memory budget is exceeded
• Your Julia session ends

Automatic eviction only affects the four bounded LRU caches. The six unbounded Dict caches persist until cleared or session end.

This design is safe because:

• Dynkin types are immutable compile-time constants
• Weights are immutable SVector objects
• All cached functions are pure — re-computing an evicted entry always gives the same result

Precompilation

Semisimple.jl precompiles many commonly-used methods to reduce first-call latency. When you load the package with using Semisimple, the precompilation work has already been done.

What gets precompiled

The package precompiles the following operations for all simple Dynkin types up to rank 10 (plus the exceptional types):

Dynkin types precompiled:

• TypeA{1} through TypeA{10}
• TypeB{2} through TypeB{10}
• TypeC{2} through TypeC{10}
• TypeD{3} through TypeD{10}
• TypeE{6}, TypeE{7}, TypeE{8}
• TypeF4
• TypeG2

Operations precompiled:

• cartan_matrix, cartan_symmetrizer, cartan_bilinear_form, cartan_matrix_inverse
• _make_root_system (internal root system construction)
• _weyl_denominator, _weyl_dim_scaled_roots (Weyl dimension formula internals)
• degree (representation dimension)
• conjugate_dominant_weight (dominant weight conjugation)
• conjugate_dominant_weight_with_length (Borel–Weil–Bott hot path)
• weyl_orbit (Weyl orbit generation)
• Weyl group actions (* operator for roots and weights with Weyl elements)
• freudenthal_formula (weight multiplicities)
• dot_reduce (weight normalization)
• tensor_product (Brauer–Klimyk; Littlewood–Richardson rule for Type A)

Keeping precompilation affordable

Covering 41 Dynkin types would be very expensive if every method were compiled separately per type. Instead, the heavy numeric kernels (the Freudenthal recursion, the Weyl dimension formula, dominant-weight enumeration, and the Weyl-orbit traversal) are parametrized by the rank only, so for example A₇, B₇, C₇, D₇, and E₇ all share a single compiled kernel. Only thin per-type wrappers remain, which keeps both precompilation time and the package-image size in check.

To skip the precompile workload entirely (e.g. during development or in CI jobs that never call into the numeric routines), set the package preference:

using Preferences, Semisimple
set_preferences!(Semisimple, "precompile_workload" => false)

The package then precompiles in a couple of seconds; all functionality remains available, with compilation happening lazily at first use.

Why precompilation matters

Without precompilation, the first call to a method triggers just-in-time (JIT) compilation, which can take hundreds of milliseconds. With precompilation, these methods are ready to use immediately:

using Semisimple

# First call is fast due to precompilation
@time degree(fundamental_weight(TypeE{8}, 1))  # ~0.001s

# Without precompilation, this would take ~0.5s for the first call

What is NOT precompiled

Operations involving:

• Product Dynkin types (e.g., ProductDynkinType{Tuple{TypeA{2}, TypeB{3}}})
• Rank ≥ 11 simple types (e.g., TypeA{15})

These will experience first-call latency but will be fast on subsequent calls (after JIT compilation). Because the numeric kernels are shared per rank, the first-call latency for an uncovered type is limited to its thin wrappers.

Performance characteristics

Compile-time vs. run-time

Semisimple.jl leverages Julia's type system and @generated functions to move selected computations to compile time, while larger derived data is computed once at runtime and cached per Dynkin type (keeping precompilation cheap):

This means that cartan_matrix(TypeE{8}) produces a compile-time constant SMatrix that is embedded directly into your compiled code — there's no matrix allocation at runtime. Root systems, by contrast, are built by a single shared routine on first use and memoized, so the construction cost (microseconds) is paid once per session.

Memory usage

For large-scale computations (e.g., thousands of E₈ tensor products), the character-related LRU caches will automatically evict old entries once their memory budget is reached. Use configure_caches! to increase the budget, or clear_caches! to free memory immediately.

Asymptotic complexity

For reproducible performance measurements, see the benchmark scripts in benchmark/.

Type stability

Semisimple.jl is designed for complete type stability:

using Semisimple

ω₁ = fundamental_weight(TypeE{8}, 1)
typeof(ω₁)  # WeightLatticeElem{TypeE{8}, 8} — concrete type

ch = freudenthal_formula(ω₁)
typeof(ch)  # Dict{SVector{8, Int64}, BigInt} — concrete type

result = tensor_product(ω₁, ω₁)
typeof(result)  # WeylCharacter{TypeE{8}, 8} — concrete type

All public APIs return concrete types, enabling aggressive compiler optimizations. There are no type instabilities in hot paths.

Numerical precision

All computations use exact integer arithmetic — there are no floating-point operations:

• Weights are SVector{R, Int} — exact integer vectors
• Irreducible multiplicities in a WeylCharacter are Int; weight multiplicities from the Freudenthal recursion are BigInt (they can exceed typemax(Int64) for large representations)
• Dimensions are computed exactly (the Weyl dimension formula works in BigInt)
• Inner products use scaled integer forms to avoid division

This means:

• No numerical stability concerns — safe for arbitrarily large representations
• No overflow — dimensions and weight multiplicities are BigInt throughout

Example: the irreducible representation of E₈ with highest weight ρ has dimension $2^{120}$, far beyond typemax(Int64) ≈ 9.2 × 10^{18}:

julia> using Semisimple

julia> ρ = weyl_vector(TypeE{8});

julia> degree(ρ)
1329227995784915872903807060280344576

julia> degree(ρ) == big(2)^120
true

Thread safety

The recommended pattern for parallel computation remains: populate caches in a single-threaded warm-up phase, then perform read-only operations in parallel.

Comparison with LiE

Semisimple.jl reimplements many algorithms from the LiE computer algebra system. Key differences:

For hot operations (cached, precompiled), Semisimple.jl matches or exceeds LiE's performance. For cold operations, LiE is faster due to no JIT compilation delay.

Implementation philosophy

Semisimple.jl follows these design principles:

1. Type-level dispatch at the API surface — Use Julia's type system to specialize the user-facing layer for each Dynkin type, while the heavy numeric kernels are shared per rank so they are compiled only once for e.g. A₇/B₇/C₇/D₇/E₇
2. Compile-time constants where they pay — @generated Cartan data; larger derived data (root systems, Weyl dimension data) is computed once at runtime and memoized
3. Immutability — All core types are immutable for thread safety and optimization
4. Caching — Trade memory for speed by memoizing expensive computations
5. Minimal dependencies — StaticArrays.jl, LRUCache.jl, PrecompileTools.jl, Preferences.jl, and LinearAlgebra (stdlib)
6. Pure Julia — No C/Fortran, enabling introspection and compilation to other targets

These principles enable aggressive compiler optimizations while maintaining mathematical rigor.

Weyl orbit traversal

Weyl orbits are computed by the internal module Weylloop.jl, which implements LiE-style systematic orbit traversal. Rather than a hash-set BFS that scales with orbit size, it converts weight coordinates to the ε-basis where classical Weyl subgroups act as permutations (type A) or permutations + sign flips (types B/C/D). Orbits are enumerated via lexicographic permutation generation and Gray-code sign flips, eliminating the $O(|\text{orbit}|)$ hash-set overhead that would otherwise dominate for large orbits (e.g., E₈ orbits with millions of elements). For exceptional types, precomputed coset representatives reduce the problem to the classical case.

API reference

clear_all_caches!()

julia> using Semisimple

julia> clear_all_caches!()

clear_caches!()

julia> using Semisimple

julia> ω1 = fundamental_weight(TypeA{2}, 1);

julia> tensor_product(ω1, ω1);  # populates caches

julia> clear_caches!()

configure_caches!(; budget=nothing, dominant_frac=nothing, tensor_frac=nothing,
                    sym_power_frac=nothing, ext_power_frac=nothing)

julia> using Semisimple

julia> configure_caches!(budget = 512 * 1024^2)  # 512 MiB total

cache_info() -> NamedTuple

julia> using Semisimple

julia> info = cache_info();

julia> info.tensor.length >= 0
true

Internals reference

These are internal functions not part of the public API. They are documented here for contributors and advanced users.

Root system internals

RootSystem(::Type{DT}) -> RootSystem{DT,R}

julia> using Semisimple

julia> RootSystem(TypeA{2}) === RootSystem(TypeA{2})
true

_make_root_system_runtime(::Type{DT}) -> RootSystem{DT,R}

Weyl group internals

_weyl_denominator(::Type{DT}) -> BigInt

_weyl_dim_scaled_roots(::Type{DT}) -> Vector{SVector{R,Int}}

weylloop(action!, ::Type{DT}, v::AbstractVector{<:Integer})

Cache internals

_apply_cache_preferences!()

Character internals

dot_reduce(λ::WeightLatticeElem{DT,R}) -> Tuple{Int, WeightLatticeElem{DT,R}}

brauer_klimyk(char::Dict{SVector{R,Int}, <:Integer}, μ::WeightLatticeElem{DT,R}) -> WeylCharacter{DT,R}

_brauer_klimyk_dominant(dom_char::Dict{SVector{R,Int}, <:Integer}, μ::WeightLatticeElem{DT,R}) -> WeylCharacter{DT,R}

_expand_dominant_orbits(::Type{DT}, dom_mults, k) -> Dict{SVector{R,Int}, BigInt}

_vdecomp(::Type{DT}, dom_char::Dict{SVector{R,Int},<:Integer}) -> WeylCharacter{DT,R}

_tensor_characters(V::WeylCharacter{DT,R}, W::WeylCharacter{DT,R}) -> WeylCharacter{DT,R}

Littlewood–Richardson internals (type A)

_weight_to_partition(λ::WeightLatticeElem{TypeA{N},N}) -> Vector{Int}

_partition_to_weight(::Type{TypeA{N}}, p::Vector{Int}) -> WeightLatticeElem{TypeA{N},N}

_lr_coefficients(α::Vector{<:Integer}, β::Vector{<:Integer}, n::Integer) -> Dict{Vector{Int}, Int}

_n_tableaux(λ::Vector{<:Integer}, l::Integer) -> BigInt

Plethysm internals (Murnaghan–Nakayama)

_partitions(n::Integer) -> Vector{Vector{Int}}

_classord(κ::Vector{Int}) -> BigInt

_mn_char_val(λ::Vector{Int}, μ::Vector{Int}) -> BigInt