the magma algebra system i: the user language

J. Symbolic Computation (1997) 24, 235–265

The Magma Algebra System I: The User Language†

WIEB BOSMA‡, JOHN CANNON§ AND CATHERINE PLAYOUST¶

Computational Algebra Group, School of Mathematics and Statistics,The University of Sydney, NSW 2006, Australia

In the first of two papers on Magma, a new system for computational algebra, wepresent the Magma language, outline the design principles and theoretical background,and indicate its scope and use. Particular attention is given to the constructors forstructures, maps, and sets.

c© 1997 Academic Press Limited

1. Introduction

Magma is a new software system for computational algebra, the design of which isbased on the twin concepts of algebraic structure and morphism. The design is intendedto provide a mathematically rigorous environment for computing with algebraic struc-tures (groups, rings, fields, modules and algebras), geometric structures (varieties, specialcurves) and combinatorial structures (graphs, designs and codes).

The philosophy underlying the design of Magma is based on concepts from UniversalAlgebra and Category Theory. Key ideas from these two areas provide the basis for a gen-eral scheme for the specification and representation of mathematical structures. The userlanguage includes three important groups of constructors that realize the philosophy insyntactic terms: structure constructors, map constructors and set constructors. The util-ity of Magma as a mathematical tool derives from the combination of its language withan extensive kernel of highly efficient C implementations of the fundamental algorithmsfor most branches of computational algebra. In this paper we outline the philosophy ofthe Magma design and show how it may be used to develop an algebraic programmingparadigm for language design. In a second paper we will show how our design philoso-phy allows us to realize natural computational “environments” for different branches ofalgebra.

An early discussion of the design of Magma may be found in Butler and Cannon(1989, 1990). A terse overview of the language together with a discussion of some of theimplementation issues may be found in Bosma et al. (1994).

† This research was supported in part by the Australian Research Council.‡ E-mail: [email protected]§ E-mail: [email protected]¶ E-mail: [email protected]

0747–7171/97/030235 + 31 $25.00/0 sy960125 c© 1997 Academic Press Limited

236 W. Bosma et al.

2. The Magma Philosophy: Design Criteria

The process of designing a computer algebra system involves choosing a mathematicalviewpoint and then selecting one or more programming language paradigms (procedural,functional, rewrite rule-based etc). A given system will be based on a particular viewpointchosen from among the many different ways of looking at an area of mathematics. Notonly are different approaches evident in different branches, but even within a singlebranch, quite different viewpoints often co-exist.

Modern algebra is characterized by the process of abstracting minimal sets of axiomssatisfied by some particular class of structures and then attempting to produce a clas-sification of the entire class of structures satisfying that axiomatic system. The internalstructure of an algebraic structure plays a central role in classification efforts. Importanttools are structure-preserving mappings (morphisms) and actions of structures.

The design of Magma is firmly rooted in this structural view of algebra. The fundamen-tal notions underlying the system design are those of algebraic structure and morphism.Having chosen a mathematical viewpoint, it is now appropriate to state a number ofmore specific criteria:

• The language should be “universal-algebraic” in the sense that its design philosophyshould strive to be equally appropriate for all branches of algebra and related fields.• Algebraic structures and their morphisms are to be first class objects.• The language should ensure that the specification of mathematical objects and

their attributes is precise and unambiguous. The semantics associated with eachobject definable in the language should be as close as possible to the standardmathematical interpretation.• The user language should support common mathematical notation as far as possible.• “Mathematical” data structures, such as sets, sequences and mappings, are used

rather than the more standard computer science data structures such as arrays,lists and trees.• Efficiency is a paramount concern.

In the following paragraphs we expand on some of these points.

Universality. A system design that provides a satisfactory computational environmentfor all areas of mathematics has not yet appeared, and for good reason: it is probablyimpossible. For example, an environment supporting computation in analysis, where theproblem of expression simplification is central, will differ very significantly from an en-vironment for constructive combinatorics where backtrack search is the main tool. Onthe other hand the many excellent systems developed for particular branches of math-ematics (KANT, LiE, PARI, Macaulay, Snappea etc) suffer from the disadvantage thatmany practical computations will involve the use of tools from neighbouring areas. Wehave chosen to design a system for an area of mathematics that is, hopefully, sufficientlybroad to encompass a large class of mathematical computations that rely heavily onalgebraic calculation, but which is sufficiently constrained that the adoption of a singlemathematical viewpoint will work equally well throughout the area.

First class status for structures. Since, operationally, algebraic structures and individual“elements” of a structure are each mathematical entities possessing properties which weseek to investigate, structures need to have first class status in an algebraic language.Thus, it should be as easy to define a polynomial ring R and perform operations on R

The Magma Algebra System I: The User Language 237

as it would be to define and perform arithmetic with a polynomial. This is in sharpcontrast to the approach taken in systems such as MACSYMA, REDUCE, Maple andMathematica which have adopted an “element-centred” model of algebra and providevirtually no support for structural computation.

Precision and the avoidance of ambiguity. The central notion here is that of “context”:the answer to mathematical questions (and indeed, their appropriateness) often dependsupon the context in which they are asked. As a simple example, consider the problemof factoring x3 − 1. At first sight this is an innocuous and appropriate question for asymbolic algebra package. Upon reflection, however, it is entirely unreasonable to expecta solution from any system without further context: if, “in the current context” x isan identifier with the integer 4 assigned to it, then evaluation should yield the answerx3 − 1 = 32 · 7. A computer algebra system would be able to decide that no “value”has been assigned to x yet, but ambiguities arise if it assumes next that x refers toa transcendental element: it will then have to decide over which structure to factor thepolynomial x3−1. One possible solution, often adopted by conventional symbolic algebrasystems in some form, is to make the notion of context explicit: the user specifies a contextin which computation is to be performed, so that a change of context changes the domainof computation. Serious drawbacks to this approach include the difficulty of computingsimultaneously in various structures, and the counterintuitive change of “meaning” ofobjects whenever the exterior context is changed. While such an approach may workfor elementary applications in which computation takes place in a single fixed structure,in more sophisticated algebraic computation, where objects of one structure interactwith those of another, it becomes difficult if not impossible. The solution chosen forMagma is to associate with every object its unique context, in the form of the “parentstructure” to which it belongs. It is impossible to define x3 − 1 in Magma without(explicitly) designating the structure to which it belongs. If, for example, it is defined tobe an element of the polynomial ring Z[x], factorization results in its factorization intoa product of irreducible polynomials over Z.

Efficiency. Since Magma is intended as a heavy-duty research tool, its fundamentalalgorithms need to be as fast as possible. The difficulties of achieving satisfactory speedof execution will be clear to anyone who has undertaken the development of mathematicalsoftware. Since the optimal choice of data structures is crucial for many algorithms, theimplementation of such algorithms in a high-level general algebraic language suffers thedrawback that the use of generic data structures rather than the optimal data structuresfor a given problem will often result in the loss of a considerable degree of efficiency. Thisis true regardless of whether the language is interpreted or compiled into some low-levellanguage such as C or Lisp. One approach to this problem is to install fundamental orparticularly time-critical algorithms in the C kernel. To avoid the cost of re-implementingevery relevant algebraic algorithm, the Magma internal system architecture makes itpossible for certain classes of specialist software written independently of Magma to beinstalled in the kernel at the cost of a modest amount of effort.

3. Theoretical Foundations

In order to produce a coherent design, we require a model of algebraic computationthat specifies the possible classes of objects that may be defined within the scheme, andallows the valid operators for a given class of objects to be recognized.

238 W. Bosma et al.

An essential prerequisite for mathematical rigour is a strongly typed system. Ideas fromUniversal Algebra and Category Theory have been used to develop a theory of formalalgebraic specification of data structures and their operations (Burstall and Gougen, 1981;Gougen, 1989). This work underpins semantic models for Computer Algebra systemssuch as AXIOM (Jenks and Sutor, 1992) that support strong typing. Recently, Hearn andSchrufer have used the theory of order-sorted algebras to develop a proposal for a stronglytyped language for the Computer Algebra system REDUCE (Hearn and Schrufer, 1995).This body of work is chiefly concerned with defining a satisfactory system of types in aparticular context and explicating the relationships between the different types.

While no description known to us of the semantics of algebraic computation seems to becompletely satisfactory, we have found that ideas from Universal Algebra and CategoryTheory provide a useful framework. Although the description of our model takes itsinspiration from these sources, the Magma notions of algebra, category and variety donot strictly adhere to the standard definitions. We use these concepts not only to developa theory of algebraic types and their representation, but also to identify operations thatare common to large classes of algebraic and geometric structures.

In the next sections we briefly outline the basic ideas of multi-sorted algebras andcategories in order to provide the reader with an understanding of the foundations ofthe Magma model. Our overview of universal algebra follows that of Meinke and Tucker(1992), and the reader is referred to this excellent exposition for a detailed account. Forthe notions of category theory we refer the reader to Mac Lane (1971).

3.1. multi-sorted algebras

To define multi-sorted algebras, we fix a non-empty set S of sorts. Although manyfamiliar algebraic structures may be described as single-sorted algebras, it will be conve-nient to consider multi-sorted algebras.

