A symbolic variable representing a dimension.

Variables have unique identities (compared by ID, not name or bounds) and mutable bindings that persist until changed. Each call to var creates a fresh variable even if the name is reused. Variables track minimum and maximum bounds to validate runtime values.

A dimension is an expression.

Dimensions may be static constants, symbolic variables, or arithmetic combinations. Use static for constants, dim_of_var for variables, and add, mul, neg for arithmetic.

A shape is an array of dimensions.

Shapes are immutable arrays representing the dimensions of multi-dimensional tensors. Operations return new shapes without modifying originals. Each element is a dimension expression that may contain symbolic variables. Empty shapes represent scalars (rank-0 tensors).

static n creates a static dimension with value n.

Static dimensions have fixed values known at creation time.

• raises Invalid_argument

  if n < 0.

dynamic name ~min ~max creates a dynamic dimension with bounds.

Creates a fresh symbolic variable and converts it to a dimension expression. Equivalent to dim_of_var (var name ~min ~max). The variable can be bound to any value in the range [min, max] at runtime.

• raises Invalid_argument

  if min < 0 or min > max.

var name ~min ~max creates a fresh symbolic variable.

Each call returns a distinct variable with a unique identity, regardless of name. Names are used for debugging and display purposes only. Variables remain unbound until explicitly assigned with bind.

The bounds [min, max] constrain valid runtime values.

• raises Invalid_argument

  if min < 0 or min > max.

dim_of_var var wraps a variable as a dimension expression.

of_ints arr creates a shape with all static dimensions.

Each element of arr is converted to a static dimension using static. This is the standard way to create concrete shapes.

• raises Invalid_argument

  if any element of arr is negative.

of_list lst creates a shape with all static dimensions.

Equivalent to of_ints (Array.of_list lst).

• raises Invalid_argument

  if any element of lst is negative.

add d1 d2 creates a dimension expression d1 + d2.

Constructs an Add expression representing the sum of two dimensions. Useful for expressing padding or concatenation dimensions.

mul d1 d2 creates a dimension expression d1 * d2.

Constructs a Mul expression representing the product of two dimensions. Useful for expressing flattened or tiled dimensions.

neg d creates a dimension expression -d.

Constructs a Neg expression representing the negation of a dimension. Rarely used directly; primarily for internal expression manipulation.

bind var value shape binds value to var globally and updates all occurrences of var in shape by identity.

Performs a global mutation of the variable's mutable state. The shape is traversed to find all instances matching var by identity, including those within compound expressions. The binding persists until changed.

Variables must be bound before shapes can be evaluated to concrete dimensions. Binding is checked against the variable's min and max bounds specified at creation.

Time complexity: O(n) where n is the total size of all expression trees in the shape.

• raises Invalid_argument

  if value is outside the variable's bounds.

eval shape returns concrete shape if all dimensions are bound.

Evaluates all dimensions in shape to produce an integer array. Returns Some arr if all symbolic variables are bound and all expressions can be computed. Returns None if any dimension contains an unbound variable.

This is the primary way to extract concrete shapes for backend operations.

eval_dim dim evaluates a single dimension.

Returns Some n if dim is fully bound and can be evaluated to a concrete value. Returns None if dim contains unbound variables.

Evaluates arithmetic expressions by depth-first recursion without memoization, evaluating subexpressions and applying the corresponding operations.

partial_eval shape returns an array of evaluated dimensions.

Evaluates each dimension independently, returning Some n for bound dimensions and None for unbound dimensions. Unlike eval, this succeeds even when some dimensions remain symbolic.

Useful for debugging and displaying partially bound shapes.

is_fully_bound shape returns true if all dimensions are bound.

Checks whether every symbolic variable in shape has been assigned a value. Static dimensions are always considered bound. Returns true if eval shape would succeed.

numel shape returns the total number of elements if shape is fully bound.

Computes the product of all dimensions if the shape can be fully evaluated. Returns Some 1 for empty shapes (scalars). Returns None if any dimension contains unbound variables.

