Skip to main content

Types, Factories, and Options

At a Glance​

  • Most aleph types can and should be built via factories.
  • A typename is always in camel case, (e.g. StateVector).
  • A factory is always in snake case, (e.g. StateVector is built with state_vector).
  • Factories provide a single entry point for groups of related types (like state vectors and matrices).
  • Modifying the return type is done via constants of the form as_<name>, (e.g. matrix([[2,2]], as_real)).
  • Preset objects can be made by name, (e.g. lattice("square", [10,10]))
  • Optional keyword arguments are passed via a Map (e.g. lattice("square", [10,10], ["a" : 1.2]))

Summary and Conventions​

A key advantage of aleph is that it provides users a degree of type safety. If a value is declared as an integer, aleph will warn you if you try to use it as a float. Non-primitive types often fall into groups. For example, a matrix could be a matrix of real values or a matrix of complex values. Some types, like StateVector, can have many specializations depending on the type of the coefficients, the storage preference, and the algebra of the underlying degrees of freedom. Aleph provides users with factory functions that should be thought of as entry points into a particular group of types.

Type Specification​

Factory functions always return objects that share a common interface. For example, all the values returned by state_vector share a common interface, as do all the objects returned by lattice. The objects returned by state_vector, however, can be further specified into subtypes that enforce type safety. After all, we wouldn't want to mistake a fermionic state for a bosonic one. This kind of type specification is provided by special constants called specifiers that always follow the pattern as_<name>. To elaborate on the above example, we can produce different subtypes of StateVector via

var spinhalf_sparse = state_vector(10, as_sparse | as_spinhalf)
var real_fermi = state_vector(10, as_real | as_fermi)

The return type of state_vector is, in both cases, a subtype of StateVector, but spinhalf_sparse is further specified to be a sparse representation spin-1/21/2 state, where real_fermi is specified to have real coefficients and represent a fermionic state.

Preset Attribute Specification​

Some factories, like lattice don't need further type specification. They do, however, come with a number of preset options for the user's convenience. For example,

var my_squares = lattice("square", [10,2])
var my_triangles = lattice("triangular", [4,4])

Saves the user the trouble of having to type out the primitive vector definitions. Another example is in the production of a Distribution of random values,

var bernoulli = random_distribution("bernoulli")

Where the preset attribute specifier "bernoulli" returns a subtype of Distribution containing specialized methods for accessing the attributes specific to a Bernoulli distribution.

Optional Arguments​

Many functions in aleph take keyword options. These are always provided via an aleph Map (dictionary). For example,

var oblique = lattice("oblique", [3,3], ["a" : 1.2, "b" : 2.2, "theta" : 0.25*pi])

Documentation Contributors

James Lambert