A multi-sorted algebra A consists of a family {As : s ∈ S} of non-empty sets As calledcarrier sets, together with a signature Σ; the signature identifies certain distinguishedelements of the carrier sets as well as the collection of allowable operations in A, and isformalized as follows. By S∗ we denote the (possibly empty) set of words in the elementsof S; by λ we will denote the empty word. A signature Σ is an S∗×S indexed collection ofsets {ΣAw,s, w ∈ S∗, s ∈ S}. For each sort S, the set ΣAλ,s ⊂ As consists of the constants ofsort s in A, while for each non-empty word w = s1 · · · sk and sort s the set ΣAw,s consistsof the operations σ:As1 × · · · × Ask → As, of arity k, with domain As1 × · · · × Ask andco-domain As.

We should therefore speak of “multi-sorted Σ-algebras”, but in the remainder of thissection the abbreviated term “algebras” will be used.

There are three standard constructions which, when applied to algebras, produce newalgebras. These are the subalgebra, quotient algebra and direct product constructions. Webriefly sketch their definitions. Let A and B be S-sorted algebras. Then a subalgebra Bof A is defined as follows:

(i) The carrier sets of B are subsets of the carrier sets of A: i.e., Bs ⊆ As, for s ∈ S.(ii) The constants of B are identical with those of A: i.e., ΣAλ,s = ΣBλ,s, for s ∈ S.(iii) The operations on B are obtained by restricting the operations on A to B: i.e.,

σB(b1, . . . , bn) = σA(b1, . . . , bn), for σ ∈ Σw,s, bi ∈ Bsi .


If B is a subalgebra of A then we write B ≤ A. The notion of a subalgebra leads to aconcept that is fundamental for computation: generating set. Let A be an algebra andlet X ⊆ A. Then

〈X〉A =⋂X⊆BB≤A

B

is the subalgebra generated by X ⊆ A. It is not hard to show that this intersection definesa subalgebra provided the intersection of carrier sets is non-empty. The statement that Ais generated by X ⊆ A is equivalent to 〈X〉A = A. Further, we say that A is finitelygenerated if and only if 〈X〉A = A, for some finite set X. The idea of a generating setprovides us with an extremely compact method of representing algebras: rather thanexplicitly listing the elements of carrier sets, we will describe them in terms of (usually)small sets of generators.

A (Σ-)congruence is an S-sorted family of equivalence relations on the carrier sets ofan algebra A which is compatible with the operations on A. Given a congruence ∼= onan algebra A, it is straightforward to define the quotient algebra Q = A/ ∼= of A withrespect to the congruence ∼= as follows (where [ ] denotes for any R the canonical mapR→ Q that sends an element of R to its class in Q):

(i) The carrier sets of Q are quotients of the carrier sets of A: i.e., Qs = As/ ∼=s, fors ∈ S.

(ii) The constants of Q are the classes containing constants from A:ΣQλ,s = {[c] : c ∈ ΣAλ,s}, for s ∈ S.

(iii) The operations on Q are obtained in the obvious way from those on A:σQ([a1], . . . , [an]) = [σA(a1, . . . , an)], for σ ∈ Σw,s, and ai ∈ Asi .

If A is an S-sorted Σ-algebra and ∼= is a Σ-congruence on A, then Q = A/ ∼= is also anS-sorted Σ-algebra.

The direct product of Σ-algebras A and B is the Σ-algebra P defined as follows:

(i) The carrier sets of P are direct products of the carrier sets of A and B: i.e., Ps =As ×Bs, for s ∈ S.

(ii) The constants of P are the products of corresponding constants, i.e., c(A×B)s =(cAs , cBs), for s ∈ S.

(iii) The operations on P are obtained componentwise, so for σ ∈ Σw,s, ai ∈ Asi , bi ∈Bsi : σP ((a1, b1), . . . , (an, bn)) = (σA(a1, . . . , an), σB(b1, . . . , bn)).

This construction is easily extended to products of arbitrary families of algebras.A (Σ-)homomorphism between algebras A and B is an S-indexed family of mappings

φ = {φs : As → Bs | s ∈ S}such that cB = φ(cA), for each constant symbol c, and

φs(σA(a1, . . . , an)) = σB(φs1(a1), . . . φsn(an))

for each operator σ. Related terms such as homomorphic image, Σ-isomorphism,Σ-endomorphism and Σ-automorphism are defined in the obvious manner. It is straight-forward to show that for a Σ-algebra A, the set End(A), resp. Aut(A), of all endomor-phisms, resp. automorphisms, of A forms a monoid, resp. group, under composition ofmappings.

240 W. Bosma et al.

A class K of algebras is said to be closed under the formation of subalgebras if, andonly if, whenever A ∈ K and B ≤ A, then B ∈ K. Similarly, we may define closureof a class K with respect to the formation of quotient algebras, direct products andhomomorphic images.

A class of Σ-algebras closed under the formation of subalgebras, direct products andhomomorphic images is called a variety. Such a class will also be closed under the for-mation of quotient algebras.

It turns out that varieties arise as classes of Σ-algebras with “the same operations”on them: algebras satisfying certain polynomial identities on (derived) operators. ByAlg(Σ, P ) we will denote the equational class of all Σ-algebras whose operations satisfythe relations specified by P .

A famous theorem by Birkhoff asserts that a class of (multi-sorted Σ-)algebras formsa variety if and only if it forms an equational class for some set of equations P .

Example: Commutative RingsWith the above notations we can describe commutative rings as single-sorted algebras asfollows, if we adopt the convention that for single-sorted algebras we abbreviate Σsn,s =Σn. The algebra consists of a non-empty carrier set R together with signature

Σ0 = {0, 1},Σ1 = {−},Σ2 = {+, ·},Σn≥3 = ∅.

Thus, commutative rings contain 0, 1 (it is convention to assume 0 6= 1), and allow theunary operation − for negation, as well as the binary operations + and ·.

Commutative rings form a variety, hence an equational class, which can be obtainedfrom the above Σ-algebra by imposing the equations that express their axioms, i.e.,

(x+ y) + z = x+ (y + z) (associativity of +)x+ 0 = x = 0 + x (identity for +)x+ (−x) = 0 = (−x) + x (inverse for +)x+ y = y + x (commutativity of +)(x · y) · z = x · (y · z) (associativity of ·)x · 1 = x = 1 · x (identity for ·)x · (y + z) = x · y + x · z (distributivity of · over +)x · y = y · x (commutativity of ·)

Semigroups, groups, abelian groups, and not-necessarily-commutative rings can be ob-tained as classes of algebras and as equational classes in a similar fashion by choosingthe appropriate subsets of constants, operations and equations from the above. Notethat fields will not form a single-sorted algebra this way, because the additional unaryoperation −1 of inversion is not everywhere defined on the carrier set.

Although many of the standard algebraic structures such as semigroups, rings andR-modules can thus be treated as single-sorted algebras, modelling computation requiresthe introduction of additional carrier sets and operations. For example, exponentiationof elements introduces the integers as a carrier set, membership testing introduces thebooleans, etc. The introduction of such subsidiary carrier sets can be accomplished neatlyby a process known as expansion (see Meinke and Tucker, 1992).


3.2. categories

In category theory, the concepts of similar algebraic structures and their structurepreserving mappings are formalized as follows. A category C consists of

(i) A collection ObC of objects.(ii) For each pair of objects A,B, a set Hom(A,B) of morphisms from A to B.

(iii) For each ordered triple A,B,C of objects of C, a composition map Hom(B,C) ×Hom(A,B)→ Hom(A,C).

The following conditions are required to hold:

• The sets Hom(A,B) are disjoint for distinct pairs of objects A,B.• Composition is associative.• For each object A, Hom(A,A) contains an identity morphism idA such that for all

objects B and all f in Hom(A,B) and g in Hom(B,A), idA ◦f = f and g ◦ idA = g.

Many familiar classes of algebraic structures and their mappings form categories; inparticular, every variety Alg(Σ, P ) forms a category. However, there exist categoriesthat are not varieties; for example, the category of fields (with the field homomorphismsbetween them) is not a variety, since fields are not even algebras.

A morphism of categories C and D is called a functor: it consists of a function F whichacts on objects C 7→ FC and on morphisms f 7→ Ff , such that Ff ∈ Hom(FA,FB) iff ∈ Hom(A,B), satisfying F idC = idFC and F (g ◦ f) = Fg ◦ Ff . An important class offunctors are the so-called forgetful functors, which simply forget some of the structure ofthe objects. Thus, the functors sending a field to the additive group of all its elements,and that of sending it to the multiplicative group of its non-zero elements, provide twoexamples of forgetful functors between the category of fields and that of abelian groups.As another example, the direct product construct that we encountered in the previoussection is a functor from C to C for various categories C.

A desirable property of varietal categories is the existence of free objects. In termsof algebras, a Σ-algebra F is free on the indexed family Xs of subsets is:Xs ↪→ Fs fora class of Σ-algebras C if and only if for any A ∈ C and any S-indexed family of mapsφs:Xs → As there exists a unique Σ-homomorphism ψ which agrees with φ on X, that is,such that ψs◦is = φs on Xs. In short, every Σ-homomorphism from X factors through F .

Existence of Free Algebras: Let C be a class of Σ-algebras that forms a variety. Thenthere exist free algebras in C, and up to isomorphism such a free algebra is charac-terized by its indexed family of generator cardinalities #Xs. In particular, in singlesorted varieties of algebras there exists an essentially unique free algebra for anypositive integer.

