# Cubical¶

The Cubical mode extends Agda with a variety of features from Cubical Type Theory. In particular, it adds computational univalence and higher inductive types, hence giving computational meaning to Homotopy Type Theory and Univalent Foundations. The version of Cubical Type Theory that Agda implements is a variation of the CCHM Cubical Type Theory where the Kan composition operations are decomposed into homogeneous composition and generalized transport. This is what makes the general schema for higher inductive types work, following the CHM paper. There is also a research paper specifically about Cubical Agda at https://www.doi.org/10.1017/S0956796821000034.

To use the cubical mode Agda needs to be run with the
`--cubical`

command-line-option or with ```
{-#
OPTIONS --cubical #-}
```

at the top of the file. There is also a
variant of the cubical mode, activated using
`--erased-cubical`

, which is described
below.

The cubical mode adds the following features to Agda:

An interval type and path types

Generalized transport (

`transp`

)Partial elements

Homogeneous composition (

`hcomp`

)Glue types

Higher inductive types

Cubical identity types

There are two major libraries for Cubical Agda:

`agda/cubical`

: originally intended as a standard library for Cubical Agda available at https://github.com/agda/cubical. This documentation uses the naming conventions of this library, for a detailed list of all of the built-in Cubical Agda files and primitives see Appendix: Cubical Agda primitives.`1lab`

: A formalised and cross linked reference resource for cubical methods in Homotopy Type Theory which can be found at https://1lab.dev/. Much better documented than the`agda/cubical`

library and hence more accessible to newcomers. The sources can be found at https://github.com/plt-amy/1lab.

In this documentation we will rely on the `agda/cubical`

library and
the recommended way to get access to the cubical primitives is to add
the following to the top of a file (this assumes that the
`agda/cubical`

library is installed and visible to Agda).

```
{-# OPTIONS --cubical #-}
open import Cubical.Core.Everything
```

Follow the instructions at https://github.com/agda/cubical to install the library.
In order to make this library visible to Agda add
`/path/to/cubical/cubical.agda-lib`

to `.agda/libraries`

and
`cubical`

to `.agda/defaults`

(where `path/to`

is the absolute
path to where the `agda/cubical`

library has been installed). For
details of Agda’s library management see Library Management.

Expert users who do not want to rely on `agda/cubical`

can just add
the relevant import statements at the top of their file (for details
see Appendix: Cubical Agda primitives). However, for beginners it is
recommended that one uses at least the core part of the
`agda/cubical`

library.

## The interval and path types¶

The key idea of Cubical Type Theory is to add an interval type ```
I :
IUniv
```

(the reason this is in a special sort `IUniv`

is because it
doesn’t support the `transp`

and `hcomp`

operations). A variable
`i : I`

intuitively corresponds to a point in the real unit interval. In an empty context,
there are only two values of type `I`

: the two endpoints of the
interval, `i0`

and `i1`

.

```
i0 : I
i1 : I
```

Elements of the interval form a De Morgan algebra, with minimum
(`∧`

), maximum (`∨`

) and negation (`~`

).

```
_∧_ : I → I → I
_∨_ : I → I → I
~_ : I → I
```

All the properties of De Morgan algebras hold definitionally. The
endpoints of the interval `i0`

and `i1`

are the bottom and top
elements, respectively.

```
i0 ∨ i = i
i1 ∨ i = i1
i ∨ j = j ∨ i
i0 ∧ i = i0
i1 ∧ i = i
i ∧ j = j ∧ i
~ (~ i) = i
i0 = ~ i1
~ (i ∨ j) = ~ i ∧ ~ j
~ (i ∧ j) = ~ i ∨ ~ j
```

The core idea of Homotopy Type Theory and Univalent Foundations is a
correspondence between paths (as in topology) and (proof-relevant)
equalities (as in Martin-Löf’s identity type). This correspondence is
taken very literally in Cubical Agda where a path in a type `A`

is
represented like a function out of the interval, `I → A`

. A
path type is in fact a special case of the more general built-in
heterogeneous path types:

```
-- PathP : ∀ {ℓ} (A : I → Set ℓ) → A i0 → A i1 → Set ℓ
-- Non dependent path types
Path : ∀ {ℓ} (A : Set ℓ) → A → A → Set ℓ
Path A a b = PathP (λ _ → A) a b
```

The central notion of equality in Cubical Agda is hence heterogeneous
equality (in the sense of `PathOver`

in HoTT). To define paths we
use λ-abstractions and to apply them we use regular application. For
example, this is the definition of the constant path (or proof of
reflexivity):

```
refl : ∀ {ℓ} {A : Set ℓ} {x : A} → Path A x x
refl {x = x} = λ i → x
```

Although they use the same syntax, a path is not exactly the same as a function. For example, typed lambdas cannot be used to form paths, they are reserved for functions:

```
not-refl : ∀ {ℓ} {A : Set ℓ} {x : A} → (i : I) → A
not-refl {x = x} = λ (i : I) → x
```

Because of the intuition that paths correspond to equality ```
PathP (λ
i → A) x y
```

