Package Architecture

This page explains the internal structure of Giac.jl, helping developers understand how the package is organized and how components interact.

Overview

Giac.jl wraps the GIAC computer algebra system (C++) for use in Julia. The package uses CxxWrap.jl for C++/Julia interoperability and provides a Julia-native API.

graph TB
    subgraph Julia_User_Code["Julia User Code"]
        A[User Code]
    end

    subgraph Giac_jl_Package["Giac.jl Package"]
        B["api.jl (High-level API)"]
        C["command_utils.jl (giac_cmd)"]
        D["wrapper.jl (CxxWrap)"]
        E["types.jl (GiacExpr)"]
    end

    subgraph External_Libraries["External Libraries"]
        F["libgiac-julia-wrapper"]
        G["libgiac (GIAC CAS)"]
    end

    A --> B
    A --> C
    B --> D
    C --> D
    D --> F
    F --> G
    E -.-> D

Source File Reference

Module Initialization

When using Giac is executed, the following initialization sequence occurs:

sequenceDiagram
    participant User
    participant Giac.jl
    participant wrapper.jl
    participant GiacCxxBindings
    participant libgiac

    User->>Giac.jl: using Giac
    Giac.jl->>Giac.jl: include all source files
    Giac.jl->>wrapper.jl: __init__()
    wrapper.jl->>GiacCxxBindings: init_giac_library()
    GiacCxxBindings->>libgiac: Load shared library (RTLD_GLOBAL)
    libgiac-->>GiacCxxBindings: Library loaded
    GiacCxxBindings-->>wrapper.jl: Ready
    wrapper.jl->>Giac.jl: Create DEFAULT_CONTEXT
    Giac.jl->>Giac.jl: _init_command_registry()
    Giac.jl->>Commands.jl: Commands.__init__()
    Commands.jl->>Commands.jl: Generate ~2000 command functions
    Commands.jl-->>User: Ready to use

What Happens in __init__()

1. Library Loading: init_giac_library() loads the C++ wrapper library with RTLD_GLOBAL flag to ensure proper symbol resolution
2. Context Creation: Creates DEFAULT_CONTEXT, the global evaluation context
3. Command Registry: Initializes the registry of valid GIAC commands
4. Commands Module: Dynamically generates wrapper functions for all GIAC commands

Type System

Giac.jl defines four core types for working with GIAC:

classDiagram
    class GiacExpr {
        +Ptr~Cvoid~ ptr
        +finalizer()
        +show()
        +getproperty()
    }

    class GiacContext {
        +Ptr~Cvoid~ ptr
        +ReentrantLock lock
        +finalizer()
    }

    class GiacMatrix {
        +Ptr~Cvoid~ ptr
        +Int rows
        +Int cols
        +finalizer()
        +getindex()
    }

    class GiacError {
        +String message
        +Symbol category
    }

    GiacExpr --> GiacContext : uses
    GiacMatrix --> GiacExpr : contains

GiacExpr

The primary type representing a GIAC expression. Wraps a pointer to a C++ giac::gen object.

mutable struct GiacExpr
    ptr::Ptr{Cvoid}
end

• Automatic memory management: Uses Julia's finalizer to free C++ memory
• Method-style syntax: Supports expr.factor() which translates to giac_cmd(:factor, expr)
• Display: Implements show for text and LaTeX output

GiacContext

Evaluation context managing computation state.

mutable struct GiacContext
    ptr::Ptr{Cvoid}
    lock::ReentrantLock
end

• Thread safety: Contains a ReentrantLock for concurrent access
• Configuration: Holds computation settings (precision, assumptions, etc.)

GiacMatrix

Symbolic matrix type with dimension tracking.

mutable struct GiacMatrix
    ptr::Ptr{Cvoid}
    rows::Int
    cols::Int
end

• Indexing: Supports m[i,j] returning a GiacExpr
• Construction: Can be created from Julia arrays or symbolically

GiacError

Exception type for GIAC-related errors.

struct GiacError <: Exception
    message::String
    category::Symbol  # :parse, :eval, :type, :memory
end

Data Flow

A typical function call flows through the package like this:

flowchart LR
    A["User: sin(x)"] --> B{GiacExpr?}
    B -->|Yes| C[command_utils.jl]
    B -->|No| D[Julia Base]
    C --> E{Tier 1?}
    E -->|Yes| F["wrapper.jl (_giac_sin_tier1)"]
    E -->|No| G[giac_cmd]
    F --> H[C++ wrapper]
    G --> I[String evaluation]
    H --> J[libgiac]
    I --> J
    J --> K["Result: GiacExpr"]

File Dependencies

Understanding which files depend on which helps when making changes:

graph TD
    A[types.jl] --> B[wrapper.jl]
    A --> C[operators.jl]
    B --> D[api.jl]
    B --> E[command_utils.jl]
    D --> F[macros.jl]
    E --> G[Commands.jl]
    H[command_registry.jl] --> E
    H --> I[namespace_commands.jl]

    K[Giac.jl] --> A
    K --> B
    K --> C
    K --> D
    K --> E
    K --> F
    K --> G
    K --> H
    K --> I

Where to Make Changes

See Also

• Performance Tiers - Deep dive into the tier system
• Adding Functions - Step-by-step contribution guide
• Memory Management - How memory is managed