1 files changed, 50 insertions, 0 deletions
diff --git a/README.md b/README.md
index 81a71f2..9b8d543 100644
--- a/README.md
+++ b/README.md
@@ -4,3 +4,53 @@ struct-of-arrays form via the `Data.Vector.Unboxed` data family trick. Below
 the surface layer, there is a more low-level wrapper around `orthotope` that
 defines an array type type-indexed by `[Maybe Nat]`: some dimensions are
 shape-typed (i.e. have their size statically known), and some not.
+
+An overview of the API:
+
+```haskell
+data Ranked (n :: INat) a               {- e.g. -}  Ranked 3 Float
+data Shaped (sh :: '[Nat]) a            {- e.g. -}  Shaped [2,3,4] Float
+data Mixed (xsh :: '[Maybe Nat]) a      {- e.g. -}  Mixed [Just 2, Nothing, Just 4] Float
+ 
+Ranked I0 a = Ranked Z a          ~~=  Acc.Array Z a                 = Acc.Scalar a
+Ranked I1 a = Ranked (S Z) a      ~~=  Acc.Array (Z :. Int) a        = Acc.Vector a
+Ranked I2 a = Ranked (S (S Z)) a  ~~=  Acc.Array (Z :. Int :. Int) a = Acc.Matrix a
+
+
+rshape :: (Elt a, KnownINat n)     => Ranked n a  -> IxR n
+sshape :: (Elt a, KnownShape sh)   => Shaped sh a -> IxS sh
+mshape :: (Elt a, KnownShapeX xsh) => Mixed xsh a -> IxX xsh
+
+rindex :: Elt a => Ranked n a  -> IxR n   -> a
+sindex :: Elt a => Shaped sh a -> IxS sh  -> a
+mindex :: Elt a => Mixed xsh a -> IxX xsh -> a
+
+data IxR n where
+  IZR :: IxR Z
+  (:::) :: Int -> IxR n -> IxR (S n)
+
+data IxS sh where
+  IZS :: IxS '[]
+  (::$) :: Int -> IxS sh -> IxS (n : sh)
+
+data IxX sh where
+  IZX :: IxX '[]
+  (::@) :: Int -> IxX sh -> IxX (Just n : sh)
+  (::?) :: Int -> IxX sh -> IxX (Nothing : sh)
+
+class Elt a
+instance                             Elt ()
+instance                             Elt Double
+instance                             Elt Int
+instance (Elt a, Elt b)           => Elt (a, b)
+instance (Elt a, KnownINat n)     => Elt (Ranked n a)
+instance (Elt a, KnownShape sh)   => Elt (Shaped sh a)
+instance (Elt a, KnownShapeX xsh) => Elt (Mixed xsh a)
+
+rgenerate :: Elt a                    => IxR n   -> (IxR n   -> a) -> Ranked n a
+sgenerate :: (Elt a, KnownShape sh)   =>            (IxS sh  -> a) -> Shaped sh a
+mgenerate :: (Elt a, KnownShapeX xsh) => IxX xsh -> (IxX xsh -> a) -> Mixed xsh a
+
+newtype Ranked n  a = Ranked (Mixed (Replicate n Nothing) a)
+newtype Shaped sh a = Shaped (Mixed (MapJust sh)          a)
+```