gets printed as `x ≡ y`

when `A`

does not mention
`i`

. By iterating the path type we can define squares, cubes, and
higher cubes in Agda, making the type theory cubical. For example a
square in `A`

is built out of 4 points and 4 lines:

```
Square : ∀ {ℓ} {A : Set ℓ} {x0 x1 y0 y1 : A} →
x0 ≡ x1 → y0 ≡ y1 → x0 ≡ y0 → x1 ≡ y1 → Set ℓ
Square p q r s = PathP (λ i → p i ≡ q i) r s
```

Viewing equalities as functions out of the interval makes it possible to do a lot of equality reasoning in a very direct way:

```
sym : ∀ {ℓ} {A : Set ℓ} {x y : A} → x ≡ y → y ≡ x
sym p = λ i → p (~ i)
cong : ∀ {ℓ} {A : Set ℓ} {x y : A} {B : A → Set ℓ} (f : (a : A) → B a) (p : x ≡ y)
→ PathP (λ i → B (p i)) (f x) (f y)
cong f p i = f (p i)
```

Because of the way functions compute these satisfy some new definitional equalities compared to the standard Agda definitions:

```
symInv : ∀ {ℓ} {A : Set ℓ} {x y : A} (p : x ≡ y) → sym (sym p) ≡ p
symInv p = refl
congId : ∀ {ℓ} {A : Set ℓ} {x y : A} (p : x ≡ y) → cong (λ a → a) p ≡ p
congId p = refl
congComp : ∀ {ℓ} {A B C : Set ℓ} (f : A → B) (g : B → C) {x y : A} (p : x ≡ y) →
cong (λ a → g (f a)) p ≡ cong g (cong f p)
congComp f g p = refl
```

Path types also let us prove new things are not provable in standard Agda. For example, function extensionality, stating that pointwise equal functions are equal, has an extremely simple proof:

```
funExt : ∀ {ℓ} {A : Set ℓ} {B : A → Set ℓ} {f g : (x : A) → B x} →
((x : A) → f x ≡ g x) → f ≡ g
funExt p i x = p x i
```

## Transport¶

While path types are great for reasoning about equality they do not let
us transport along paths between types or even compose paths, which in
particular means that we cannot yet prove the induction principle for paths.
As a remedy, we also have a built-in (generalized) transport operation `transp`

and homogeneous composition operations `hcomp`

.
The transport operation is generalized in the sense that it
lets us specify where it is the identity function.

```
transp : ∀ {ℓ} (A : I → Set ℓ) (r : I) (a : A i0) → A i1
```

There is an additional side condition to be satisfied for a usage of
`transp`

to type-check: `A`

should be a constant function whenever
the constraint `r = i1`

is satisfied. By constant here we mean that
`A`

is definitionally equal to `λ _ → A i0`

, which in turn
requires `A i0`

and `A i1`

to be definitionally equal as well.

When `r`

is `i1`

, `transp A r`

will compute as the identity function.

```
transp A i1 a = a
```

This is only sound if in such a case `A`

is a trivial path, as the
side condition requires.

It might seems strange that the side condition expects `r`

and
`A`

to interact, but both of them can depend on any of the
interval variables in scope, so assuming a specific value for `r`

can affect what `A`

looks like.

Some examples of the side condition for different values of `r`

:

If

`r`

is some in-scope variable`i`

, on which`A`

may depend as well, then`A`

only needs to be a constant function when substituting`i1`

for`i`

.If

`r`

is`i0`

then there is no restrition on`A`

, since the side condition is vacuously true.If

`r`

is`i1`

then`A`

must be a constant function.

We can use `transp`

to define regular transport:

```
transport : ∀ {ℓ} {A B : Set ℓ} → A ≡ B → A → B
transport p a = transp (λ i → p i) i0 a
```

By combining the transport and min operations we can define the induction principle for paths:

```
J : ∀ {ℓ} {A : Set ℓ} {x : A} (P : ∀ y → x ≡ y → Set ℓ)
(d : P x refl) {y : A} (p : x ≡ y)
→ P y p
J P d p = transport (λ i → P (p i) (λ j → p (i ∧ j))) d
```

One subtle difference between paths and the propositional equality
type of Agda is that the computation rule for `J`

does not hold
definitionally. If `J`

is defined using pattern-matching as in the
Agda standard library then this holds, however as the path types are
not inductively defined this does not hold for the above definition of
`J`

. In particular, transport in a constant family is only the
identity function up to a path which implies that the computation rule
for `J`

only holds up to a path:

```
transportRefl : ∀ {ℓ} {A : Set ℓ} (x : A) → transport refl x ≡ x
transportRefl {A = A} x i = transp (λ _ → A) i x
JRefl : ∀ {ℓ} {A : Set ℓ} {x : A} (P : ∀ y → x ≡ y → Set ℓ)
(d : P x refl) → J P d refl ≡ d
JRefl P d = transportRefl d
```

Internally in Agda the `transp`