The existence of free algebras for varieties is a consequence of the left adjoint theorem(Mac Lane, 1971), which implies the existence of a left adjoint for the forgetful functorAlg→ Set in the case of a variety of single-sorted algebra; this left adjoint produces thefree algebra in Alg on the carrier set X.

Since algebraic varieties have such nice properties, we use them to model the “idealcase”. However, we do not restrict ourselves to working with categories belonging to

242 W. Bosma et al.

varieties. It usually turns out that the ideas developed for varietal categories can besuitably reinterpreted in the case of other structures.

We first use the varietal condition to provide us with a compact representation ofalgebras.

Existence of Generators: Let A be a member of a class of algebras C that forms analgebraic variety V . Then A possesses a generating set X. Moreover, A can beobtained as a quotient of a free algebra in C.

Since we are interested in morphisms between algebras, the fact that an algebra is definedin terms of generating sets allows us to use the Homomorphism Representation Theorem.

Homomorphism Representation Theorem: Let A be an algebra belonging to a va-riety. Then any homomorphism f of A is uniquely determined by the set {f(x) :x ∈ X}, where X is any generating set for A.

3.3. the magma model

The ideas developed in the previous sections provide the basis for developing a compu-tational model of algebraic structures. We begin by formalizing the notion of an algebraicstructure as a Σ-algebra. In order to avoid confusion with other notions of algebra, theterm magma will be used when referring to a Σ-algebra. (This name was introduced byBourbaki (Bourbaki, 1970), who defines a magma to be a set with a law of composition.†However, we will use it more generally to refer to a Σ-algebra.) We introduce a two-levelclassification of magmas in Magma:

(i) A class of magmas satisfying a set of identical relations P will be called a variety,written Var(Σ, P ).

(ii) A class of magmas belonging to the variety V and sharing a common “representa-tion” R will be called a category, written Cat(V,R).

The notion of variety permits the specification of generic functions, functions that areindependent of the representation of a magma and which, consequently, may be appliedto magmas belonging to any category in the variety. For example, the standard methodof constructing the normal closure of a subgroup of a group requires only arithmetic withgroup elements and the ability to determine whether an element lies in a subgroup. Somevarieties in Magma are groups (Grp), commutative rings (Rng), and modules (Mod).

At the level of category, a magma is realized in concrete form. Thus, the categoryto which a magma belongs determines the representation of its carrier sets. Associatedwith a category C belonging to the variety V = Var(Σ, P ) are functions implementingthe operations given by Σ. Non-defining operations that depend upon a knowledge of therepresentation R are also attached to C. Most categories in Magma have names consistingof (usually) three letters indicating the variety to which it belongs and usually three moreto distinguish the category; for example, RngMPol is the name in Magma for the categoryof multivariate polynomial rings. (Technically, RngMPol is a family of categories indexed

† “Un ensemble muni d’une loi de composition est appele un magma.” (Bourbaki, 1970), ch. 1, p. 1.


by the coefficient ring, but we will abuse terminology and refer to RngMPol and similarindexed families of categories as though they were single categories.)

Recall that a magma is said to be finitely generated if it possesses a finite generating set.Since the vast majority of commonly occurring algebraic structures are finitely generated,we do not sacrifice much by restricting our model to describe finitely generated magmas.The occasional infinitely generated magma can be handled by other means within thelanguage. Exceptions to the finitely generated paradigm are such notorious structures asthe field of real numbers, rings of Laurent series, etc.

We further note that structure algorithms for algebraic structures typically work withgenerating sets. Hence, wherever possible we will choose to represent magmas in termsof finite generating sets. The property of being freely finitely generated is in many casespreserved under taking substructures and forming direct products, whereas taking quo-tients or homomorphic images yields (finite) presentations. Since the word problem isunsolvable for many interesting varieties, computation in a finitely presented category isoften limited.

As we saw, free magmas exist within any class of magmas that form a variety; it willbe convenient to extend the notion of a free magma somewhat, to include “the largestpossible magma with the given parameters” in certain categories in which free objectsstrictly speaking do not exist. For example, within the category of matrix groups over afield F , the generalized free algebras are the general linear groups GL(n, F ), for positiveintegers n. We will then be able to create most magmas from a “free” magma in thissense using constructions such as substructure, quotient, homomorphic image and directproduct formation.

Many of the functions that create new (free) magmas will take existing magmas asparameters. Thus, for example, the creation of polynomial rings or of matrix groupsuses some form of recursion since they must be defined over a coefficient ring (magma).Indeed, these creation functions may be viewed as functors from certain categories ofring to other categories of group or ring.

The category to which a magma belongs determines:

• The representation of elements of the carrier sets.• The representation of carrier sets.• The operations that are allowed on elements of the magma.• The operations that are allowed on the magma.

The implementation of a category involves installing functions which perform the follow-ing tasks:

• Creation and deletion of magmas, their elements and their morphisms.• Creation and deletion of mappings and coercion operations involving the magmas.• The Σ-operations.• The representation-dependent operations associated with the magma.

The fundamental action in our language will be the application of an operator to somelist of objects. Let A be an S-sorted Σ-algebra and let

σA : As1 × . . .×Asn → As

be an operation belonging to ΣA. Suppose we attempt to apply σA to the argumentsb1, . . . , bn. This will involve four distinct steps:

244 W. Bosma et al.

(i) Test compatibility of sorts: That is, we must check that the sort corresponding to biis si for i = 1, . . . , n. If any of these tests fail, the operation is illegal.

(ii) Test compatibility of values: In the case of n-ary operations for n ≥ 2, it is necessaryto check that bi ∈ Asi for i = 1, . . . , n.

(iii) Locate the function that performs the operation σA. This is obtained from thecategory of A.

(iv) Invoke the function to evaluate σA(b1, . . . , bn).

Testing compatibility of sorts is what is usually referred to as type checking. A simpleinstance in which testing compatibility of values arises is in the evaluation of the ex-pression x ∗ y, where x and y are ring elements. The magma semantics insists that ringproducts may only be evaluated when both arguments belong to a common ring. In orderto determine compatibility of values efficiently, we need to know if x and y belong to acommon set.

We shall use the term type to mean a set of values. Any set constructible in theMagma language is ultimately defined in terms of one or more magmas. For simplicity,we restrict discussion to sets defined in terms of a single magma. As noted above, anarrow definition of a particular type of algebraic structure involves typically one or twocarrier sets. However, actual computation introduces many further carrier sets, such asthe set of integers, the power set of the magma, etc. The carrier sets that appear in theaxiomatic definition of an algebraic structure will be referred to as fundamental carriersets, while the expanded list required for computation will be referred to as ancillarycarrier sets. The ancillary carrier sets for a magma are the same for every category.Roughly speaking, the types to which a magma A gives rise are as follows:

• The carrier sets of A.• The set of all subalgebras of A.• The set of all ideals of A.• An n-order iterated power set of each of the above sets.

The situation is slightly more complicated than this since, as we shall subsequently see,Magma distinguishes between ordered and unordered sets, simple sets and multisets.

Thus, each possible set of values definable in the Magma language must arise as acarrier set associated with some magma. Hence, the types correspond precisely to thecollection of all possible carrier sets. In Magma the carrier sets associated with a givenmagma form a related set of types. Compatibility of sorts and compatibility of valuesmay be quickly determined if the pair 〈s,As〉 is associated with each object, i.e., its sortand the carrier set to which it belongs.

3.4. the constructors for magmas, elements, and mappings

In this section we discuss the language constructs for defining magmas and their ele-ments. The first issue concerns the form of representation adopted. Since our objectiveis to work with specific magmas we require a concrete realization of the carrier sets ofthe magma. Rather than try to design in the abstract, we look at the way in which thefundamental varieties of algebraic structures are realized. What do the actual elementsof carrier sets look like? While there are endless possibilities, it turns out that most ofthe computationally interesting categories of magmas arise as follows:


• As one of a small number of primitive magmas (e.g., the ring of integers).• As a set of mappings from one magma to another.• By means of generators and relations.• As substructures, quotient structures, extensions and direct products of magmas.

For example, the finite field GF(p3) can be specified by a single generator and a singlerelation over the prime field GF(p), which itself is a quotient of the integers. The bimoduleof m × n integral matrices is the set of linear transformations from the module Zm tothe module Zn. The latter modules are direct products of copies of Z.

We are now in a position where we can present a general mechanism for specifying amagma M . This involves two conceptual steps:

(i) The definition of an appropriate free magma F .(ii) The construction of the desired magma M from F by forming a succession of

substructures, quotient structures and extensions until M is obtained.

For each category, the implementer must install a function that creates the appropriatefree magma. The system provides standard constructors which, given any magma Mand a set X of elements belonging to M , construct either the substructure or quotientstructure defined by the submagma generated by X.

The above ideas lead to the following generic constructions for creating magmas:

• A free magma constructor.• A submagma constructor, which takes an existing magma M together with a set X

of elements of M and creates the submagma of M generated by X.• A quotient magma constructor, which takes an existing magma M together with a

set X of elements of M and creates the quotient of M by the ideal generated by X.• An extension constructor, which forms an extension of one magma by some other

