numz 0.1.0 → 0.3.0

package/docs/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "docs",
+  "type": "module",
+  "version": "0.0.1",
+  "scripts": {
+    "dev": "astro dev",
+    "start": "astro dev",
+    "build": "astro build",
+    "preview": "astro preview",
+    "astro": "astro"
+  },
+  "dependencies": {
+    "@astrojs/starlight": "^0.37.1",
+    "astro": "^5.6.1",
+    "sharp": "^0.34.2",
+    "starlight-github-alerts": "^0.1.1",
+    "starlight-theme-obsidian": "^0.4.1"
+  }
+}

package/docs/public/favicon.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 128 128"><path fill-rule="evenodd" d="M81 36 64 0 47 36l-1 2-9-10a6 6 0 0 0-9 9l10 10h-2L0 64l36 17h2L28 91a6 6 0 1 0 9 9l9-10 1 2 17 36 17-36v-2l9 10a6 6 0 1 0 9-9l-9-9 2-1 36-17-36-17-2-1 9-9a6 6 0 1 0-9-9l-9 10v-2Zm-17 2-2 5c-4 8-11 15-19 19l-5 2 5 2c8 4 15 11 19 19l2 5 2-5c4-8 11-15 19-19l5-2-5-2c-8-4-15-11-19-19l-2-5Z" clip-rule="evenodd"/><path d="M118 19a6 6 0 0 0-9-9l-3 3a6 6 0 1 0 9 9l3-3Zm-96 4c-2 2-6 2-9 0l-3-3a6 6 0 1 1 9-9l3 3c3 2 3 6 0 9Zm0 82c-2-2-6-2-9 0l-3 3a6 6 0 1 0 9 9l3-3c3-2 3-6 0-9Zm96 4a6 6 0 0 1-9 9l-3-3a6 6 0 1 1 9-9l3 3Z"/><style>path{fill:#000}@media (prefers-color-scheme:dark){path{fill:#fff}}</style></svg>

package/docs/src/content/docs/about.md

@@ -0,0 +1,11 @@
+---
+title: about
+description: about
+# sidebar:
+#     order : 0
+tableOfContents: false
+---
+
+Hello world;
+
+My name is Zakaria ELALAOUI, There’s nothing impressive here, just skip this part and go straight to the documentation.

package/docs/src/content/docs/guides/example.md