operation computes by cases on the
type, so for example for Σ-types it is computed elementwise. For path
types it is however not yet possible to provide the computation rule
as we need some way to remember the endpoints of the path after
transporting it. Furthermore, this must work for arbitrary higher
dimensional cubes (as we can iterate the path types). For this we
introduce the “homogeneous composition operations” (`hcomp`

) that
generalize binary composition of paths to n-ary composition of higher
dimensional cubes.

## Partial elements¶

In order to describe the homogeneous composition operations we need to
be able to write partially specified n-dimensional cubes (i.e. cubes
where some faces are missing). Given an element of the interval ```
r :
I
```

there is a predicate `IsOne`

which represents the constraint ```
r
= i1
```

. This comes with a proof that `i1`

is in fact equal to `i1`

called `1=1 : IsOne i1`

. We use Greek letters like `φ`

or `ψ`

when such an `r`

should be thought of as being in the domain of
`IsOne`

.

Using this we introduce a type of partial elements called `Partial φ A`

.
The idea is that `Partial φ A`

is the type of cubes in `A`

that are only defined when `IsOne φ`

holds.
`Partial φ A`

is a special version of `IsOne φ → A`

with a more extensional judgmental equality:
Two elements of `Partial φ A`

are considered equal if they represent the same subcube;
so, the faces of the cubes can for example be given in different order
yet the two elements will still be considered the same.

There is also a dependent version of `Partial φ A`

called `PartialP φ A`

which requires `A`

only to be defined when `IsOne φ`

.

```
Partial : ∀ {ℓ} → I → Set ℓ → SSet ℓ
PartialP : ∀ {ℓ} → (φ : I) → Partial φ (Set ℓ) → SSet ℓ
```

There is a new form of pattern matching that can be used to introduce partial elements:

```
partialBool : ∀ i → Partial (i ∨ ~ i) Bool
partialBool i (i = i0) = true
partialBool i (i = i1) = false
```

The term `partialBool i`

should be thought of a boolean with
different values when `(i = i0)`

and `(i = i1)`

. Terms of type
`Partial φ A`

can also be introduced using a Pattern matching lambda.

```
partialBool' : ∀ i → Partial (i ∨ ~ i) Bool
partialBool' i = λ where
(i = i0) → true
(i = i1) → false
```

When the cases overlap they must agree:

```
partialBool'' : ∀ i j → Partial (~ i ∨ i ∨ (i ∧ j)) Bool
partialBool'' i j = λ where
(i = i1) → true
(i = i1) (j = i1) → true
(i = i0) → false
```

Note that the order of the cases does not have to match the interval formula exactly.

Furthermore, `IsOne i0`

is actually absurd:

```
empty : {A : Set} → Partial i0 A
empty = λ()
```

Cubical Agda also has cubical subtypes as in the CCHM type theory:

```
_[_↦_] : ∀ {ℓ} (A : Set ℓ) (φ : I) (u : Partial φ A) → SSet ℓ
A [ φ ↦ u ] = Sub A φ u
```

A term `v : A [ φ ↦ u ]`

should be thought of as a term of type
`A`

which is definitionally equal to `u : A`

when `IsOne φ`

is
satisfied. Any term `u : A`

can be seen as an term of ```
A [ φ ↦ u
]
```

which agrees with itself on `φ`

:

```
inS : ∀ {ℓ} {A : Set ℓ} {φ : I} (u : A) → A [ φ ↦ (λ _ → u) ]
```

One can also forget that a partial element agrees with `u`

on `φ`

:

```
outS : ∀ {ℓ} {A : Set ℓ} {φ : I} {u : Partial φ A} → A [ φ ↦ u ] → A
```

These coercions satisfy the following equalities:

```
outS (inS a) = a
inS {φ = φ} (outS {φ = φ} a) = a
outS {φ = i1} {u} _ = u 1=1
```

Note that given `a : A [ φ ↦ u ]`

and `α : IsOne φ`

, it is not the
case that `outS a = u α`

; however, underneath the pattern binding
`(φ = i1)`

, one has `outS a = u 1=1`

.

With all of this cubical infrastructure we can now describe the
`hcomp`

operations.

## Homogeneous composition¶

The homogeneous composition operations generalize binary composition of paths so that we can compose multiple composable cubes.

```
hcomp : ∀ {ℓ} {A : Set ℓ} {φ : I} (u : I → Partial φ A) (u0 : A) → A
```

When calling `hcomp {φ = φ} u u0`

Agda makes sure that `u0`

agrees
with `u i0`

on `φ`

. The idea is that `u0`

is the base and `u`

specifies the sides of an open box. This is hence an open (higher
dimensional) cube where the side opposite of `u0`

is missing. The
`hcomp`

operation then gives us the missing side opposite of
`u0`

. For example binary composition of paths can be written as:

```
compPath : ∀ {ℓ} {A : Set ℓ} {x y z : A} → x ≡ y → y ≡ z → x ≡ z
compPath {x = x} p q i = hcomp (λ{ j (i = i0) → x
; j (i = i1) → q j })
(p i)
```

Pictorially we are given `p : x ≡ y`

