Built-in Reference¶

This page lists all dimensions, units, constants, and functions provided by the Graphcal prelude. These are available in every .gcl file without any import declarations.

The set of bare-callable functions is closed: user code cannot add to it. Externally-provided functions are declared with import plugin blocks and called qualified through their alias — see Extern Functions (Plugins).

Built-in Constants¶

Built-in Functions¶

Math Functions¶

The rounding functions (round, trunc, floor, ceil) reject dimensioned arguments: "round to an integer" has no unit-independent meaning for a physical quantity -- an integer number of meters is not an integer number of centimeters. To round a quantity, divide by an explicit granularity, round the dimensionless ratio, and scale back:

// Round down to whole centimeters.
node whole_cm: Length = floor(@x / 1.0 cm) * 1.0 cm;

Complex Functions¶

Complex<D> is the built-in complex type over dimension D. Both components are stored in SI base units and must have the same dimension. Construction is explicit; there is no a + bi literal syntax.

node displacement: Complex<Length> = complex(3.0 m, 4.0 m);
node same_polar: Complex<Length> = polar(5.0 m, 53.130102 deg);
node magnitude: Length = abs(@displacement); // 5 m
node direction: Angle = phase(@displacement);
node shifted: Complex<Length> = @displacement + to_complex(1.0 m);

polar rejects a negative magnitude instead of silently rotating the phase by π. Arithmetic and complex function results must remain finite. Complex division by zero is an evaluation error. See Complex Arithmetic for the mixed real/complex operation matrix.

Trigonometric Functions¶

Hyperbolic Functions¶

Selection Functions¶

These selectors always take exactly two values. To reduce an indexed value, use minimum(values) or maximum(values) instead.

Type Conversion Functions¶

to_int never chooses a rounding policy implicitly. Apply trunc, floor, ceil, or round before converting when that is the intended policy:

node exact: Int = to_int(3.0);
node toward_zero: Int = to_int(trunc(3.7));
node nearest: Int = to_int(round(3.7));

Integrality is checked on the represented binary64 value. A conversion cannot detect precision that was already lost while computing that value.

Index Key Functions¶

These functions construct and consume index keys of type Key<I>. C is a coordinate axis over dimension D; c is a static Nat constant; e is a runtime Int; q is a quantity of dimension D.

Named axes need no former — a qualified label such as Maneuver.Departure is itself a constant of type Key<Maneuver> — and have no extraction: a named key is opaque apart from equality and match. There is no exact quantity-to-key cast for coordinate axes; select a grid point with an explicit search policy instead.

index TimeStep = range(0.0 s, 10.0 s, step: 0.1 s);

param event_time: Time = 3.47 s;
node before_event: Key<TimeStep> = floor_key(TimeStep, @event_time);
node event_coord: Time = coord(@before_event);

param readings: Pressure[Fin(8)] = for i: Fin(8) { 100.0 Pa };
param requested: Int = 5;
node channel: Key<Fin(8)> = fin_key(Fin(8), @requested);
node selected: Pressure = @readings[@channel];

Datetime Functions¶

Constructors¶

Each constructor has exactly one interpretation source:

• one-argument datetime requires Z or a numeric offset;
• timezone-based datetime requires local civil coordinates with no embedded offset, timezone, or time-scale suffix;
• epoch<S> requires local calendar coordinates with no embedded offset, timezone, or time-scale suffix, and S must be one supported bare time scale.

Datetime literals are parsed during checking. Invalid calendar dates and missing or contradictory interpretation sources are compile errors, not runtime failures. Local civil times are also resolved against Graphcal's bundled tzdb during checking: nonexistent times in DST gaps and repeated times in DST folds are rejected rather than shifted or selected silently. To choose a specific instant, use one-argument datetime with an explicit numeric offset. The obsolete positional form epoch("...", TT) is rejected; write epoch<TT>("...").

Time Scale Conversions¶

Numeric Conversions¶

Extraction Functions¶

All calendar extractors use the input's declared time scale. For example, hour(epoch<TT>("2024-11-05T12:00:00")) is 12, even though the same instant has a different UTC coordinate. A display timezone applied with -> remains formatting metadata and does not change extractor results.

Datetime Domain Constraints¶

Datetime<S> supports inclusive min: and max: constraints. Bounds are compile-time constants and must have exactly the constrained time scale:

param event: Datetime<TT>(
    min: epoch<TT>("2025-01-01T00:00:00"),
    max: epoch<TT>("2025-12-31T23:59:59"),
) = epoch<TT>("2025-06-01T12:00:00");

Cross-scale bounds require an explicit conversion such as to_tt(datetime("...Z")). Constraints apply element-wise to indexed datetime values and to constrained algebraic payload fields. See Type System — Domain Constraints.

Timezone Display¶

The -> operator can display a datetime in a specific timezone without changing the underlying value:

node meeting_ny: Datetime = @meeting -> "America/New_York";

Quoted timezone spellings are contextual TimezoneLiterals, not first-class String values. They are validated and canonicalized while the program is checked, then carried through compilation and evaluation as opaque IANA identifiers.

Timezone construction, validation, and display all use the same IANA timezone database bundled with the Graphcal toolchain. Graphcal never consults the host's zoneinfo installation, so a given Graphcal release resolves timezone rules identically across supported platforms. Invalid-timezone diagnostics report the bundled IANA tzdb release; updating those rules is an explicit Graphcal dependency update.