@@ -0,0 +1,11 @@
+---
+title: Example Guide
+description: A guide in my new Starlight docs site.
+---
+
+Guides lead a user through a specific task they want to accomplish, often with a sequence of steps.
+Writing a good guide requires thinking about what your users are trying to do.
+
+## Further reading
+
+- Read [about how-to guides](https://diataxis.fr/how-to-guides/) in the Diátaxis framework

package/docs/src/content/docs/index.mdx

@@ -0,0 +1,40 @@
+---
+title: Welcome to Numz
+description: Get started building your docs site with Starlight.
+template: splash # Remove or comment out this line to display the site sidebar on this page.
+hero:
+  tagline: Scientific computation with zikojs
+  image:
+    file: ../../assets/houston.webp
+  actions:
+    - text: Example Guide
+      link: /guides/example/
+      icon: right-arrow
+    - text: Read Zikojs docs
+      link: https://github.com/zakarialaoui10/zikojs
+      icon: external
+      variant: minimal
+---
+
+import { Card, CardGrid } from '@astrojs/starlight/components';
+
+## Next steps
+
+<CardGrid stagger>
+	<Card title="Update content" icon="pencil">
+		Edit `src/content/docs/index.mdx` to see this page change.
+	</Card>
+	<Card title="Change page layout" icon="document">
+		Delete `template: splash` in `src/content/docs/index.mdx` to display a
+		sidebar on this page.
+	</Card>
+	<Card title="Add new content" icon="add-document">
+		Add Markdown or MDX files to `src/content/docs` to create new pages.
+	</Card>
+	<Card title="Configure your site" icon="setting">
+		Edit your `sidebar` and other config in `astro.config.mjs`.
+	</Card>
+	<Card title="Read the docs" icon="open-book">
+		Learn more in [the Starlight Docs](https://starlight.astro.build/).
+	</Card>
+</CardGrid>

package/docs/src/content/docs/philosophy.md

@@ -0,0 +1,15 @@
+---
+title: philosophy
+description: The philosphy of numz
+---
+
+Numz adopts the [**Extended array programming paradigm**](), as it is built on top of the [**ZikoJS Math module**]().
+
+It is inspired by:
+- **NumPy**
+- **SciPy**
+- **MATLAB**
+
+Numz guarantees a **layered, shape-safe, function-first numerical computing model**, designed to scale naturally from scalars to tensors while preserving mathematical correctness and clarity.
+
+<!-- Numz is a layered, shape-safe, function-first numerical computing library that brings true array programming and scientific mathematics to JavaScript, built on the top of [Zikojs](). -->

package/docs/src/content/docs/reference/complex/complex.mdx

@@ -0,0 +1,66 @@
+---
+title: Complex
+description: complex
+sidebar:
+    label : complex
+---
+import { Tabs, TabItem } from '@astrojs/starlight/components';
+
+## Declarations
+
+### Complex Constructor
+
+<Tabs>
+  <TabItem label="Class Constructor">
+    - `new Complex(c : Complex)`
+    - `new Complex(a : number, b : number)`
+    - `new Complex({z : number, phi : number})`
+    - `new Complex({a : number, z : number})`
+    - `new Complex({a : number, phi : number})`
+    - `new Complex({b : number, z : number})`
+    - `new Complex({b : number, phi : number})`
+  </TabItem>
+  <TabItem label="Functional Constructors">
+    - `complex(c : Complex)`
+    - `complex(a : number, b : number)`
+    - `complex({z : number, phi : number})`
+    - `complex({a : number, z : number})`
+    - `complex({a : number, phi : number})`
+    - `complex({b : number, z : number})`
+    - `complex({b : number, phi : number})`
+  </TabItem>
+</Tabs>
+
+### Static Factory Methods
+
+- `Complex.Zero()` : 
+- `Complex.fromPloar(z, phi)` :
+- `Complex.Twiddle(N, K)` : 
+- `Complex.Random.int(min, max)` : 
+- `Complex.Random.float(min, max)` : 
+
+## Getters
+
+|Getter|Description|Type|
+|-|-|-|
+|`.z`|||
+|`.phi`|||
+|`.conj`|||
+|`.inv`|||
+|`.expo`|||
+|`.sqrt`|||
+|`.cbrt`|||
+|`.log`|||
+|`.cos`|||
+|`.sin`|||
+|`.tan`|||
+
+## Arithmetic
+
+- `.add(...c : (Complex | number)[])` : 
+- `.sub(...c : (Complex | number)[])` : 
+- `.mul(...c : (Complex | number)[])` : 
+- `.div(...c : (Complex | number)[])` : 
+- `.modul(...c : (Complex | number)[])` : 
+- `.pow(...c : (Complex | number)[])` : 
+- `.nthr(n : number)` : 

package/docs/src/content/docs/reference/functions/arithmetic.md

@@ -0,0 +1,14 @@
+---
+title: Arithemtic helpers
+description: arithemtic
+sidebar:
+    order : 1
+    label : arithemtic
+---
+
+
+- `add(...x)` :
+- `sub(...x)` :
+- `mul(...x)` :
+- `div(...x)` : 
+- `modulo(...x)` :

package/docs/src/content/docs/reference/functions/mapfun.md

@@ -0,0 +1,81 @@
+---
+title: Mapfun - The core of Extended Array Programming 
+description: mapfun
+sidebar:
+    order : 0
+    label : mapfun
+---
+
+## Introduction
+
+**Mapfun** is the heart of Numz’s extended array programming.  
+It allows applying functions recursively to deeply nested structures — arrays, objects, or mixed types — preserving their shape and type, without manual loops or recursion.
+
+
+## Javascript Limitation :
+
+While JavaScript offers a built-in `Math` module, it has limitations in flexibility and handling complex data structures:
+
+```js
+Math.sqrt(4)        // 2
+Math.sqrt(4, 9)     // 2  (ignores extra arguments)
+Math.sqrt([4, 9, 16]) // NaN
+```
+- Cannot handle multiple arguments simultaneously.
+- Cannot map functions over arrays or objects automatically
+- Lacks support for deeply nested or heterogeneous structures.
+
+## Existing Solutions in Other Languages and Libraries
+
+Array programming libraries in other languages partially solve this problem:
+
+- **NumPy (Python):** Provides efficient vectorized operations on arrays, but primarily works with homogeneous arrays. Nested lists require manual handling.
+
+- **MATLAB:** Supports matrix and array operations natively, excellent for linear algebra and numeric computing, but struggles with nested or mixed-type structures.
+
+- **R Lang:** Vectorized operations are supported and convenient for statistical computing, but deeply nested lists or heterogeneous objects require custom iteration.
+
+Even these solutions do not fully support deeply nested or heterogeneous structures in a clean, recursive, type-preserving way.
+
+## Solution : 
+[Zikojs]() which is the core of Numz introduces mapfun, a functional, type-preserving mapper.
+It enables you to apply any function over numbers, arrays, objects, and nested combinations thereof without side effects.
+
+### Features 
+- Recursive Processing, Enabling transformations on deeply nested data structures.
+- No need for explicit recursions or loops, eliminating the need for manual recursion or loops.
+- Preserves Data Type Format.
+- Supports Heterogeneous Structures, working with diverse, mixed data types.
+- No Side Effect, adopting a functional approach to ensure immutability and avoid unintended
+changes.
+- works with any unary function, including user-defined functions.
+- Ideal for scientific computing where operations must be applied across complex, structured datasets.
+
+
+### Example 
+
+```js
+import { mapfun } from "ziko/math/functions/mapfun";
+// or import { mapfun } from "numz/functions/mapfun"  
+const sqrt = (...x) => mapfun(Math.sqrt, ...x)
+const result = sqrt(1, 4, 9, [16, 25], {
+  x: 36,
+  y: 49,
+  z: [64, 81],
+}
+);
+/*
+result =>
+[
+  1,
+  2,
+  3,
+  [4, 5],
+  {
+    x: 6,
+    y: 7,
+    z: [8, 9],
+  },
+];
+*/
+```

package/docs/src/content/docs/reference/functions/ufunc.md

@@ -0,0 +1,41 @@
+---
+title: Universal functions
+description: ufunc
+sidebar:
+    order : 2
+    label : ufunc
+---
+
+- `abs(...x)` : 
+- `pow(...x)` : 
+- `sqrt(...x)` : 
+- `cbrt(...x)` : 
+- `nthr(...x)` : 
+- `croor(...x)` : 
+
+- `exp(...x)` : 
+-  `ln(...x)` : 
+
+-  `sign(...x)` : 
+-  `floor(...x)` : 
+-  `ceil(...x)` : 
+-  `round(...x)` : 
+-  `trunc(...x)` : 
+-  `fract(...x)` :
+
+-  `cos(...x)` : 
+-  `sin(...x)` : 
+-  `tan(...x)` : 
+-  `sec(...x)` : 
+-  `acos(...x)` : 
+-  `asin(...x)` : 
+-  `atan(...x)` : 
+-  `acot(...x)` : 
+-  `cosh(...x)` : 
+-  `sinh(...x)` : 
+-  `tanh(...x)` : 
+-  `coth(...x)` : 
+-  `acosh(...x)` : 
+-  `asinh(...x)` : 
+-  `atanh(...x)` : 
+-  `sig(...x)` : 

package/docs/src/content/docs/reference/functions/utils.md

@@ -0,0 +1,16 @@
+---
+title: Utils
+description: utils
+sidebar:
+    order : 1
+    label : utils
+---
+
+
+- `deg2rad(...deg)` :
+- `rad2deg(...rad)` :
+- `norm(x, min, max)` :
+- `lerp(x, min, max)` : 
+- `clamp(x, min, max)` :
+- `hypot(...x)` :
+- `atan2(y, x, rad? : boolean)` : 

package/docs/src/content/docs/reference/matrix/matrix.mdx

@@ -0,0 +1,97 @@
+---
+title: Matrix
+description: matrix
+sidebar:
+    label : matrix
+---
+
+import { Tabs, TabItem } from '@astrojs/starlight/components';
+
+## Declarations
+
+### Matrix Constructor
+
+<Tabs>
+  <TabItem label="Class Constructor">
+    - `new Matrix(r, c, arr: (number|Complex)[])` : 
+    - `new Matrix(m : Matrix)` : 
+    - `new Matrix(arr : (number|Complex)[])` : 
+  </TabItem>
+  <TabItem label="Functional Constructors">
+    - `matrix()`
+    - `matrix2(a0, a1, b0, b1)` : Creates a **2×2** matrix
+    - `matrix3(a0, a1, a2, b0, b1, b2, c0, c1, c2)` : Creates a **3×3** matrix
+    - `matrix4(a0, a1, a2, a3, b0, b1, b2, b3, c0, c1, c2, c3, d0, d1, d2, d3)` : Creates a **4×4** matrix
+  </TabItem>
+</Tabs>
+
+### Static Factory Methods
+- `Matrix.zeros(r, c)` : Creates an `r × c` matrix filled with zeros.
+- `Matrix.ones(r, c)` : Creates an `r × c` matrix filled with ones.
+- `Matrix.eye(r, c)` : Creates an `r × c` identity matrix (ones on the diagonal, zeros elsewhere).  
+  If `r !== c`, creates a rectangular diagonal matrix.
+- `Matrix.nums(num : number|complex, r, c)` : Creates an r × c matrix filled with the specified value num, which can be a real or complex number.
+- `Matrix.random.int(min, max)`
+- `Matrix.random.float(min, max)`
+
+## Indexing
+
+- `.at(r, c)` : Returns the element at row `r` and column `c`
+- `[Symbol.iterator]` : 
+
+## Reshape
+
+- `.reshape(r, c)` : Reshapes the matrix to `(r × c)` without changing the total number of elements.
+- `.reshape(r0, c0, r1, c1)` : 
+- `.hstack(...matrices: Matrix[])` : Horizontally stacks matrices by columns (same number of rows required).
+- `.vstack(...matrices: Matrix[])` : Vertically stacks matrices by rows (same number of columns required).
+- `.hqueue(...matrices: Matrix[])` : Appends matrices horizontally, preserving row order (row-wise concatenation).
+- `.vqueue(...matrices: Matrix[])` : Appends matrices vertically, preserving column order (column-wise concatenation).
+
+
+## Arithmetic
+
+- `.add(...m: (Matrix | number)[])` : Element-wise addition with one or more matrices or scalars.
+- `.sub(...m: (Matrix | number)[])` : Element-wise subtraction with one or more matrices or scalars.
+- `.mul(...m: (Matrix | number)[])` : Element-wise multiplication with one or more matrices or scalars.
+- `.div(...m: (Matrix | number)[])` : Element-wise division with one or more matrices or scalars.
+- `.modulo(...m: (Matrix | number)[])` : Element-wise modulo operation with one or more matrices or scalars.
+- `.dot(m: Matrix)` : Matrix multiplication (linear algebra dot product).
+
+## Modifiers
+
+- `.toPrecision(n)`
+- `.toComplex(n)` : Casts a real-valued matrix to a complex-valued matrix with `0` imaginary components
+- `.map(Imin, Imax, Fmin, Fmax)` : Linearly maps matrix values from the input range `[Imin, Imax]` to the output range `[Fmin, Fmax]`.
+- `.lerp(min, max)` : Applies linear interpolation to scale matrix values into the range `[min, max]`.
+- `.norm(min, max)` : Normalizes matrix values to the range `[min, max]`.
+- `.clamp(min, max)` : Clamps matrix values so that all elements lie within the range `[min, max]`.
+- `.shuffle()` : Randomly shuffles the elements of the matrix (element-wise), preserving its shape.
+- `.shuffleRows()` : Randomly shuffles the **rows** of the matrix, keeping the order of elements within each row intact.
+- `.shuffleCols()` : Randomly shuffles the **columns** of the matrix, keeping the order of elements within each column intact.
+
+## Getters
+
+| Getter | Description | Type |
+|-------|-------------|------|
+| `.size` | Returns the total number of elements in the matrix (`rows × cols`). | `number` |
+| `.shape` | Returns the shape of the matrix as `[rows, cols]`. | `[number, number]` |
+| `.det` | Returns the determinant of the matrix (only for square matrices). | `number \| Matrix` |
+| `.inv` | Returns the inverse of the matrix (only if invertible). | `Matrix` |
+| `.T` | Returns the transpose of the matrix. | `Matrix` |
+
+
+## Checkers
+
+|Checker|Description|
+|-|-|
+| `.isMatrix()` |  |
+| `.haComplex()` |  |
+| `.isSquare()` | Checks whether the matrix has the same number of rows and columns. |
+| `.isSym()` | Checks whether the matrix is symmetric (`A = Aᵀ`). |
+| `.isAntiSym()` | Checks whether the matrix is antisymmetric (`A = -Aᵀ`). |
+| `.isDiag()` | Checks whether the matrix is diagonal (non-zero elements only on the main diagonal). |
+| `.isOrtho()` | Checks whether the matrix is orthogonal (`A · Aᵀ = I`). |
+| `.isIdemp()` | Checks whether the matrix is idempotent (`A² = A`). |
+| `.isUpperTri()` | Checks whether the matrix is upper triangular (zeros below the main diagonal). |
+| `.isLowerTri()` | Checks whether the matrix is lower triangular (zeros above the main diagonal). |

package/docs/src/content/docs/reference/signal/functions/periodic/pulse-train.md

@@ -0,0 +1,6 @@
+---
+title: pulse_train
+description: pulse_train
+sidebar : 
+    order: 10
+---

package/docs/src/content/docs/reference/signal/functions/periodic/pwm.md

@@ -0,0 +1,6 @@
+---
+title: pwm
+description: pwm
+sidebar : 
+    order: 10
+---

package/docs/src/content/docs/reference/signal/functions/periodic/sawtooth-train.md

@@ -0,0 +1,6 @@
+---
+title: swatooth_train
+description: swatooth train
+sidebar : 
+    order: 10
+---

package/docs/src/content/docs/reference/signal/functions/periodic/sinusoid.md

@@ -0,0 +1,6 @@
+---
+title: sinusoid
+description: sinusoid
+sidebar : 
+    order: 10
+---

package/docs/src/content/docs/reference/signal/functions/periodic/square.md

@@ -0,0 +1,6 @@
+---
+title: square
+description: square
+sidebar : 
+    order: 10
+---

package/docs/src/content/docs/reference/signal/functions/periodic/triangle.md

@@ -0,0 +1,6 @@
+---
+title: triangle
+description: triangle
+# sidebar : 
+#     order: 1
+---

package/docs/src/content/docs/reference/signal/functions/pulse/dirac.md

@@ -0,0 +1,12 @@
+---
+title: dirac
+description: dirac
+sidebar : 
+    order: 10
+---
+
+## Definition
+
+## Signature
+
+## Usage

package/docs/src/content/docs/reference/signal/functions/pulse/noise.md

@@ -0,0 +1,12 @@
+---
+title: noise
+description: noise
+sidebar : 
+    order: 10
+---
+
+## Definition
+
+## Signature
+
+## Usage

package/docs/src/content/docs/reference/signal/functions/pulse/rampe.md

@@ -0,0 +1,12 @@
+---
+title: rampe
+description: rampe
+sidebar : 
+    order: 10
+---
+
+## Definition
+
+## Signature
+
+## Usage

package/docs/src/content/docs/reference/signal/functions/pulse/rect.md

@@ -0,0 +1,12 @@
+---
+title: rect
+description: rect
+sidebar : 
+    order: 10
+---
+
+## Definition
+
+## Signature
+
+## Usage

package/docs/src/content/docs/reference/signal/functions/pulse/signum.md

@@ -0,0 +1,12 @@
+---
+title: signum
+description: signum
+sidebar : 
+    order: 10
+---
+
+## Definition
+
+## Signature
+
+## Usage

package/docs/src/content/docs/reference/signal/functions/pulse/sinc.md

@@ -0,0 +1,12 @@
+---
+title: sinc
+description: sinc
+sidebar : 
+    order: 10
+---
+
+## Definition
+
+## Signature
+
+## Usage

package/docs/src/content/docs/reference/signal/functions/pulse/trapezoid.md

@@ -0,0 +1,12 @@
+---
+title: trapezoid
+description: trapezoid
+sidebar : 
+    order: 10
+---
+
+## Definition
+
+## Signature
+
+## Usage

package/docs/src/content/docs/reference/signal/functions/pulse/tri.md

@@ -0,0 +1,12 @@
+---
+title: tri
+description: tri
+sidebar : 
+    order: 10
+---
+
+## Definition
+
+## Signature
+
+## Usage

package/docs/src/content/docs/reference/signal/functions/sequences/arange.md

@@ -0,0 +1,21 @@
+---
+title: arange
+description: arange
+sidebar : 
+    order: 3
+---
+## Definition 
+
+## Signature
+
+```ts
+arange(
+        a : number | number[], 
+        b : number | number[], 
+        step : number , 
+        include? : boolean
+    ): number[]
+```
+
+## Usage
+

package/docs/src/content/docs/reference/signal/functions/sequences/geomspace.md

@@ -0,0 +1,21 @@
+---
+title: geomspace
+description: geomspace
+sidebar : 
+    order: 5
+---
+
+## Definition 
+
+## Signature
+```ts
+geomspace(
+    a: number | Complex | (number | Complex)[],
+    b: number | Complex | (number | Complex)[],
+    n: number,
+    endpoint?: boolean,
+    precesion?: number
+): number[] | Complex[]
+```
+
+## Usage

package/docs/src/content/docs/reference/signal/functions/sequences/linspace.md

@@ -0,0 +1,16 @@
+---
+title: linspace
+description: linspace
+sidebar : 
+    order: 4
+---
+
+```ts
+linspace(
+    a: number | Complex | (number | Complex)[],
+    b: number | Complex | (number | Complex)[],
+    n: number,
+    endpoint?: boolean
+): number[] | Complex[]
+
+```

package/docs/src/content/docs/reference/signal/functions/sequences/logspace.md

@@ -0,0 +1,20 @@
+---
+title: logspace
+description: logspace
+sidebar : 
+    order: 5
+---
+
+## Definition 
+
+## Signature
+```ts
+logspace(
+    a: number | Complex | (number | Complex)[],
+    b: number | Complex | (number | Complex)[],
+    n: number,
+    endpoint?: boolean,
+): number[] | Complex[]
+```
+
+## Usage