and `q : y ≡ z`

, and the
composite of the two paths is obtained by computing the missing lid of
this open square:

```
x z
^ ^
| |
x | | q j
| |
x ----------> y
p i
```

In the drawing the direction `i`

goes left-to-right and `j`

goes
bottom-to-top. As we are constructing a path from `x`

to `z`

along
`i`

we have `i : I`

in the context already and we put `p i`

as
bottom. The direction `j`

that we are doing the composition in is
abstracted in the first argument to `hcomp`

.

Note that the partial element `u`

does not have to specify
all the sides of the open box, giving more sides simply gives you
more control on the result of `hcomp`

.
For example if we omit the `(i = i0) → x`

side in the
definition of `compPath`

we still get a valid term of type
`A`

. However, that term would reduce to `hcomp (λ{ j () }) x`

when `i = i0`

and so that definition would not build
a path that starts from `x`

.

We can also define homogeneous filling of cubes as

```
hfill : ∀ {ℓ} {A : Set ℓ} {φ : I}
(u : ∀ i → Partial φ A) (u0 : A [ φ ↦ u i0 ])
(i : I) → A
hfill {φ = φ} u u0 i = hcomp (λ{ j (φ = i1) → u (i ∧ j) 1=1
; j (i = i0) → outS u0 })
(outS u0)
```

When `i`

is `i0`

this is `u0`

and when `i`

is `i1`

this is
`hcomp u u0`

. This can hence be seen as giving us the interior of an
open box. In the special case of the square above `hfill`

gives us a
direct cubical proof that composing `p`

with `refl`

is `p`

.

```
compPathRefl : ∀ {ℓ} {A : Set ℓ} {x y : A} (p : x ≡ y) → compPath p refl ≡ p
compPathRefl {x = x} {y = y} p j i = hfill (λ{ _ (i = i0) → x
; _ (i = i1) → y })
(inS (p i))
(~ j)
```

## Glue types¶

In order to be able to prove the univalence theorem we also have to
add “Glue” types. These lets us turn equivalences between types into
paths between types. An equivalence of types `A`

and `B`

is
defined as a map `f : A → B`

such that its fibers are contractible.

```
fiber : ∀ {ℓ} {A B : Set ℓ} (f : A → B) (y : B) → Set ℓ
fiber {A = A} f y = Σ[ x ∈ A ] f x ≡ y
isContr : ∀ {ℓ} → Set ℓ → Set ℓ
isContr A = Σ[ x ∈ A ] (∀ y → x ≡ y)
record isEquiv {ℓ} {A B : Set ℓ} (f : A → B) : Set ℓ where
field
equiv-proof : (y : B) → isContr (fiber f y)
_≃_ : ∀ {ℓ} (A B : Set ℓ) → Set ℓ
A ≃ B = Σ[ f ∈ (A → B) ] (isEquiv f)
```

The simplest example of an equivalence is the identity function.

```
idfun : ∀ {ℓ} → (A : Set ℓ) → A → A
idfun _ x = x
idIsEquiv : ∀ {ℓ} (A : Set ℓ) → isEquiv (idfun A)
equiv-proof (idIsEquiv A) y =
((y , refl) , λ z i → z .snd (~ i) , λ j → z .snd (~ i ∨ j))
idEquiv : ∀ {ℓ} (A : Set ℓ) → A ≃ A
idEquiv A = (idfun A , idIsEquiv A)
```

An important special case of equivalent types are isomorphic types (i.e. types with maps going back and forth which are mutually inverse).

As everything has to work up to higher dimensions the Glue types take
a partial family of types that are equivalent to the base type `A`

:

```
Glue : ∀ {ℓ ℓ'} (A : Set ℓ) {φ : I}
→ Partial φ (Σ[ T ∈ Set ℓ' ] T ≃ A) → Set ℓ'
```

These come with a constructor and eliminator:

```
glue : ∀ {ℓ ℓ'} {A : Set ℓ} {φ : I} {Te : Partial φ (Σ[ T ∈ Set ℓ' ] T ≃ A)}
→ PartialP φ T → A → Glue A Te
unglue : ∀ {ℓ ℓ'} {A : Set ℓ} (φ : I) {Te : Partial φ (Σ[ T ∈ Set ℓ' ] T ≃ A)}
→ Glue A Te → A
```

Using Glue types we can turn an equivalence of types into a path as follows:

```
ua : ∀ {ℓ} {A B : Set ℓ} → A ≃ B → A ≡ B
ua {_} {A} {B} e i = Glue B λ{ (i = i0) → (A , e)
; (i = i1) → (B , idEquiv B) }
```

The idea is that we glue `A`

together with `B`

when `i = i0`

using `e`

and `B`

with itself when `i = i1`

using the identity
equivalence. This hence gives us the key part of univalence: a
function for turning equivalences into paths. The other part of
univalence is that this map itself is an equivalence which follows
from the computation rule for `ua`

:

```
uaβ : ∀ {ℓ} {A B : Set ℓ} (e : A ≃ B) (x : A) → transport (ua e) x ≡ e .fst x
uaβ e x = transportRefl (e .fst x)
```

