Sane behavior and helpers for vectors, rows, matrix, lists

.github/workflows/tests.yml

@@ -1,22 +1,27 @@
-name: tests
+name: ci
 
 on:
   push:
-    branches: [ master ]
+    branches: [master]
   pull_request:
-    branches: [ master ]
+    branches: [master]
 
 env:
   CARGO_TERM_COLOR: always
 
 jobs:
-  build:
-
+  test:
     runs-on: ubuntu-latest
-
     steps:
-      - uses: actions/checkout@v2
-      - name: Build
-        run: cargo build --verbose --all-features
-      - name: Run tests
-        run: cargo test --verbose --all-features
+      - uses: actions/checkout@v4
+      - uses: actions-rs/toolchain@v1
+        with:
+          toolchain: stable
+          override: true
+          components: rustfmt
+      - uses: Swatinem/rust-cache@v2
+      - name: Format
+        run: cargo fmt --all -- --check
+      - name: Test
+        run: cargo test --no-default-features --features rand,nalgebra
+

README.md

@@ -2,52 +2,112 @@
 [![Crates.io](https://img.shields.io/crates/v/rhai-sci.svg)](https://crates.io/crates/rhai-sci)
 [![docs.rs](https://img.shields.io/docsrs/rhai-sci/latest?logo=rust)](https://docs.rs/rhai-sci)
 
-# About `rhai-sci`
+# rhai-sci
 
-This crate provides some basic scientific computing utilities for the [`Rhai`](https://rhai.rs/) scripting language,
-inspired by languages like MATLAB, Octave, and R. For a complete API reference,
-check [the docs](https://docs.rs/rhai-sci).
+## What & Why
 
-# Install
+`rhai-sci` adds basic scientific computing utilities to the [Rhai](https://rhai.rs/) scripting language. It is inspired by tools such as MATLAB, Octave, and R.
 
-To use the latest released version of `rhai-sci`, add this to your `Cargo.toml`:
+## Quickstart
+
+Add the crate to your `Cargo.toml`:
 
 ```toml
-rhai-sci = "0.2.3"
+rhai-sci = "0.3.0"
 ```
 
-# Usage
-
-Using this crate is pretty simple! If you just want to evaluate a single line of [`Rhai`](https://rhai.rs/), then you
-only need:
+Evaluate a single line of Rhai code:
 
 ```rust
 use rhai::INT;
 use rhai_sci::eval;
+
 let result = eval::<INT>("argmin([43, 42, -500])").unwrap();
 ```
 
-If you need to use `rhai-sci` as part of a persistent [`Rhai`](https://rhai.rs/) scripting engine, then do this instead:
+## Examples
+
+Integrate the package with a persistent Rhai engine:
 
 ```rust
-use rhai::{Engine, packages::Package, INT};
+use rhai::{packages::Package, Engine, INT};
 use rhai_sci::SciPackage;
 
-// Create a new Rhai engine
 let mut engine = Engine::new();
-
-// Add the rhai-sci package to the new engine
 engine.register_global_module(SciPackage::new().as_shared_module());
 
-// Now run your code
 let value = engine.eval::<INT>("argmin([43, 42, -500])").unwrap();
 ```
 
-# Features
+See the `examples` directory for more:
+
+- `matrix_inversion.rhai` demonstrates matrix inversion.
+- `download_and_regress.rhai` fetches data and performs linear regression.
+- `projectile_motion.rhai` uses trigonometry and array utilities to simulate a projectile trajectory.
+- `neural_network_backprop.rhai` trains a tiny neural network on XOR with explicit backpropagation.
+
+## Matrix and Vector Conventions
+
+Rhai arrays remain the storage model. Use constructors when shape matters:
+
+```typescript
+let values = [1, 2, 3];        // plain Rhai list
+let x = vec([1, 2, 3]);        // column vector: [[1], [2], [3]]
+let c = col([1, 2, 3]);        // column vector: [[1], [2], [3]]
+let r = row([1, 2, 3]);        // row vector: [[1, 2, 3]]
+let A = mat([[1, 2], [3, 4]]); // validated matrix
+```
+
+For compact matrix literals, use strings with whitespace, commas, and semicolons:
+
+```typescript
+let A = mat("1 2; 3 4");
+let B = M("1, 2; 3, 4");
+let r = R("1 2 3");
+let c = C("1; 2; 3");
+```
+
+The short aliases keep linear algebra scripts readable:
+
+```typescript
+let A = mat("1 2; 3 4");
+let x = col([5, 6]);
+let y = row([7, 8]);
+
+let z = dot(A, x);
+let z2 = A.dot(x);
+let At = T(A);
+let C = hcat(A, x);
+let D = vcat(A, y);
+```
+
+### Features
+
+- **metadata** *(disabled)*: export function metadata; required for running doc-tests on Rhai examples.
+- **io** *(enabled)*: provides `read_matrix` but pulls in `polars`, `url`, `temp-file`, `csv-sniffer`, and `minreq`.
+- **nalgebra** *(enabled)*: enables matrix functions such as `regress`, `inv`, `mtimes`, `horzcat`, `vertcat`, `repmat`, `svd`, `hessenberg`, and `qr` via the `nalgebra` and `linregress` crates.
+- **rand** *(enabled)*: adds the `rand` function for generating random values and matrices using the `rand` crate.
+
+## CLI/API reference
+
+The full API is documented on [docs.rs](https://docs.rs/rhai-sci).
+
+## Development
+
+```bash
+cargo fmt --all -- --check
+cargo test --no-default-features --features rand,nalgebra
+```
+
+## Troubleshooting
+
+- Building with the `io` feature enabled pulls in heavy dependencies. Disable default features and enable only what you need if builds are slow.
+
+## License
+
+Licensed under either of
+
+- [MIT license](LICENSE-MIT.txt)
+- [Apache License, Version 2.0](LICENSE-APACHE.txt)
 
-| Feature    | Default  | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
-|------------|----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `metadata` | Disabled | Enables exporting function metadata and is ___necessary for running doc-tests on Rhai examples___.                                                                                                                                                                                                                                                                                                                                                                                                                    |
-| `io`       | Enabled  | Enables the [`read_matrix`](#read_matrixfile_path-string---array) function but pulls in several additional dependencies (`polars`, `url`, `temp-file`, `csv-sniffer`, `minreq`).                                                                                                                                                                                                                                                                                                                                      |
-| `nalgebra` | Enabled  | Enables several functions ([`regress`](#regressx-array-y-array---map), [`inv`](#invmatrix-array---array), [`mtimes`](#mtimesmatrix1-array-matrix2-array---array), [`horzcat`](#horzcatmatrix1-array-matrix2-array---array), [`vertcat`](#vertcatmatrix1-array-matrix2-array---array), [`repmat`](#repmatmatrix-array-nx-i64-ny-i64---array), [`svd`](#svdmatrix-array---map), [`hessenberg`](#hessenbergmatrix-array---map), and [`qr`](#qrmatrix-array---map)) but brings in the `nalgebra` and `linregress` crates. |
-| `rand`     | Enabled  | Enables the [`rand`](#rand) function for generating random FLOAT values and random matrices, but brings in the `rand` crate.                                                                                                                                                                                                                                                                                                                                                                                          |
+at your option.

build.rs

@@ -225,3 +225,8 @@ mod functions {
 
 #[cfg(feature = "metadata")]
 pub use functions::*;
+
+#[cfg(feature = "metadata")]
+pub mod matrix {
+    include!("src/matrix/mod.rs");
+}

examples/matrix_inversion.rhai

@@ -0,0 +1,4 @@
+let m = [[1, 2], [3, 4]];
+let inv_m = inv(m);
+print(inv_m);
+inv_m

examples/matrix_inversion.rs

@@ -0,0 +1,21 @@
+//! Demonstrates computing the inverse of a matrix using rhai-sci.
+
+fn main() {
+    #[cfg(feature = "nalgebra")]
+    {
+        use rhai::{packages::Package, Engine};
+        use rhai_sci::SciPackage;
+
+        // Create a new Rhai engine
+        let mut engine = Engine::new();
+
+        // Add the rhai-sci package to the engine
+        engine.register_global_module(SciPackage::new().as_shared_module());
+
+        // Run the script that inverts a matrix
+        let result = engine
+            .run_file("examples/matrix_inversion.rhai".into())
+            .expect("script should run");
+        println!("{:?}", result);
+    }
+}