mutable/matrix Tutorial

Small Case: Calibrate A Dense Numeric Matrix

///|
fn calibrate_dense_matrix(matrix : @mutable.Matrix[Double]) -> Double {
  let first_row = matrix.row_view(0)
  first_row[1] = 9.0
  let first_col = matrix.col_view(0)
  first_col[1] = 5.0
  matrix.determinant().unwrap()
}

///|
test "mutable matrix tutorial case" {
  let matrix = @mutable.Matrix::from_2d_array([[1.0, 2.0], [3.0, 4.0]])
  let det = calibrate_dense_matrix(matrix)

  inspect(matrix, content="|1, 9|\n|5, 4|")
  inspect(det, content="-41")
  inspect(matrix.inverse() is Ok(_), content="true")
}

This pattern works well when a matrix is a live working buffer:

1. Build the matrix once.
2. Use row_view and col_view to patch the hot regions directly.
3. Run checked numeric APIs like determinant() and inverse() after the edits are complete.

That combination is the fastest path when the matrix is a concrete execution object rather than a historical value.

Suggested Flow

1. Build matrices with Matrix::from_2d_array, Matrix::make, Matrix::new, or Matrix::from_array.
2. Use get and set for direct element access, and row_view / col_view for repeated row or column work.
3. Use checked methods such as trace, determinant, inverse, mul_vec, and pow when inputs may fail at runtime.

Practical Guidance

• Use to_transpose() when you need a live transposed view; use transpose() when you need a materialized matrix.
• Use unchecked_* only after shape, non-emptiness, and singularity preconditions have already been enforced.
• Reach for row/column views when one region of the matrix will be updated or inspected repeatedly.