Transporting along the path that we get from applying `ua`

to an
equivalence is hence the same as applying the equivalence. This is
what makes it possible to use the univalence axiom computationally in
Cubical Agda: we can package up our equivalences as paths, do equality
reasoning using these paths, and in the end transport along the paths
in order to compute with the equivalences.

We have the following equalities:

```
Glue A {i1} Te = Te 1=1 .fst
unglue φ (glue t a) = a
glue (λ{ (φ = i1) → g }) (unglue φ g) = g
unglue i1 {Te} g = Te 1=1 .snd .fst g
glue {φ = i1} t a = t 1=1
```

For more results about Glue types and univalence see the files of Glue
types and univalence in the `agda/cubical`

library or the `1lab`

.

## Higher inductive types¶

Cubical Agda also lets us directly define higher inductive types as datatypes with path constructors. For example the circle and torus can be defined as:

```
data S¹ : Set where
base : S¹
loop : base ≡ base
data Torus : Set where
point : Torus
line1 : point ≡ point
line2 : point ≡ point
square : PathP (λ i → line1 i ≡ line1 i) line2 line2
```

Functions out of higher inductive types can then be defined using pattern-matching:

```
t2c : Torus → S¹ × S¹
t2c point = (base , base)
t2c (line1 i) = (loop i , base)
t2c (line2 j) = (base , loop j)
t2c (square i j) = (loop i , loop j)
c2t : S¹ × S¹ → Torus
c2t (base , base) = point
c2t (loop i , base) = line1 i
c2t (base , loop j) = line2 j
c2t (loop i , loop j) = square i j
```

When giving the cases for the path and square constructors we have to
make sure that the function maps the boundary to the right thing. For
instance the following definition does not pass Agda’s typechecker as
the boundary of the last case does not match up with the expected
boundary of the square constructor (as the `line1`

and `line2`

cases are mixed up).

```
c2t_bad : S¹ × S¹ → Torus
c2t_bad (base , base) = point
c2t_bad (loop i , base) = line2 i
c2t_bad (base , loop j) = line1 j
c2t_bad (loop i , loop j) = square i j
```

Functions defined by pattern-matching on higher inductive types compute definitionally, for all constructors.

```
c2t-t2c : ∀ (t : Torus) → c2t (t2c t) ≡ t
c2t-t2c point = refl
c2t-t2c (line1 _) = refl
c2t-t2c (line2 _) = refl
c2t-t2c (square _ _) = refl
t2c-c2t : ∀ (p : S¹ × S¹) → t2c (c2t p) ≡ p
t2c-c2t (base , base) = refl
t2c-c2t (base , loop _) = refl
t2c-c2t (loop _ , base) = refl
t2c-c2t (loop _ , loop _) = refl
```

By turning this isomorphism into an equivalence we get a direct proof that the torus is equal to two circles.

```
Torus≡S¹×S¹ : Torus ≡ S¹ × S¹
Torus≡S¹×S¹ = isoToPath (iso t2c c2t t2c-c2t c2t-t2c)
```

Cubical Agda also supports parameterized and recursive higher inductive types, for example propositional truncation (squash types) is defined as:

```
data ∥_∥ {ℓ} (A : Set ℓ) : Set ℓ where
∣_∣ : A → ∥ A ∥
squash : ∀ (x y : ∥ A ∥) → x ≡ y
isProp : ∀ {ℓ} → Set ℓ → Set ℓ
isProp A = (x y : A) → x ≡ y
recPropTrunc : ∀ {ℓ} {A : Set ℓ} {P : Set ℓ} → isProp P → (A → P) → ∥ A ∥ → P
recPropTrunc Pprop f ∣ x ∣ = f x
recPropTrunc Pprop f (squash x y i) =
Pprop (recPropTrunc Pprop f x) (recPropTrunc Pprop f y) i
```

For many more examples of higher inductive types see the
`agda/cubical`

library or the `1lab`

.

## Indexed inductive types¶

Cubical Agda has experimental support for the `transp`

primitive when
used to substitute the indices of an indexed inductive type. A handful
of definitions (satisfying a technical restriction on their pattern
matching) will compute when applied to a transport along indices. As an
example of what works, let us consider the following running example:

```
data Eq {a} {A : Set a} (x : A) : A → Set a where
reflEq : Eq x x
data Vec {a} (A : Set a) : Nat → Set a where
[] : Vec A zero
_∷_ : ∀ {n} → A → Vec A n → Vec A (suc n)
```

Functions which match on `Eq`

when all of its endpoints are variables,
that is, very generic lemmas like `symEq`

and `transpEq`

below, will
compute on all cases: they will compute to the given right-hand-side
definitionally when their argument is `reflEq`

, and will compute to a
transport in the codomain when their argument has been transported in
the second variable.

