Update readme; add trailing zero; tmp remove use; revise docs

.github/workflows/ci.yml

@@ -17,7 +17,7 @@ jobs:
         with:
           otp-version: "25.1"
           elixir-version: "1.14.2"
-          gleam-version: nightly
+          gleam-version: "0.24.0"
 
       - uses: actions/setup-node@v3
         with:

README.md

@@ -49,42 +49,100 @@ end
 
 ### JavaScript
 
-The `@tensorflow/tfjs` package is a runtime requirement for `argamak`, and its
+The `@tensorflow/tfjs` package is a runtime requirement for `argamak`; its
 import path in the `argamak_ffi.mjs` module might need adjustment, depending on
 your use case.
 
 ## Usage
 
 ```gleam
 // derby.gleam
+import argamak/axis.{Axis, Infer}
 import argamak/space
-import argamak/tensor
-
-pub type Axis {
-  Horse
-  Trial
-}
-
-pub fn print_times(from list: List(Float)) {
-  assert Ok(space) = space.d2(#(Horse, 3), #(Trial, -1))
-  try tensor = tensor.from_floats(of: list, into: space)
-
-  tensor
-  |> tensor.print(wrap_at: -1, meta: True)
+import argamak/tensor.{InvalidData, TensorError}
+import gleam/function
+import gleam/io
+import gleam/list
+import gleam/result
+import gleam/string
+
+pub fn announce_winner(
+  from horses: List(String),
+  with times: List(Float),
+) -> Result(Nil, TensorError) {
+  assert Ok(d2) = space.d2(Infer("Horse"), Axis("Trial", 2))
+  try x = tensor.from_floats(of: times, into: d2)
+
+  let announce = function.compose(string.inspect, io.println)
+
+  announce("Trial times per horse")
+  tensor.print(x)
+
+  announce("Mean time per horse")
+  let mean_times =
+    x
+    |> tensor.mean(with: fn(a) { axis.name(a) == "Trial" })
+    |> tensor.debug
+
+  let all_axes = fn(_) { True }
+
+  announce("Fastest mean time")
+  let time =
+    mean_times
+    |> tensor.min_over(with: all_axes)
+    |> tensor.debug
+    |> tensor.to_string(return: tensor.Data, wrap_at: 0)
+
+  announce("Fastest horse")
+  try horse =
+    mean_times
+    |> tensor.arg_min(with: all_axes)
+    |> tensor.debug
+    |> tensor.to_int
+  try horse =
+    horses
+    |> list.at(get: horse)
+    |> result.replace_error(InvalidData)
+
+  horse <> " wins the day with a mean time of " <> time <> " minutes!"
+  |> announce
   |> Ok
 }
 ```
 
 ### Example
 
 ```gleam
-> derby.print_times(from: [1.2, 1.3, 1.3, 1., 1.5, 0.9])
-// Tensor
-// format: Float32
-// space: D2 #(Horse, 3), #(Trial, 2)
-// data:
-// [[1.2, 1.3],
-//  [1.3, 1.0],
-//  [1.5, 0.9]]
+> derby.announce_winner(
+>   from: ["Pony Express", "Hay Girl", "Low Rider"],
+>   with: [1.2, 1.3, 1.3, 1.0, 1.5, 0.9],
+> )
+"Trial times per horse"
+Tensor(
+  Format(Float32),
+  Space(Axis("Horse", 3), Axis("Trial", 2)),
+  [[1.2, 1.3],
+   [1.3, 1.0],
+   [1.5, 0.9]],
+)
+"Mean time per horse"
+Tensor(
+  Format(Float32),
+  Space(Axis("Horse", 3)),
+  [1.25, 1.15,  1.2],
+)
+"Fastest mean time"
+Tensor(
+  Format(Float32),
+  Space(),
+  1.15,
+)
+"Fastest horse"
+Tensor(
+  Format(Float32),
+  Space(),
+  1.0,
+)
+"Hay Girl wins the day with a mean time of 1.15 minutes!"
 Ok(Nil)
 ```

src/argamak/axis.gleam