Special dimension value representing "infer from context".

Equivalent to -1 in NumPy reshape operations. Use this in target shapes to indicate that a dimension should be computed from the total element count. At most one dimension in a shape may be infer; this constraint exists because multiple unknowns make element count calculation ambiguous. The constraint is enforced at runtime by resolve_reshape.

The resolve_reshape function computes the concrete value for inferred dimensions based on the source shape's element count.

is_infer dim returns true if dimension should be inferred.

Checks whether dim evaluates to -1, indicating it should be computed from context during reshape operations. Returns false for unbound variables, which cannot be evaluated to -1.

resolve_reshape ~from_shape ~to_shape resolves a reshape operation with inference.

Computes concrete dimensions for infer values in to_shape based on the element count of from_shape. At most one dimension in to_shape may be infer.

Returns Some resolved_shape if:

• from_shape is fully bound (all dimensions have concrete values)
• to_shape contains zero or one infer dimensions
• The total elements of from_shape divides evenly by known dimensions in to_shape

Returns None if:

• from_shape contains unbound variables
• Element count doesn't divide evenly (i.e., total_elements mod known_product != 0)

Examples

Resolving a reshape with one inferred dimension:

  let from_shape = Symbolic_shape.of_ints [| 2; 3; 4 |] in
  let to_shape = [| Symbolic_shape.static 6; Symbolic_shape.infer |] in
  match Symbolic_shape.resolve_reshape ~from_shape ~to_shape with
  | Some resolved -> assert (Symbolic_shape.eval resolved = Some [| 6; 4 |])
  | None -> ()

• raises Invalid_argument

  if to_shape contains multiple infer dimensions or any dimension evaluates to an invalid size (zero or negative).

substitute bindings shape substitutes variable bindings into shape.

Replaces variables in shape with their corresponding values from bindings, creating a new shape with Const nodes where variables were substituted. Variables not present in bindings remain as Var nodes. Unlike bind, this creates a new shape without mutating variable state.

Binding list format: (var, value) pairs where var is matched by its unique identity (not by name).

Useful for creating multiple specialized versions of a parametric shape without side effects.

vars shape returns all unique symbolic variables in shape.

Extracts all distinct variables from dimension expressions. Variables are compared by identity, so the same variable object appears only once even if used in multiple dimensions or compound expressions.

Returns an empty list for shapes containing only static dimensions. The order of variables in the result is unspecified.

var_id v returns the unique identifier assigned to v.

var_name v returns the user-facing name of v.

var_bounds v returns the inclusive minimum and maximum bounds for v.

is_static shape returns true if all dimensions are static.

Checks whether shape contains only Const expressions with no symbolic variables. Static shapes can be evaluated without binding variables.

Returns true for empty shapes.

rank shape returns number of dimensions.

to_string shape returns human-readable representation.

Formats the shape as a bracketed list of dimension expressions. Static dimensions appear as integers. Variables show as name#id or name#id=value if bound. Empty variable names render as v{id}. Compound expressions use infix notation with parentheses.

equal s1 s2 compares shapes structurally.

Returns true if s1 and s2 have the same rank and corresponding dimensions are structurally equal. Dimensions are compared by:

• Constants: Equal if values match
• Variables: Equal if variable identities match (not names)
• Expressions: Equal if operators and subexpressions match recursively

Two shapes with different but equivalent variables are not equal:

  let v1 = Symbolic_shape.var "x" ~min:0 ~max:10 in
  let v2 = Symbolic_shape.var "x" ~min:0 ~max:10 in
  let s1 = [| Symbolic_shape.dim_of_var v1 |] in
  let s2 = [| Symbolic_shape.dim_of_var v2 |] in
  assert (not (Symbolic_shape.equal s1 s2))
  (* Different identities *)

Performs structural comparison without evaluation; expressions that evaluate to the same value may not be equal. For example, Add (Const 1, Const 2) is not equal to Const 3.

Time complexity: O(n*m) where n is shape size and m is average expression tree depth.