```
symEq : ∀ {a} {A : Set a} {x y : A} → Eq x y → Eq y x
symEq reflEq = reflEq
transpEq : ∀ {a} {A B : Set a} → Eq A B → A → B
transpEq reflEq x = x
pathToEq : ∀ {a} {A : Set a} {x y : A} → x ≡ y → Eq x y
pathToEq {x = x} p = transp (λ i → Eq x (p i)) i0 reflEq
module _ {a} {A B : Set a} {x y : A} {f : A ≃ B} where
_ : symEq (reflEq {x = x}) ≡ reflEq
_ = refl
_ : transpEq (pathToEq (ua (idEquiv Bool))) ≡ λ x → x
_ = refl
```

Matching on indexed types in situations where types are assumed (so
their transports are also open) often generates many more transports
than the comparable construction with paths would. As an example,
compare the proof of `uaβEq`

below has four pending transports,
whereas `uaβ`

only has one!

```
uaβEq : transpEq (pathToEq (ua f)) ≡ f .fst
uaβEq = funExt λ z →
compPath (transportRefl (f .fst _))
(cong (f .fst) (compPath
(transportRefl _)
(compPath
(transportRefl _)
(transportRefl _))))
```

In more concrete situations, such as when the indices are constructors of some other inductive type, pattern-matching definitions will not compute when applied to transports. For specific unsupported cases, see What works, and what doesn’t.

If the `UnsupportedIndexedMatch`

warning is enabled (it is by default),
Agda will print a warning for every definition whose computational
behaviour could not be extended to cover transports. Internally,
transports are represented by an additional constructor, and
pattern-matching definitions must be extended to cover these
constructors. To do this, the results of pattern-matching unification
must be translated into an embedding (in the HoTT sense).
**This is work-in-progress.**

For the day-to-day use of Cubical Agda, it is advisable to disable the
`UnsupportedIndexedMatch`

warnings. You can do this using the
`-WnoUnsupportedIndexedMatch`

option in an `OPTIONS`

pragma or in your
`agda-lib`

file.

### What works, and what doesn’t¶

This section lists some of the common cases where pattern-matching unification produces something that can not be extended to cover transports, and the cases in which it can.

The following pair of definitions relies on injectivity for data
constructors (specifically of the constructor `suc`

), and so will not
compute on transported values.

```
sucInjEq : ∀ {n k} → Eq (suc n) (suc k) → Eq n k
sucInjEq reflEq = reflEq
head : ∀ {n} {a} {A : Set a} → Vec A (suc n) → A
head (x ∷ _) = x
```

To demonstrate the failure of computation, we can set up the following
artificial example using `head`

. By passing the vector `true ∷ []`

through two transports, even if they would cancel out, `head`

’s
computation gets stuck.

```
module _ (n : Nat) (p : n ≡ 1) where private
vec : Vec Bool n
vec = transport (λ i → Vec Bool (p (~ i))) (true ∷ [])
hd : Bool
hd = head (transport (λ i → Vec Bool (p i)) vec)
-- Does not type-check:
-- _ : hd ≡ true
-- _ = refl
-- Instead, hd is some big expression involving head applied to a
-- transport
```

If a definition is stuck on a transport, often the best workaround is to
avoid treating it like the reducible expression it should be, and
managing the transports yourself. For example, using the proof that
`transport (sym p) (transport p x) ≡ x`

, we can compute with `hd`

up
to a path, even if it’s definitionally stuck.

```
-- Continuing from above..
_ : hd ≡ true
_ = cong head (transport⁻Transport (λ i → Vec Bool (p (~ i))) (true ∷ []))
```

In other cases, it may be possible to rephrase the proof in ways that
avoid unsupported cases in pattern matching, and so, compute. For
example, returning to `sucInj`

, we can define it in terms of `apEq`

(which always computes), and the fact that `suc`

has a
partially-defined inverse:

```
apEq : ∀ {a b} {A : Set a} {B : Set b} (f : A → B) {x y : A}
→ Eq x y → Eq (f x) (f y)
apEq f reflEq = reflEq
sucInjEq′ : ∀ {n k} → Eq (suc n) (suc k) → Eq n k
sucInjEq′ = apEq λ{ (suc n) → n ; zero → zero }
```

Definitions which rely on principles incompatible with Cubical Agda (K,
injectivity of type constructors) will never compute on transports. Note
that enabling both Cubical and K is not compatible with `--safe`

.

Absurd clauses do not need any special handling (since the transport of
an absurdity is still absurd), so definitions which rely on Agda’s
ability to automatically separate constructors of inductive types will
not generate a `UnsupportedIndexedMatch`

warning.

```
zeroNotSucEq : ∀ {n} {a} {A : Set a} → Eq zero (suc n) → A
zeroNotSucEq ()
```

Definitions whose elaboration involves using an equality derived from
pattern-matching in a type in `Setω`

can not be extended yet. The
following example is very artificial because it minimises
an example from the Cubical library.
The point is that to extend `test`

to cover transports, we would need
to, given `p : ℓ′ ≡ ℓ`

, produce a `PathP (λ i → Argh ℓ (p i)) _ _`

,
but `Setω`

is not considered fibrant yet.