magma (the form of this is rather dependent upon the variety to which the magmasbelong).

In addition to the above constructors we will need:

• An element constructor, for elements in a given magma.• A map constructor, to construct morphisms between given magmas.

Mappings play many roles in Magma and are an important programming tool. Justas in mathematics, they are used to represent the following kinds of associations betweensets and magmas:

• A natural relationship holding between two magmas (e.g., an embedding).• A general homomorphism between two magmas (possibly an endomorphism).• An action of magma A on magma B.• An association between two sets.

For example, if some structural invariant of a magma A is to be computed using adivide-and-conquer algorithm which replaces the computation in A by computations in(smaller) submagmas and quotient magmas of A then the natural morphisms relating the

246 W. Bosma et al.

submagmas and quotient magmas to A are used to pull back solutions of the subproblemsinto A.

We need to consider the problem of representing mappings. For a small set or magma Ait may be possible to represent a map f :A → B by listing all pairs (a, f(a)). In somesituations, it is possible to define a mapping by giving a rule for calculating the image ofa general element of the domain. However, both of these cases are the exception. Sincewe are mainly interested in morphisms between magmas, the fact that our magmas aredefined in terms of finite generating sets allows us to use the Homomorphism Represen-tation Theorem. Hence the constructor will require only the images of the generators ofthe domain.

3.5. coercion

In a strongly typed algebra system such as Magma, a particular magma M may beembeddable in one or more other magmas. This embedding may be essentially unique(e.g. Z in Q) or there may be a number of distinct possibilities (e.g. Q(α) in C). Sincefor most binary operations Magma requires both arguments to belong to a commonmagma, the user can soon become overwhelmed with the detail of continually havingto cast objects into a different magma (i.e., to change types). The design of Magmais organized so as to mitigate this by providing both automatic and forced coercion.Coercion is an operation that, given an element x of a magma M and some magma Nsuch that there is an interpretation of x in N , returns this “image” of x in N . Automaticcoercion will only be performed when there is a canonical relationship between M and N .Knowledge of the existence of such a relationship will be available to Magma in two setsof circumstances.

Firstly, as a submagma or quotient magma is created, Magma automatically notesthe relationship between the magmas and stores the associated morphism (that is, theinclusion homomorphism or the natural homomorphism onto a quotient) in its internaltables. When an attempt is made, say, to multiply two elements that are not already in thesame magma, the Magma processor will use this relationship information in attemptingto locate a common overstructure O which contains both elements. If one is found thenboth elements will be automatically cast as elements of O and the operation performed.Secondly, in certain situations where from convention or for mathematical reasons anunambiguous canonical map between M and N exists, this knowledge has been builtinto the Magma processor and automatic coercion will occur.

Forced coercion refers to the situation in which M does not have a unique and canonicalrelationship with N , but nevertheless an element x does have a natural image in N . Inthis case the user will have to apply forced coercion via N ! x. This occurs, for example,when only a subset of the elements of M have a natural interpretation in N .

4. The Magma Language

The Magma language is an imperative programming language having standard imper-ative style statements and procedures. The language has a functional subset providingfunctions as first class objects, higher order functions, partial evaluation, etc. We sum-marize and comment on some of the more interesting language elements in this chapter.

An object is specified in the Magma language by means of an expression. Expressionsare constructed in the usual manner through the application of operators, functions and


Table 1. Expressions.

Identifier Map constructor Cartesian product constructorLiteral Magma constructor Co-product constructorFunction invocation Element constructor Tuple constructorFunction/procedure definition Sequence constructor Record format constructorselect, case expressions Set constructor Record constructor

constructors to less complex expressions. The major kinds of expressions in Magmaare shown in Table 1. In contrast to many algebraic languages, any identifier appearingin a Magma expression must have a value. The type of an expression is inferred atrun-time from the types of its subexpressions. In general, Magma employs call-by-valueevaluation, in that it evaluates each subexpression before commencing the evaluation ofthe outermost expression.

Much of the power of the language derives from its constructors. These are basicallyfunctions with special syntax and semantics. Constructors are used to specify magmas,elements of magmas, mappings and aggregates (sets, sequences, products and records).They will receive particular attention in this survey, because of their novel nature andtheir importance to the language.

Before proceeding to the constructors, we note briefly that there are three classes ofidentifiers in Magma:

• variable identifiers: those identifiers which are declared as local, either implicitly bythe first use rule, or explicitly through a local declaration. They may be assignedvalues.• value identifiers: placeholders for values to be substituted during evaluation. They

are effectively constants, and may not be reassigned. The value identifiers are:

– the formal value arguments and parameters of a function or procedure.– all loop identifiers.– the pseudo-identifiers $ (“current” structure) and $$ (function/procedure being

defined by current expression).– all identifiers whose first use in the statement body of a function or procedure

is as a value (i.e., not on the left-hand side of a := symbol, nor as an actualreference argument to a procedure).

• reference identifiers: identifiers preceded by a tilde ∼ in a procedure definitionor invocation (page 260). A reference identifier in a procedure definition may beassigned a new value in the procedure. This will have the effect of changing thevalue of the corresponding reference identifier in the calling context.

4.1. magma constructors

4.1.1. free magma constructors

The standard model for many categories includes a constructor for free magmas. AsTable 2 below indicates, this is true not only for varietal categories (such as GrpFP) inwhich true free objects exist, but also in some other magma categories in which it isconvenient to create a magma from a general “free-like” object.

248 W. Bosma et al.

Table 2. Free magma constructors.

Category Constructor Magma

SgpFP FreeSemigroup(n) Free semigroup of rank nMonFP FreeMonoid(n) Free monoid of rank nGrpFP FreeGroup(n) Free finitely-presented group of rank nGrpAb FreeAbelianGroup(n) Free abelian group of rank nRngMPol PolynomialRing(R, n) Polynomial ring in n indeterminates over the ring RModFP FreeRModule(R, n) Free R-module of rank nAlgFP FreeAlgebra(R, M) Free associative algebra over the ring R and the monoid M

AlgMat MatrixAlgebra(R, n) Full matrix algebra of degree n over the ring RGrpPerm Sym(X) Symmetric group acting on the set XGrpMat GL(n, R) General linear group of degree n over the ring RModTup RModule(R, n) Free R-module of n-tuples

A free algebra is normally defined as a term algebra over some set of variables. Thenotion of a (term algebra) variable causes semantic problems in many computer algebrasystems since such a variable has different properties to an ordinary variable identifier.For this reason we avoid the notion of a (term algebra) variable or indeterminate inMagma. Rather, we use the notion of a generator. If F is a free algebra, the expressionF.i denotes the ith generator of F . Semantically, this is simply a particular element of F .(In cases where a free algebra has not been assigned to an identifier, the form $.i refersto its ith generator in certain contexts.) The expression F.i is called the standard namefor the ith generator of F ; the generator assignment statement allows the user to chooseidentifiers for the generators as well.

We consider two examples. In the first we construct the free group F of rank 3. Wewill use an assignment statement to assign the group to the identifier F .

> F := FreeGroup(3);> w := F.1^2*F.2*F.1*F.2^-1*F.3;> w;F.1^2 * F.2 * F.1 * F.2^-1 * F.3

It is usually desirable to be able to refer to generators by means of normal identifiers.Further, when elements of a free algebra are printed, we would like to see them presentedas strings in generator names. This is handled by a special form of the Magma assign-ment. Any constructor that defines a magma in terms of generators may have namesassigned to the generators by an assignment of the form

F<a1, . . . , an> := magma constructor;

This has the following effect. The magma F has stored, as part of its definition, the(ordered) set X = {x1, . . . , xn} of generators on which it is defined. When the aboveassignment is executed, two things happen. Firstly, the identifier ai is assigned the ithgenerator of F as its value, for i = 1, . . . , n. Secondly, when a word of F is printed, itwill be printed as a string in the symbols a1, . . . , an and their inverses. Note that any ofthese identifiers may be reassigned at any time. If ai is assigned a new value, this has noeffect on the generator that was its previous value. However, while ai will no longer refer


Table 3. The submagma, quotient and extension constructors.

sub< expr | expr1, ..., exprk > (semi)groups, fields, modules, codes, graphsncl< expr | expr1, ..., exprk > Groupsideal< expr | expr1, ..., exprk > Semigroups, ringslideal< expr | expr1, ..., exprk > Semigroups, algebrasrideal< expr | expr1, ..., exprk > Semigroups, algebras

quo< expr | expr1, ..., exprk > (semi)groups, rings, modules, graphs

ext< expr | expr1, ..., exprk > FieldsExtensionField< expr, idfr | expr1, ..., exprk > Finite fields

to xi, the name ai will still appear in words involving the generator xi. We illustrate thismechanism by continuing the previous example.

> F<a,b,c> := FreeGroup(3);> v := a^2*b*a*b^-1*c;> v;a^2 * b * a * b^-1 * c> w := F.1^2*F.2*F.1*F.2^-1*F.3;> v eq w;true

In our second example, we construct the full matrix ring of 2 × 2 matrices over theintegers. In the case of R-algebras, we may write down elements directly if we wish, sincewe have some concrete representation of their elements. Thus, the matrix

(1 23 4

)is created

by the second statement below:

> M := MatrixRing(Integers(), 2);> v := M ! [1, 2, 3, 4];> v;[1 2][3 4]