Aggregation Functions (Indexed Values)¶

These functions operate on rank-one for comprehensions or indexed values. D is a quantity dimension; T may be any non-indexed value type.

argmax and argmin return the extremum's location as an index key rather than its value, so the result can re-index the source or any other value on the same axis. Because axes are never empty and ties are deterministic, the identity @x[argmax(@x)] == maximum(@x) always holds:

index Maneuver = { Departure, Correction, Insertion };
param delta_v: Velocity[Maneuver] = {
    Maneuver.Departure: 2.46 km/s,
    Maneuver.Correction: 0.12 km/s,
    Maneuver.Insertion: 1.83 km/s,
};
param fuel_margin: Dimensionless[Maneuver] = {
    Maneuver.Departure: 1.1,
    Maneuver.Correction: 1.2,
    Maneuver.Insertion: 1.3,
};

node critical: Key<Maneuver> = argmax(@delta_v);
node critical_dv: Velocity = @delta_v[@critical];        // 2.46 km/s
node critical_margin: Dimensionless = @fuel_margin[@critical];

product makes chained reductions explicit without deeply nested binary multiplication. A dimensioned product requires a concrete axis cardinality so its output exponent is known; a dimensionless product does not. rss is the unit-safe quadrature operation for uncertainty budgets and Euclidean component combinations, and avoids avoidable intermediate overflow/underflow. Keep a budget's deterministic means and statistical sigmas as separate values, then combine each according to its semantics:

index BudgetLine = { Structure, Payload };
param means: Mass[BudgetLine] = {
    BudgetLine.Structure: 100.0 kg,
    BudgetLine.Payload: 50.0 kg,
};
param sigmas: Mass[BudgetLine] = {
    BudgetLine.Structure: 3.0 kg,
    BudgetLine.Payload: 4.0 kg,
};
node budget_mean: Mass = sum(@means);   // 150 kg
node budget_sigma: Mass = rss(@sigmas); // 5 kg

Convert a count explicitly when quantity arithmetic needs a dimensionless scalar: sum(@values) / to_float(count(@values)). Direct multi-axis aggregation is rejected; reduce one selected axis at a time with an explicit for, such as product(for row: Row { product(for column: Column { @a[row, column] }) }).

Frame-Tagged Vectors and Attitudes¶

Reference frames are project-specific nominal types, so Graphcal does not provide global Eci, Body, or similarly named frame values. Define the frames and wrappers in project vocabulary, then use the array linear-algebra built-ins for their numeric kernels:

type Eci { Eci }
type Body { Body }
type Vec3<D: Dim, Frame: Type> { Vec3(x: D, y: D, z: D) }
type Rotation<From: Type, To: Type> {
    Rotation(elements: Dimensionless[Fin(3), Fin(3)])
}
type Quaternion<From: Type, To: Type> {
    Quaternion(w: Dimensionless, x: Dimensionless, y: Dimensionless, z: Dimensionless)
}

node r: Vec3<Length, Eci> = Vec3<Length, Eci>(x: 1.0 m, y: 2.0 m, z: 3.0 m);
node q: Quaternion<Eci, Body> =
    Quaternion<Eci, Body>(w: 1.0, x: 0.0, y: 0.0, z: 0.0);

The phantom Frame / From / To arguments prevent accidental frame reinterpretation at type-check time. The linear_algebra_ergonomics.gcl fixture demonstrates an explicit matrix-vector frame transition. Projects can package numeric component operations in reusable DAGs with required type-level inputs; see DAG Blocks.

Linear Algebra (Indexed Quantities)¶

Linear-algebra built-ins operate on rank-one vectors and rank-two matrices. Axes are part of the type and contractions require the same typed axis, not merely the same number of entries. Fin(N) axes match structurally; named axes match by their declaration identity.

param A: Length[Fin(2), Fin(3)] = table[Fin(2), Fin(3)] {
    1.0 m, 2.0 m, 3.0 m;
    4.0 m, 5.0 m, 6.0 m;
};
param B: Dimensionless[Fin(3), Fin(2)] = table[Fin(3), Fin(2)] {
    7.0, 8.0;
    9.0, 10.0;
    11.0, 12.0;
};

node AB: Length[Fin(2), Fin(2)] = matmul(@A, @B);
node A_t: Length[Fin(3), Fin(2)] = transpose(@A);

There is no implicit axis selection or broadcasting. For example, matmul always contracts the second axis of its first argument with the first axis of its second argument. Distinct named axes with equal cardinality are rejected.

solve and inverse use scaled partial-pivoting LU, reject singular or numerically ill-conditioned matrices, and verify the residual before returning a result. These failures are explicit evaluation errors; they never return NaN or infinity. det remains defined for singular matrices and returns zero. Because a determinant's physical dimension is D raised to the matrix order, det requires a concrete axis cardinality.

Prelude Base Dimensions¶

Prelude Derived Dimensions¶

Prelude Units¶

Length¶

Time¶

h is the only prelude spelling for the hour unit; hour(value) remains the datetime extractor.

Mass¶

Temperature¶

Electric Current¶

Amount of Substance¶

Luminous Intensity¶

Angle¶

Force¶

Energy¶

Power¶

Pressure¶

Frequency¶