```
data Argh (ℓ : Level) : Level → Setω where
argh : ∀ {ℓ′} → Argh ℓ ℓ′ → Argh ℓ ℓ′
test : ∀ {ℓ ℓ′} → Argh ℓ ℓ′ → Bool
test {ℓ} (argh _) = true
```

### Modalities & indexed matching¶

When using indexed matching in Cubical Agda, clauses’ arguments (and
their right-hand-sides) need to be transported to account for indexing,
meaning that the *types* of those arguments must be well-formed *terms*.

For example, the following code is forbidden in Cubical Agda, and when
`--without-K`

is enabled:

```
subst : (@0 P : A → Set p) → x ≡ y → P x → P y
subst _ refl p = p
```

This is because the predicate `P`

is erased, but internally, we have
to transport along the argument `p`

along a path involving `P`

, in a
relevant position.

Any argument which is used in the result type, or appears after a forced (dot) pattern, must have a modality-correct type.

## Cubical Agda with erased Glue¶

The option `--erased-cubical`

enables a variant of Cubical
Agda in which Glue (and the other builtins defined in
`Agda.Builtin.Cubical.Glue`

) must only be used in
erased settings.

Regular Cubical Agda code can import code that uses
`--erased-cubical`

. Regular Cubical Agda code can also be
imported from code that uses `--erased-cubical`

, but names
defined using Cubical Agda can only be used if the option
`--erasure`

is used. In that case the names are treated as if
they had been marked as erased, with an exception related to pattern
matching:

Matching on a non-erased imported constructor does not, on its own, make Agda treat the right-hand side as erased.

The reason for this exception is that it should be possible to import
the code from modules that use `--cubical`

, in which the
non-erased constructors are not treated as erased.

Note that names that are re-exported from a Cubical Agda module using
`open import M args public`

are seen as defined using Cubical Agda.

## References¶

Cyril Cohen, Thierry Coquand, Simon Huber and Anders Mörtberg; “Cubical Type Theory: a constructive interpretation of the univalence axiom”.

Thierry Coquand, Simon Huber, Anders Mörtberg; “On Higher Inductive Types in Cubical Type Theory”.

## Appendix: Cubical Agda primitives¶

The Cubical Agda primitives and internals are exported by a series of
files found in the `lib/prim/Agda/Builtin/Cubical`

directory of
Agda. The `agda/cubical`

library exports all of these primitives
with the names used throughout this document. Experts might find it
useful to know what is actually exported as there are quite a few
primitives available that are not really exported by `agda/cubical`

,
so the goal of this section is to list the contents of these
files. However, for regular users and beginners the `agda/cubical`

library should be sufficient and this section can safely be ignored.

**Warning**: Many of the built-ins whose definitions can be written in
Agda are nonetheless used internally in the implementation of cubical Agda,
and using different implementations can easily lead to unsoundness. Even
though they are definable in user code, this is not a supported
use-case.

The key file with primitives is `Agda.Primitive.Cubical`

. It exports
the following `BUILTIN`

, primitives and postulates:

```
{-# BUILTIN CUBEINTERVALUNIV IUniv #-} -- IUniv : SSet₁
{-# BUILTIN INTERVAL I #-} -- I : IUniv
{-# BUILTIN IZERO i0 #-}
{-# BUILTIN IONE i1 #-}
infix 30 primINeg
infixr 20 primIMin primIMax
primitive
primIMin : I → I → I -- _∧_
primIMax : I → I → I -- _∨_
primINeg : I → I -- ~_
{-# BUILTIN ISONE IsOne #-} -- IsOne : I → SSet
postulate
itIsOne : IsOne i1 -- 1=1
IsOne1 : ∀ i j → IsOne i → IsOne (primIMax i j)
IsOne2 : ∀ i j → IsOne j → IsOne (primIMax i j)
{-# BUILTIN ITISONE itIsOne #-}
{-# BUILTIN ISONE1 IsOne1 #-}
{-# BUILTIN ISONE2 IsOne2 #-}
{-# BUILTIN PARTIAL Partial #-}
{-# BUILTIN PARTIALP PartialP #-}
postulate
isOneEmpty : ∀ {a} {A : Partial i0 (Set a)} → PartialP i0 A
{-# BUILTIN ISONEEMPTY isOneEmpty #-}
primitive
primPOr : ∀ {a} (i j : I) {A : Partial (primIMax i j) (Set a)}
→ PartialP i (λ z → A (IsOne1 i j z)) → PartialP j (λ z → A (IsOne2 i j z))
→ PartialP (primIMax i j) A
-- Computes in terms of primHComp and primTransp
primComp : ∀ {a} (A : (i : I) → Set (a i)) {φ : I} → (∀ i → Partial φ (A i)) → (a : A i0) → A i1
syntax primPOr p q u t = [ p ↦ u , q ↦ t ]
primitive
primTransp : ∀ {a} (A : (i : I) → Set (a i)) (φ : I) → (a : A i0) → A i1
primHComp : ∀ {a} {A : Set a} {φ : I} → (∀ i → Partial φ A) → A → A
```