4.1.2. submagma, quotient and extension constructors

After a free magma is constructed, the desired magma will normally be obtained from Fby applying a sequence of submagma, quotient magma, and extension constructors.

The main form of the submagma constructor is sub< > as shown in Table 3. Givena magma M defined by an expression and a set Y of elements mi ∈ M defined byexpressions on the right-hand side, it creates the submagma of M generated by Y . Thus,a magma in the same category as that of M is constructed.

The ncl constructor applies to objects in the variety of groups, and constructs thenormal closure of the subgroup generated by the elements within the given group; againthe result lies in the same category as the original group.

The various (two-sided and one-sided) ideal constructors listed apply in certain semi-group, ring and algebra categories. Although the effect is slightly dependent on theparticular category, the effect is usually similar to that of any other sub, in the sensethat an “ideal” generated by the given elements is created within the same category;thus a sub-object closed under some action by the given magma is constructed, ratherthan an object of some “ideal”-type.

250 W. Bosma et al.

The quotient magma constructor quo has similar syntactic structure. There is an im-portant semantic difference: the quotient constructor may construct an object Q in acategory different from that of the original magma M .

The expressions on the right-hand side of both quo and sub are allowed to be moregeneral than simply defining elements of M : each expri may evaluate to an elementof M , a sequence defining an element of M , a submagma of M , an ideal of M , a setof elements of M , or a sequence of elements of M . Each term of the list defines one ormore elements mi of M , and Y is the set of all the mi. In the case where an expressionevaluates to a submagma or ideal, it contributes its generators to Y .

The quo constructor allows us to create any finitely presented algebra in a naturalmanner. For instance, the group G with presentation 〈c, d | c2, d3, (cd)4〉 can be createdas a quotient of the free group F of rank 2:

> F<a, b> := FreeGroup(2);> G<x, y> := quo< F | a^2, b^3, (a*b)^4 >;> G;GrpFP: G on 2 generatorsRelations

x^2 = Id(G)y^3 = Id(G)(x * y)^4 = Id(G)

> Generators(G);{ x, y }

The ternary Golay code, constructed as a six-dimensional subspace of K(11) where Kequals GF(3), provides an example of the use of the sub constructor.

> K11 := RModule(FiniteField(3), 11);> G3 := sub< K11 |> [1,0,0,0,0,0,1,1,1,1,1], [0,1,0,0,0,0,0,1,2,2,1],> [0,0,1,0,0,0,1,0,1,2,2], [0,0,0,1,0,0,2,1,0,1,2],> [0,0,0,0,1,0,2,2,1,0,1], [0,0,0,0,0,1,1,2,2,1,0] >;> G3;KModule G3 of dimension 6 with base ring GF(3)

The third fundamental construction in algebra is the formation of extensions. Owing tothe lack of a general theory of extensions even in the case of a particular variety such asgroups, we have not been able to design a general extension constructor. The constructorext is supported only for certain categories, and its semantics are heavily dependentupon the category. The ExtensionField constructor was devised to construct algebraicextensions in a single statement via a transcendental extension followed by a quotient.

A critical issue in algebraic system design concerns the ability to transfer objectsbetween related structures. This, in turn, introduces questions concerning the represen-tation of “derived magmas”, i.e., magmas produced through the operations of formingsubmagmas, quotient magmas and extension magmas. In Magma, the following principlehas been adopted:

Principle of Magma Autonomy: If N is a magma constructed as a submagma, quo-tient magma or extension magma of M , then N will be autonomous, in the sensethat any operation involving N alone can be performed without reference to M .


As a consequence of the principle of autonomy, the magma M may be deleted withoutaffecting the definition of N . This principle has some important consequences. In thecase when N is finitely presented, then the elements of N are given in terms of thegenerators of N rather than in terms of the generators of M . If N is a magma belongingto a category in which magmas are always given with respect to a standard basis, then Nwill be given with respect to the appropriate standard basis. In both cases, it may notbe easy to relate elements of N to elements of M . In order to have this informationavailable, the sub and quo constructors return morphisms as a second return value. Thusthe constructor sub< M | ...> returns:

(i) the submagma S defined by the constructor.(ii) the inclusion monomorphism φ : S →M .

and the constructor quo< M | ...> returns:

(i) the quotient magma Q defined by the constructor.(ii) the natural homomorphism φ : M → Q.

4.1.3. direct product and direct sum constructors

For a category of magmas belonging to a single algebraic variety, direct productsmay be formed using the intrinsic function DirectProduct (or DirectSum, in certaincategories). This function takes a sequence Q of n magmas belonging to a single categoryand constructs their direct product (or sum). It returns the following objects:

(i) The product (or sum) magma A = Q[1]× · · · ×Q[n].(ii) The sequence I of injections such that I[i] : Q[i]→ A.(iii) The sequence P of projections such that P [i] : A→ Q[i].

This function should not be confused with the general Cartesian product constructorcar< >, which merely returns a set (of type SetCart) containing tuples of elements withentries in the factor magmas. Its factors may be of any kind.

4.1.4. specific magma constructors

In addition to the generic magma constructors above, Magma also provides variousconstructors for category-specific magmas. Table 4 lists most of them. Besides theseconstructors (with arguments enclosed by < >) there are many functions (with argumentsin ( )) for the creation of category-specific magmas.

Example:We illustrate the iterated use of constructors with code that creates the Hecke algebraof type E6. The algebra is obtained as the quotient of a finitely presented associativealgebra H by a certain right ideal I. A free associative algebra FA over a cyclotomicfield Q5 is defined on generators corresponding to those of a monoid M . Thus, themultiplicative relations between the generators of FA are inherited from M . Additionalrelations are now imposed on FA to give the required associative algebra H. The onlyserious computation involved occurs when constructing the algebra quotient H/I, whichis performed using Linton’s vector enumerator.

252 W. Bosma et al.

Table 4. Specific magma constructors.

Monoid< generators | relations >Semigroup< generators | relations >AbelianGroup< generators | relations >Group< generators | relations >PolycyclicGroup< generators | relations >MatrixGroup< degree, ring | generators >PermutationGroup< degree or G-set | generators >MatrixRing< ring, degree | generators >MatrixAlgebra< ring, degree | generators >LinearCode< field, length | generators >IncidenceStructure< points | blocks >Design< t, points | blocks >ProjectivePlane< points | lines >AffinePlane< points | lines >Graph< vertex set | edge set >Digraph< vertex set | edge set >

Table 5. Literals.

Description Remarks Examples Type

Boolean true false BoolEltString "abc0 12" MonStgEltInteger Optional sign -7, +5, 11 RngIntEltRational n/d for literal integers n and d 5/84, -1/3 FldRatEltReal Optional sign, exponent, precision -7.123e-5p32 FldPrEltLiteral sequence Efficient enumerated sequence \[1,2] SeqEnumLiteral cycle Efficient permutation \(1,2) Cyc

> FM<x, y, z, t, u, v, q> := FreeMonoid(7);> M := quo< FM |> x*y*x = y*x*y, z*y*z = y*z*y, x*z = z*x,> x*t = t*x, y*t = t*y, t*z*t = z*t*z,> u*x = x*u, u*y = y*u, u*z*u = z*u*z,> u*t = t*u, x*v = v*x, y*v = v*y,> z*v = v*z, t*v = v*t, u*v*u = v*u*v >;>> Q5<w> := CyclotomicField(5);> FA<x, y, z, t, u, v, q> := FreeAlgebra(Q5, M);> H<x, y, z, t, u >, f := quo< FA | x^2 = (q-1)*x + q,> y^2 = (q-1)*y + q, z^2 = (q-1)*z + q, t^2 = (q-1)*t + q,> u^2 = (q-1)*u + q, v^2 = (q-1)*v + q, q = FA ! w >;>> I := rideal<H | x+1, y+1, z+1, t+1, u+1>;> Q, im, f := QuotientModule(H, I);> E6 := sub< Universe(Q) | Q >;> E6;Matrix Algebra of degree 27 with 7 generatorsover Cyclotomic Field of order 5 and degree 4


Table 6. Element constructors.

elt< expr | expr1, ..., exprk >expr ! [ expr1, ..., exprk ]

4.2. element constructors

When viewing elements in Magma it is important to recall that there are no au-tonomous elements. An element may only be created in the context of a unique magma.Thus, a polynomial cannot exist as an independent object: it can only exist as an elementof a polynomial ring. Consequently, prior to the construction of an element, its parentmagma must exist. As many standard algebraic structures have a single fundamentalcarrier set, we will consider this situation first. There are three standard constructionsfor elements of a magma M :

• In the case of the most elementary sets, such as the set of integers or the setof boolean values, the elements are self-identifying; their parent magma can bededuced from the syntax. See Table 5.• If M is a finitely generated algebra defined over the generating set X, an element

of M may be specified in the form of an expression built up from the elements of Xthrough application of the fundamental operators of M .• An element of M may be constructed from a list a1, . . . , an of more elementary

objects using the element constructor elt< >. This constructor has an abbreviatedform M ! Q, where Q is the sequence containing a1, . . . , an. See Table 6.

Example:Consider the 4-dimensional vector space V over the finite field F = F33 . First, we createthis space by applying the function VectorSpace to the field F312 and its subfield F .Note that we apply a functor from the category of finite fields to that of vector spaces.