@@ -180,12 +180,8 @@ pub fn rename(x: Axis, name: String) -> Axis {
 
 /// Changes the `size` of the given `Axis`.
 ///
-/// If an `Axis` is renamed to a single capital letter (from `"A"` to `"Z"`
-/// inclusive), the single-letter convenience constructor will be used for the
-/// new `Axis`. 
-///
 /// Resizing an `Infer` returns an `Axis` record that will no longer have its
-/// `size` automatically computed as needed.
+/// `size` automatically computed.
 ///
 /// ## Examples
 ///

src/argamak/format.gleam

@@ -2,32 +2,34 @@ import gleam/string
 
 /// Numerical formats for tensors.
 ///
-/// Each `Format` uses a set number of bits to to represent every `Float`-like
-/// or `Int`-like value.
+/// Each `Format` uses a set number of bits to represent every `Float`-like or
+/// `Int`-like value.
 ///
 pub opaque type Format(a) {
   Format(a)
 }
 
-/// A 32-bit floating point type.
+/// A 32-bit floating point type, argamak's standard for working with floats.
 ///
 pub type Float32 {
   Float32
 }
 
-/// Creates a 32-bit floating point `Format`.
+/// Creates a 32-bit floating point `Format`, argamak's standard for working
+/// with floats.
 ///
 pub fn float32() -> Format(Float32) {
   Format(Float32)
 }
 
-/// A 32-bit signed integer type.
+/// A 32-bit signed integer type, argamak's standard for working with ints.
 ///
 pub type Int32 {
   Int32
 }
 
-/// Creates a 32-bit signed integer `Format`.
+/// Creates a 32-bit signed integer `Format`, argamak's standard for working
+/// with ints.
 ///
 pub fn int32() -> Format(Int32) {
   Format(Int32)

src/argamak/space.gleam

@@ -40,15 +40,16 @@ pub type SpaceResult =
 /// ## Examples
 ///
 /// ```gleam
-/// > new() |> elements
+/// > new() |> axes
 /// []
 /// ```
 ///
 pub fn new() -> Space {
   Space(axes: [])
 }
 
-/// Results in a 1-dimensional `Space` on success, or `SpaceErrors` on failure.
+/// Results in a one-dimensional `Space` on success, or `SpaceErrors` on
+/// failure.
 ///
 /// ## Examples
 ///
@@ -65,7 +66,8 @@ pub fn d1(a: Axis) -> SpaceResult {
   |> validate
 }
 
-/// Results in a 2-dimensional `Space` on success, or `SpaceErrors` on failure.
+/// Results in a two-dimensional `Space` on success, or `SpaceErrors` on
+/// failure.
 ///
 /// ## Examples
 ///
@@ -82,7 +84,8 @@ pub fn d2(a: Axis, b: Axis) -> SpaceResult {
   |> validate
 }
 
-/// Results in a 3-dimensional `Space` on success, or `SpaceErrors` on failure.
+/// Results in a three-dimensional `Space` on success, or `SpaceErrors` on
+/// failure.
 ///
 /// ## Examples
 ///
@@ -99,7 +102,8 @@ pub fn d3(a: Axis, b: Axis, c: Axis) -> SpaceResult {
   |> validate
 }
 
-/// Results in a 4-dimensional `Space` on success, or `SpaceErrors` on failure.
+/// Results in a four-dimensional `Space` on success, or `SpaceErrors` on
+/// failure.
 ///
 /// ## Examples
 ///
@@ -116,7 +120,8 @@ pub fn d4(a: Axis, b: Axis, c: Axis, d: Axis) -> SpaceResult {
   |> validate
 }
 
-/// Results in a 5-dimensional `Space` on success, or `SpaceErrors` on failure.
+/// Results in a five-dimensional `Space` on success, or `SpaceErrors` on
+/// failure.
 ///
 /// ## Examples
 ///
@@ -133,7 +138,8 @@ pub fn d5(a: Axis, b: Axis, c: Axis, d: Axis, e: Axis) -> SpaceResult {
   |> validate
 }
 
-/// Results in a 6-dimensional `Space` on success, or `SpaceErrors` on failure.
+/// Results in a six-dimensional `Space` on success, or `SpaceErrors` on
+/// failure.
 ///
 /// ## Examples
 ///
@@ -150,7 +156,8 @@ pub fn d6(a: Axis, b: Axis, c: Axis, d: Axis, e: Axis, f: Axis) -> SpaceResult {
   |> validate
 }
 
-/// Results in a `Space` on success, or `SpaceErrors` on failure.
+/// Results in a `Space` created from a list of `Axes` on success, or
+/// `SpaceErrors` on failure.
 ///
 /// ## Examples
 ///
@@ -285,6 +292,8 @@ pub fn map(x: Space, with fun: fn(Axis) -> Axis) -> SpaceResult {
 /// Results in a new `Space` that is the element-wise maximum of the given
 /// spaces on success, or `SpaceErrors` on failure.
 ///
+/// Spaces are merged tail-first, and corresponding `Axis` names must match.
+///
 /// ## Examples
 ///
 /// ```gleam