The interval `I`

belongs to its own sort, `IUniv`

. Types in this sort
do not support composition and transport (unlike `Set`

), but function
types from types in this sort to types in `Set`

do (unlike SSet).

The Path types are exported by `Agda.Builtin.Cubical.Path`

:

```
postulate
PathP : ∀ {ℓ} (A : I → Set ℓ) → A i0 → A i1 → Set ℓ
{-# BUILTIN PATHP PathP #-}
infix 4 _≡_
_≡_ : ∀ {ℓ} {A : Set ℓ} → A → A → Set ℓ
_≡_ {A = A} = PathP (λ _ → A)
{-# BUILTIN PATH _≡_ #-}
```

The Cubical subtypes are exported by `Agda.Builtin.Cubical.Sub`

:

```
{-# BUILTIN SUB Sub #-}
postulate
inc : ∀ {ℓ} {A : Set ℓ} {φ} (x : A) → Sub A φ (λ _ → x)
{-# BUILTIN SUBIN inS #-}
primitive
primSubOut : ∀ {ℓ} {A : Set ℓ} {φ : I} {u : Partial φ A} → Sub _ φ u → A
```

Equivalences are exported by `Agda.Builtin.Cubical.Equiv`

:

```
record isEquiv {ℓ ℓ'} {A : Set ℓ} {B : Set ℓ'} (f : A → B) : Set (ℓ ⊔ ℓ') where
field
equiv-proof : (y : B) → isContr (fiber f y)
infix 4 _≃_
_≃_ : ∀ {ℓ ℓ'} (A : Set ℓ) (B : Set ℓ') → Set (ℓ ⊔ ℓ')
A ≃ B = Σ (A → B) λ f → isEquiv f
equivFun : ∀ {ℓ ℓ'} {A : Set ℓ} {B : Set ℓ'} → A ≃ B → A → B
equivFun e = fst e
equivProof : ∀ {la lt} (T : Set la) (A : Set lt) → (w : T ≃ A) → (a : A)
→ ∀ ψ (f : Partial ψ (fiber (w .fst) a)) → fiber (w .fst) a [ ψ ↦ f ]
equivProof A B w a ψ fb = contr' {A = fiber (w .fst) a} (w .snd .equiv-proof a) ψ fb
where
contr' : ∀ {ℓ} {A : Set ℓ} → isContr A → (φ : I) → (u : Partial φ A) → A
contr' {A = A} (c , p) φ u = hcomp (λ{ i (φ = i1) → p (u 1=1) i
; i (φ = i0) → c }) c
{-# BUILTIN EQUIV _≃_ #-}
{-# BUILTIN EQUIVFUN equivFun #-}
{-# BUILTIN EQUIVPROOF equivProof #-}
```

The Glue types are exported by `Agda.Builtin.Cubical.Glue`

:

```
open import Agda.Builtin.Cubical.Equiv public
primitive
primGlue : ∀ {ℓ ℓ'} (A : Set ℓ) {φ : I}
→ (T : Partial φ (Set ℓ')) → (e : PartialP φ (λ o → T o ≃ A))
→ Set ℓ'
prim^glue : ∀ {ℓ ℓ'} {A : Set ℓ} {φ : I}
→ {T : Partial φ (Set ℓ')} → {e : PartialP φ (λ o → T o ≃ A)}
→ PartialP φ T → A → primGlue A T e
prim^unglue : ∀ {ℓ ℓ'} {A : Set ℓ} {φ : I}
→ {T : Partial φ (Set ℓ')} → {e : PartialP φ (λ o → T o ≃ A)}
→ primGlue A T e → A
primFaceForall : (I → I) → I
```

Note that the Glue types are uncurried in `agda/cubical`

to make
them more pleasant to use:

```
Glue : ∀ {ℓ ℓ'} (A : Set ℓ) {φ : I}
→ (Te : Partial φ (Σ[ T ∈ Set ℓ' ] T ≃ A))
→ Set ℓ'
Glue A Te = primGlue A (λ x → Te x .fst) (λ x → Te x .snd)
```

The `Agda.Builtin.Cubical.Id`

exports the cubical identity types:

```
postulate
Id : ∀ {ℓ} {A : Set ℓ} → A → A → Set ℓ
{-# BUILTIN ID Id #-}
{-# BUILTIN CONID conid #-}
{-# BUILTIN REFLID reflId #-}
primitive
primDepIMin : _
primIdFace : ∀ {ℓ} {A : Set ℓ} {x y : A} → Id x y → I
primIdPath : ∀ {ℓ} {A : Set ℓ} {x y : A} → Id x y → x ≡ y
primitive
primIdElim : ∀ {a c} {A : Set a} {x : A}
(C : (y : A) → Id x y → Set c) →
((φ : I) (y : A [ φ ↦ (λ _ → x) ])
(w : (x ≡ outS y) [ φ ↦ λ{ (φ = i1) _ → x } ]) →
C (outS y) (conid φ (outS w))) →
{y : A} (p : Id x y) → C y p
```