> G<g> := FiniteField(3, 12);> F<f> := FiniteField(3, 3);> V, v := VectorSpace(G, F);> V, v;Full Vector space of degree 4 over GF(3^3)Mapping from: FldFin: G to ModTupFld: V

Note also that a second value, the map v from G to V , is returned, The map v and itsinverse may be used to transfer elements between G and V . We may also create elementsof G as polynomials in f and g.

> elt< V | 1, f, f^2, f^3 >;( 1 f f^2 f^3)> e := V ! [ f, f^11, f^2+f+1, 7 ];> e;( f f^11 f^6 1)> e @@ v;g^86726> f + f^11*g + (f^2+f+1)*g^2 + 7*g^3;g^86726

254 W. Bosma et al.

Table 7. The map constructors.

map< expr1 -> expr2 | graph >pmap< expr1 -> expr2 | graph >hom< expr1 -> expr2 | graph >

In a general multi-sorted algebra A, the concept of an element of A is not well defined.Instead, we have a number of sorts s, each with their associated carrier sets As. Theproblem then arises of specifying an element of a particular carrier set As. In Magma,such an object may be constructed by means of the third method above (elt constructoror coercion of a sequence), where the element target is the appropriate carrier set, ratherthan A itself.

Example:In the category of undirected graphs, each magma has two fundamental carrier sets: thevertex-set and the edge-set. We define the graph of the 4-dimensional cube, create twoadjacent vertices p and q and then form the edge e connecting them.

> G := KCubeGraph(4);> V := VertexSet(G); E := EdgeSet(G);> p := V ! 1; q := V ! 9;> e := E ! { p, q };> e;{1, 9}> Parent(p), Parent(e);The vertex-set of graph GThe edge-set of graph G

4.3. map constructors

The Magma syntax distinguishes three main classes of mappings (see Table 7):

• A mapping f :A → B, i.e., a subgraph G of the graph A × B, such that everyelement of A appears in exactly one pair of G.

• A partial mapping f :A → B, i.e., a subgraph G of the graph A × B, such thatevery element of A appears in at most one pair of G.

• A homomorphism f :A→ B, where A and B are magmas.

The graph may be specified in various ways. In the case of partial maps and maps, thepairs comprising the graph may be enumerated. However, a more useful method is togive the image of a generic element as in the following example:

> R := RealField();> t := map< R -> R | x :-> x - Sin(x) >;> t( Pi(R)/2 );0.57079632679489661923132169162

If f is a mapping defined with the general mapping constructor, it is not possible, ingeneral, to compute pre-images with respect to f . However, many particular mappingscreated by intrinsic functions do allow the computation of pre-images. The image of an


element x is represented syntactically either by x@f or f(x), while the pre-image of x(when defined for the mapping f) is represented by x@@f .

When defining a homomorphism, it suffices to specify images for the defining gen-erators of the domain, by virtue of the Homomorphism Representation Theorem. Weillustrate this form by defining isomorphisms between Sym(4) defined as a finitely pre-sented group G and as a permutation group H. Notice that the homomorphism can beapplied to subgroups as well as to elements.

> G<a, b> := Group< a, b | a^2 = b^3 = (a*b)^4 = 1>;> H<x, y> := PermutationGroup< 4 | (1, 2), (2, 3, 4) >;> f := hom< G -> H | a->x, b->y >;> g := hom< H -> G | x->a, y->b >;> f(a^b);(1, 3)> // We construct the Klein 4-group in H and find its image in G> K := sub< H | (1, 4)(3, 2), (1, 3)(2, 4) >;> V4 := g(K);> V4;Finitely presented group V4 on 2 generatorsGenerators as words in group G

V4.1 = (a * b)^2V4.2 = (a * b^-1)^2

4.4. sets and sequences

The data structures provided in the Magma language for aggregating objects to-gether are based on the standard mathematical notions of unordered sets, ordered sets,unordered multisets, ordered multisets (sequences), products and co-products (see Ta-ble 8). There are conversion functions between the various kinds of aggregate structures.

Most aggregate data structures in Magma are required to satisfy a homogeneity prin-ciple:

Homogeneity Principle: The members of any set or sequence must all belong to somecommon magma U which is known as the universe of the set.

This principle allows sets to be stored in the form of a hash-addressed table. It alsosimplifies the storage of elements of sets and sequences, since the parent of each elementdoes not have to be stored with it.

The most important aggregate structures are enumerated sets and sequences. An enu-merated set is a finite unordered collection of objects of a common magma, stored as alist of elements (usually in the form of a hash table). This allows random insertion anddeletion of elements, selection of elements and iteration over the set. An enumerated se-quence is a finite ordered collection of objects (with possible duplicates), all belonging toa common magma. Its implementation maximizes the speed of accessing the ith element.Enumerated sets and sequences are specified in the same way, the only difference beingthe type of delimiters used; the general constructor has the following form:

{ U | e : x in E | P } (or the appropriate delimiters)

where U is the common magma to which all elements of the set will belong, e is an

256 W. Bosma et al.

Table 8. Sets, sequences, and other aggregates.

Brackets Characteristics Description

{ } Homogeneous, finite, unordered, no duplicates, fast ∈ test Enumerated set{* *} Homogeneous, finite, unordered, fast ∈ test Enumerated multiset{@ @} Homogeneous, finite, ordered, no duplicates, fast ∈ test Indexed set{! !} Homogeneous, unordered, no duplicates, ∈ test via predicates Formal set

[ ] Homogeneous, finite, ordered, fast indexed access Enumerated sequence[* *] Inhomogeneous, finite, ordered List< > Inhomogeneous, finite, ordered (element of Cartesian product) Tuple

car< > Iterable if components are iterable Cartesian productcop< > Co-product

expression usually involving the (local) parameter x which ranges over the magma (orset or sequence) E, which must be enumerable, and restricted by the predicate P usuallyalso involving x. Note that it is quite possible that the expression e defines objects notbelonging to the magma E. Often U and the following | may be omitted, when Magmawill be able to determine the common overstructure by itself. If all elements of E shouldbe incorporated, it is permissible to omit the | P section of the constructor.

An indexed set X is a finite collection of n distinct objects from a common magma,with an associated bijection (the index map) between X and the set {1, . . . , n}. As inenumerated sets duplicates are discarded, and as in sequences the elements are linearlyordered and can be indexed. Operators are provided that allow the adjunction of furtherelements to X in such a way that the index map for the larger set is an extension of theindex map for X. This data structure provides fast membership testing while associatinga unique index with each element. These two facilities are critical when writing efficientcode to form the closure of a set under some action.

A formal set is a possibly infinite subset of the element-set of a magma M ; it is storedas M together with a predicate defining its elements. Membership testing is a simplepredicate evaluation, but iteration over formal sets is impossible.

A tuple is an element of a Cartesian product of finitely many magmas (or sets). Thefactors may be chosen quite independently of one another.

We mention a few additional features of the constructors for enumerated sets andsequences:

• Instead of enumerating over a single domain E, it is possible to enumerate over afinite number of domains simultaneously.• A small set may be created by simply listing the elements within the delimiters:{t1, t2, ..., tn}.• The arithmetic progression constructor {a .. b by k} makes it easy to enumerate

the integer-set {x : x = a+ kn, a ≤ x ≤ b}.• Recursion on sequence constructors is also possible. Inside the sequence constructor,

the ith entry of the sequence under construction is Self(i), and the whole sequencecomputed so far is Self().

It is possible to use existential and universal quantifiers on set constructors. Each of theexpressions below returns a Boolean value, with the obvious interpretation:


Table 9. Some set functions.

eq, ne Equality testing Random(S) Random elementin, notin Membership Representative(S) Representative elementsubset, notsubset Subset? Include(S, s) Include s in Sjoin, meet Union, intersection Exclude(S, x) Remove element sdiff, sdiff (symmetric) difference exists Existential quantificationIsEmpty Empty? forall Universal quantification

Table 10. Some sequence functions.

eq, ne Equality testing Random(S) Random elementin, notin Membership Representative(S) Representative elementcat Concatenate Exclude(S, x) Remove element xIsEmpty Empty? Include(S, x) Include x if not in SIsSubsequence(S, T) S subsequence of T? Remove(S, i) Remove ith elementIsComplete(S) All entries defined? Insert(S, i, x) Put x in ith positionIsDefined(S, i) ith entry defined? Append(S, s) Append element sUndefine(S, i) Undefine entry i Prune(S) Remove last elementPosition(S, x) Find index of x in S Rotate(S, p) Cyclically permute p placesSort(S) Sort (ordered magma) Reverse(S) S backwardsExplode(S) Terms of S &•S Reduce S using operator •

exists(idfr){ e : x in E | P }forall(idfr){ e : x in E | P }

Moreover, if exists returns true, the idfr will be assigned the value obtained by eval-uating e with x taking the value of an example, and similarly if forall returns false,the idfr will be assigned the value obtained by evaluating e with x taking the valueof a counter-example. As soon as the return value is established, the evaluation of theright-hand side is terminated.

Entries in sequences can be modified by certain procedures, or by accessing themdirectly using indexing (on the left-hand side of an assignment):

> s := [];> s[3] := 11;> s;[ undef, undef, 11 ]

