Aleph Naming Conventions
Aleph names follow a small set of conventions. These conventions make it easier to tell whether a name refers to a value, a function, a type, a constructor, or a factory.
For the language basics behind these examples, see Aleph 101.
At a Glance
| What you are naming | Convention | Examples |
|---|---|---|
| Values, constants, functions, and methods | snake_case | num_sites, make_hamiltonian, set_random |
| Types and constructors | PascalCase | ExperimentResult, RealMatrix, Distribution, MapPair("k", 6) |
| Factories and helper functions | snake_case | matrix, zeros_like, state_vector |
| Primitive conversion functions | lower-case primitive type name | integer("42"), real("3.14") |
| Type specifiers and type tags | as_<name> | as_real, as_matrix, as_complex |
| Options map keys and preset names | lower snake_case strings | "is_hermitian", "uniform_real" |
| Physics operators | Literature notation | X, CNOT, SWAP, Splus, RotX |
User-Defined Names
Use snake_case for local variables, global variables, constants, functions, and methods:
var num_sites = 10
global default_tolerance = 1e-12
def make_hamiltonian(num_sites, coupling_strength) {
return coupling_strength * ZN([0..num_sites])
}
This matches the way Aleph names most public functions and methods:
var values = [4, 2, 5, 1]
values.sort()
values.push_back(10)
values.type_name()
Use PascalCase for classes and constructors:
class ExperimentResult {
var energy
def ExperimentResult(real value) {
this.energy = value
}
def shifted_energy(real offset) {
return this.energy + offset
}
}
var result = ExperimentResult(-1.25)
Valid Identifiers and Reserved Names
A standard Aleph identifier starts with a letter or underscore (_) and then contains letters, digits, or underscores.
var x = 1
var x2 = 2
var _temporary_value = 3
Prefer descriptive names over leading underscores in ordinary user code. Keywords like def, var, class, if,
return, etc. are reserved and cannot be used as identifiers.
Aleph also has backtick identifier literals for unusual names, but they are an escape hatch. Avoid them in normal code and in public APIs.
Types and Constructors
Aleph uses PascalCase for all type names. This includes user-defined classes, concrete Aleph types like RealMatrix,
and base types shown in the library reference, such as Distribution:
def multiply(RealMatrix a, RealMatrix b) {
return a * b
}
A constructor also uses PascalCase and matches the type being created:
var pair = MapPair("k", 6)
var timer = Timer()
var obj = DynamicObject()
Type Families and Base Types
A type family is a group of related concrete types with a shared purpose and common operations. For example,
RealMatrix and ComplexMatrix are both matrix types: they differ in scalar type, but they support matrix-style
operations.
When the library reference lists a base type, that type can be used when code only depends on shared behavior. For
example, Distribution can be used in a function signature when any distribution object is acceptable:
def sample_positive(Distribution dist) {
return dist.sample() > 0
}
Here Distribution accepts any distribution object with the shared distribution behavior, such as a normal, Bernoulli,
or uniform distribution.
Factories and Customization Names
Use a snake_case factory when a function creates one member of a broader family, chooses a concrete representation, or
acts as a convenient helper:
var dense = matrix([[1, 2], [3, 4]], as_real)
var same_shape = zeros_like(dense)
var state = state_vector(as_real | as_fermion, ["num_sites" : 10])
Factories keep user code focused on intent. For example, matrix(...) says that the result should behave like a matrix,
while type specifiers choose details such as scalar type or storage.
Primitive conversion functions like integer(...) and real(...) follow the same pattern — they are named after the
lower-case primitive type they produce:
var n = integer("42")
var x = real("3.14")
Type specifiers are constants named as_<name>. They select type-family details such as scalar domain, container
semantics, storage, or physical interpretation. Combine specifiers with |:
var real_grid = zeros([3, 4], as_array | as_real)
var complex_eye = identity([3, 3], as_matrix | as_complex)
var fermion_state = state_vector(as_fermion | as_number | as_real, ["num_sites" : 10, "number" : 5])
Options are passed with Aleph maps. Use lower snake_case strings for option keys:
var m = matrix([[1,2],[3,4]], as_real)
var results = eigensolver(m, ["is_hermitian" : true])
var oblique = lattice("oblique", [3, 3], ["a" : 1.2, "b" : 2.2, "theta" : 0.25*pi])
Factories that select from named presets also use lower snake_case strings:
var square = lattice("square", [10, 10])
var normal = random_distribution("normal", ["mean" : 0.0, "stddev" : 1.0])
var uniform = random_distribution("uniform_real", ["a" : -1.0, "b" : 1.0])
Physics Operator Names
Physics and quantum-computing operators are the main intentional exception to the general constructor and factory style. Their names follow common notation from the literature when that notation is clearer than strict casing:
var h = Z(0) * Z(1) + X(0)
var swap = SWAP(0, 1)
var rotation = RotX(pi / 2, 0)
var raising = Splus(0)
These names are still public constructors or factories, but readability in formulas takes priority. When adding ordinary non-operator APIs, prefer the standard conventions above.