As the above example shows, sequences are not necessarily complete. That is, usingleft-hand side indexing, it is possible to create sequences for which not all entries havebeen assigned values (“sequences with holes”). Predicates are provided to test whethersequences are complete and whether particular entries have been assigned.

The final important concept is that of reduction: it allows a (binary) symmetric op-erator to be applied successively to all elements of a set or sequence. For example, thevalue of &*s is equal to the product of all the terms of s.

We summarize the most important functions on enumerated sets and sequences inTables 9 and 10.

258 W. Bosma et al.

Example:We give a concise definition of a function that returns all integer pairs (x, y) with −10 ≤x ≤ 10 and 0 ≤ y ≤ 15 such that y2 = x3 + ax+ b, for a given pair (a, b).

> n := func< a, b |[ <x, y> : x in [-10..10], y in [0..15] | y^2 eq x^3+a*x+b ] >;

We may look for pairs (a, b) in some finite interval such that there are at least six solutionsto the given equation:

> exists(p){ <a,b> : a, b in [-10..10] | #n(a,b) ge 6 };true> p;<-7, 10>> n(-7, 10);[ <-3, 2>, <1, 2>, <2, 2>, <-2, 4>, <-1, 4>, <3, 4>, <5, 10> ]

The next construction uses recursion to obtain 50 elements of the Fibonacci sequence:

> F := [n in {1, 2} select 1 else Self(n-1)+Self(n-2) : n in [1..50]];

We now define a function that returns the degree-k elementary symmetric polynomialin the polynomial ring R = Z[x1, . . . , xm]. This polynomial is simply obtained by sum-ming the elements of the G-set consisting of the images of x1x2 · · ·xk under the actionof the symmetric group of degree m. This would be a one-line function, if we had notinsisted in the code below that the indeterminates of R print as the strings x[1], x[2]etc.

> elSym := function(k, m)> R<[x]> := PolynomialRing(Integers(), m);> return &+( &*[ R | R.i : i in [1..k] ] ^ Sym(m) );> end function;> elSym(2, 4);x[1]*x[2] + x[1]*x[3] + x[1]*x[4] + x[2]*x[3] + x[2]*x[4] + x[3]*x[4]

Note that the universe R was explicitly included in the return statement to ensure thatthe function works for k = 0: omitting the universe will lead to a null sequence for k = 0(rather than an empty R-sequence) and the reduction &*[ ] is not defined generally.

Finally, we give an example of the use of Cartesian products and co-products, which arecreated by means of the car and cop constructors. Let G be a permutation group withtwo actions X and Y , represented as G-sets. We want to build the action on the disjointunion of X and Y . Given the action of an element g on each of the components, thefunction below uses UniversalMap to generate the action on the co-product of X and Y .(The function could be applied in a situation where X and Y are two non-compatibleand unfaithful actions, and the user wishes to construct from them a faithful action offairly small degree.)


Table 11. Operators.

Arity Operators Remarks

1 + - not # Unary1 &+ &* &and &or &meet &join &cat Reduction2 + - * div mod / ^ Ordinary arithmetical2 and or xor Logical2 in notin subset notsubset Membership2 meet join diff sdiff cat Set-theoretical2 eq ne gt lt ge le Comparative2 adj notadj Adjacency2 = Relator2 . ‘ ‘‘ Access2 @ @@ :-> -> Map application2 !! ! Coercion3 select else Switch

> CompositeAction := function(G, X1, X2)> f1 := Action(X1);> f2 := Action(X2);> XW, I := cop<X1, X2>;> X := Set(XW);> f := map<> car<X, G> -> X | z :-> UniversalMap(XW, X, [h1, h2])(x)> where h1 is map<X1 -> X | x :-> f1(x, g)>> where h2 is map<X2 -> X | x :-> f2(x, g)>> where x is z[1] where g is z[2] >;> Y := GSet(G, X, f);> return Y;> end function;

4.5. functions and procedures

There are three kinds of functions and procedures in Magma: user-defined functionsand procedures, user intrinsics, and system intrinsics. All of these are first-class objectsin the Magma language. Thus, a function or procedure may be passed as an argumentto another function or procedure, returned as the result of a function, or assigned toan identifier, and it can be invoked “on the fly” by means of any expression defining it.All function arguments are passed by value, as a consequence of call-by-value semantics,but procedure arguments may be passed by value or by reference. A function invoca-tion is an expression, returning at least one value, whereas a procedure invocation is astatement, designed to perform input/output or to change the calling context by assign-ing or reassigning reference arguments. Parameters are available for both functions andprocedures.

4.5.1. operators

Operators (see Table 11) are treated by Magma as functions with special syntax.If an operator is to be regarded as a normal function, it must be enclosed within ’characters. The Boolean operators are exceptional in using call-by-name semantics; theyonly evaluate their operands as required.

260 W. Bosma et al.

Table 12. User-defined functions and procedures.

function(arg1, ..., argk)statements

end function

func< arg1, ..., argm | expr1, ..., exprk >

procedure(arg1, ..., argk)statements

end procedure

proc< arg1, ..., argm | procedure call >

4.5.2. invocation of functions and procedures

The syntax for a function-invocation expression is f(arg1,..., argk) where f is anexpression returning the function, and arg1, . . . , argk are expressions whose values aretaken to be the actual value arguments of the function. If the function has parameters,then the user may assign any non-default parameter values as follows:

f(arg1, ..., argk : param idfrα:= exprα, ..., param idfrλ := exprλ)

Every function invocation in Magma returns at least one value. If it appears on the rightside of a multiple-value assignment, as an element of a print statement or as the soleitem in a function return statement, then it returns all its values; otherwise, it returnsonly the first or principal value. (For some intrinsic functions, only the principal valuewill be printed from a simple print statement invoking the function.)

The syntax for a procedure-invocation statement is p(arg1,..., argk); where p isan expression returning the procedure, and arg1, . . . , argk are the actual arguments, or,if there are parameters being assigned non-default values:

p(arg1, ..., argk : param idfrα:= exprα, ..., param idfrλ := exprλ);

The arguments of a procedure may be passed either by value or by reference, accordingto the way the procedure was defined. Value arguments behave in the same way as forfunctions; i.e., if the ith argument is a value argument, then argi may be any expression,and its value will be passed to the procedure. If the ith argument is a reference argument,then arg i must have the form ∼idfr , where idfr is an identifier; idfr may have a (new)

value assigned to it as a result of the procedure invocation.

4.5.3. definition of functions and procedures

Table 12 lists the constructions for user-defined functions (on the left) and for user-defined procedures (on the right), where arg1, . . . , argk denote (zero or more) formalarguments. For a function, each argument is an identifier, acting as a value argument.For a procedure, each argument is either an identifier, acting as a value argument, or atilde ∼ followed by an identifier, acting as a reference argument. These constructions areexpressions, whose value is a function or procedure; the values of these expressions areusually assigned immediately to identifiers, but may be called directly or passed as anargument to another function or procedure.

Functions must be created in such a way that when they are invoked they will return


one or more values. In the func form of a function expression, the return values are thevalues of expr1, . . . , exprk when the actual arguments given in the function invocation aresubstituted for the formal arguments. In the other form, the statements in the functionbody must include one or more statements of the form

return expr1, . . ., exprk;

During the execution of a procedure invocation, any instances of a formal referenceargument in the statements of the procedure body are understood to refer to the cor-responding actual reference argument. In particular, any changes to a formal referenceargument within the procedure body will change the actual reference argument in thecalling context. The statement return; may be used (zero or more times) within a pro-cedure definition to cause an immediate end to the execution of the procedure and areturn to the calling context.

When a function/procedure with parameters is created, the list of arguments must befollowed by a colon and a list of parameter identifiers, each of which is followed by :=and an expression, as follows:

arg1, ..., argk : param idfr1:= expr1, ..., param idfrn := exprn

The default values of the parameters are the values of the corresponding expressions.The parameters will normally occur in the statement body of the function/proceduredefinition (or the right-hand side of the func or proc constructor). They are classedas value identifiers, so they may not be changed within the statement body. However,the value used for the parameters depends on the function/procedure invocation. If theinvocation includes parameters and values then the parameters will have those values;otherwise, they will have the default values.

Recursive functions and procedures pose a particular problem in Magma since func-tions and procedures are first-class objects. Not every function or procedure is assignedto an identifier. Even if it is, the identifier cannot be used within the function or pro-cedure since, by the assignment rules, identifiers appearing on the left-hand side of anassignment statement are not considered to have a value on the right-hand side, un-less they were previously assigned a value. Magma solves this problem by using the$$ pseudo-identifier as a placeholder for the function/procedure value denoted by thefunction/procedure expression inside which the $$ occurs.

Lexical scoping of identifiers is employed. Formal value arguments, formal referencearguments and parameters automatically have local scope. A “first-use” rule decideswhich other identifiers have local scope: if the first textual use of an identifier inside afunction or procedure body is on the left-hand side of a := symbol, then the identifier isconsidered to be local; otherwise, its value is imported from the environment (the value ofthe identifier in the calling context when the function/procedure is defined, not when itis invoked). The calling context cannot be changed from within the function/procedure,except by the standard means of reference arguments. The problem of mutual recursion ishandled through the provision of a forward statement that allows reference to functionsor procedures prior to their lexical appearance.

262 W. Bosma et al.

4.5.4. user intrinsics and package files

A user intrinsic is a special kind of user-defined function/procedure that has a signatureattached to it, giving the categories of the arguments and return values. The syntax fora user intrinsic is a modified form of the function/procedure expression, bounded by anintrinsic statement. A file containing one or more intrinsics constitutes a package file;also present may be some assigned values that are private to the package file. When thepackage file is attached to Magma, the user intrinsics are incorporated into the system,together with the kernel intrinsics. Identifiers private to a package file may be accessedby other packages if they are explicitly imported using the import statement.

4.6. common subexpression evaluation

The where clause may be attached to the right end of a list of expressions expr1, . . .,exprn, in order to perform common subexpression evaluation. The general form of anexpression-list ending with a where clause is

expr1, ..., exprn where idfr1, ..., idfrk is exprw

The expression exprw must have at least k return values; in most cases, it has one returnvalue, and there is only one identifier.

To evaluate the whole expression-list, Magma temporarily assigns to idfr1, . . . , idfrkthe first k return values of exprw. It then evaluates the expressions expr1, . . . , exprn,substituting the values for idfr1, . . . , idfrk whenever they occur in the expressions. Thescope of idfr1, . . . , idfrk is limited to the expression-list.

Within the predicate of a set/sequence constructor, the where clause has an additionalproperty: idfr1, . . . , idfrk may also be used in the expression used to calculate the set orsequence elements. In this case, the scope of idfr1, . . . , idfrk is limited to the constructor.

4.7. statements

The principal kinds of statements in Magma are assignment statements, input andoutput statements, iterative statements, conditional statements, and procedure invoca-tions. The last of these has already been discussed; the others will be summarized below.

4.7.1. assignment statements

There is no assignment expression in Magma, and it is not possible to print values atthe same time as they are assigned. Variable identifiers and reference identifiers may bethe targets of an assignment, but not value identifiers.

Functions may return m ≥ 1 values; the first k (where 1 ≤ k ≤ m) can be assigned toidentifiers by the multiple-value assignment. It is possible to ignore some of the first kreturn values by using the special throwaway identifier , i.e., the underscore character.

The mutation assignment statement idfr •:= idfr; is equivalent to idfr := idfr • expr;in its overall effect. However, the mutation version may sometimes result in faster ex-ecution since it allows the obvious optimization. Mutation of certain objects (such assequences) is also possible.

It is often desirable for the user to provide names for the generators, and so the


Table 13. Assignment statements.

Statement Description Remarks

idfr := expr; Simple assignmentidfr1, ..., idfrk := expr; Multiple-value assignment Use for throwawayidfr •:= expr; Mutation assignment • is a binary operatoridfr<idfr1, ..., idfrk> := expr; Generator name assignment

Table 14. Input and output statements.

print expr1, ..., exprk; Print values of expressionsexpr1, ..., exprk; As above [not in function/procedure definition]print expr1, ..., exprk: level; level is one of Minimal, Default, Maximal, Magmaexpr1, ..., exprk: level; As above [not in function/procedure definition]printf expr, expr1, ..., exprk; Print values of expressions in expr formatread idfr Assign the next input line to idfr as a stringread idfr, expr As above, giving value of expr as promptreadi idfr Assign the (legal) next input line to idfr as an integerreadi idfr, expr As above, giving value of expr as prompt

generator assignment statement provides a mechanism for the user to assign a magmato an identifier, and simultaneously to specify particular identifiers (and printnames, forfree magmas and their quotients) for the generators of a magma. See page 248.

4.7.2. input and output statements

The word print is optional, except within the definition of a function or procedure.Therefore, the user can obtain the evaluation of a list of expressions at the command-line simply by typing the comma-separated expressions and following the list with asemicolon.

The optional qualifier level may be used to control the amount and format of informa-tion printed for the designated objects. For example, the qualifier value Magma causes thevalues to be printed in Magma-readable format, so that they may be used as Magmainput.

There is also a printf statement for formatted output. The expr immediately followingprintf must evaluate to a string. The statement prints this string, substituting the valueof expri at the ith occurrence of %o within the string.

A number of other string and file-handling facilities are provided for input and output.

4.7.3. iterative statements

The while and repeat statements have the usual interpretations. In the for state-ment, the idfr is a local-scope value identifier that assumes successively the values of theelements of the domain. The domain may be any iterable magma (i.e., a finite algebraicstructure or aggregate whose elements can be enumerated by Magma) and if it is anordered aggregate, such as a sequence, then iteration will occur in index order.

264 W. Bosma et al.

Table 15. Iterative statements.

while expr dostatements

end while;

repeatstatements

until expr;

for idfr in domain dostatements

end for;

Table 16. Conditionals.

Construction Remarks

if expr then statements conditional statementelif expr then statements Optional, may be repeatedelse statements Optional

end if;

case expr case-statementwhen expr1, ..., exprk: statements Optional, may be repeatedelse statements Optional

end case;

expr select expr1 else expr2 conditional expression

case<expr | expr1:expr′1, ..., case-expressionexprk:expr′k, default:exprd> default is compulsory

4.7.4. conditional statements and expressions

As shown in Table 16, the Magma language offers both conditional statements andconditional expressions: a standard if statement, a case statement, a select expression,and a case expression. The two conditional expressions use call-by-name semantics.

5. Closing Remarks

This paper has attempted to show how ideas from universal algebra and categorytheory can provide the general foundations for an algebraic programming language. Theorganization of algebraic structures, firstly into varieties, and then within varieties intocategories, has shown itself to be a natural hierarchy for algebraic computation. As moreexotic classes of structures are included, we find that the model holds up extremely well.The use of algebraic data structures such as sets, sequences and mappings provides avery concise and natural means of specifying algebraic computations.

An interpreter and run-time system for the Magma language have been developedby Graham Matthews and Allan Steel. Magma V1 was released at the end of 1993and V2 in 1996. The language will be extended in the near future to support user-definedcategories and varieties.

An elementary overview of the system is given in Cannon and Playoust (1996a). Afull description of the language and installed categories may be found in Cannon andPlayoust (1996b, c) and Bosma and Cannon (1996). Some aspects of the implementationare touched on in Bosma et al. (1994). Applications of the system are described in the


proceedings of the first Magma conference (this issue), the proceedings of the secondMagma conference (to appear as a Special Issue of JSC ) and in Bosma et al. (1995).

References

——Bosma, W., Cannon, J.J. (1996). Handbook of Magma Functions. Sydney: School of Mathematics andStatistics, University of Sydney.

——Bosma, W., Cannon, J.J., Matthews, G. (1994). Programming with algebraic structures: design of theMagma language. In Giesbrecht, M., ed., Proc. of the 1994 International Symposium on Symbolicand Algebraic Computation, Oxford, 52–57. Association for Computing Machinery.

——Bosma, W., Cannon, J.J, Playoust, C., Steel, A. (1995). Solving Problems with Magma. Sydney: Schoolof Mathematics and Statistics, University of Sydney.

——Bourbaki, N. (Nouvelle Edition 1970). Algebre I: Chapitres 1 a 3 (Elements de Mathematique). Paris:Hermann.

——Burstall, R.M., Gougen, J.A. (1981). An informal introduction to specifications using CLEAR. In Boyer,R.S., Moore, J.S., eds, The Correctness Problem in Computer Science. London: Academic Press,185–213.

——Butler, G., Cannon, J.J. (1989). Cayley version 4: The user language. [The early name for Magma was Cay-ley V4.] In Gianni, P., ed., Proc. of the 1988 International Symposium on Symbolic and AlgebraicComputation, Rome, July 4–8, 1988, LNCS 358, 456–466. New York: Springer.

——Butler, G., Cannon, J.J. (1990). The design of Cayley, a language for modern algebra. In Miola, A., ed.,Design and Implementation of Symbolic Computation Systems, LNCS 429, 10–19.

——Cannon, J.J., Playoust, C. (1996a). Magma: A New Computer Algebra System. Euromath Bulletin, 2, 1.——Cannon, J.J., Playoust, C. (1996b). Algebraic Programming with Magma: The Language. Springer-Verlag,

To appear.——Cannon, J.J., Playoust, C. (1996c). Algebraic Programming with Magma: The Categories. Springer-Verlag,

To appear.——Gougen, J.A. (1989). Principles of Parameterized Programming. In Biggerstaff, T., Perlis, A., eds, Software

Reuseability, Vol 1: Concepts and Models. Reading, MA: ACM Press, Addison-Wesley, 159–225.——Hearn, A.C, Schrufer, E. (1995). A computer algebra system based on order-sorted algebra. J. Symbolic

Comput. 19, 65–77.——Jenks, R.J, Sutor, R. (1992). AXIOM: The Scientific Computation System. New York: Springer-Verlag.——Mac Lane, S. (1971). Categories for the working mathematician. New York: Springer-Verlag.——Meinke, K., Tucker, J.V. (1992). Universal Algebra. In Abramsky, S., Gabbay, D.M., Maibaum, T.S.E.,

eds, Handbook of Logic in Computer Science 1. Oxford: Clarendon Press, 189–411.

Originally received 10 January 1996Accepted 7 November 1996

the magma algebra system i: the user language

Documents