modelstudio 0.3.0__tar.gz → 0.4.0__tar.gz

{modelstudio-0.3.0/python/modelstudio.egg-info → modelstudio-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: modelstudio
-Version: 0.3.0
+Version: 0.4.0
 Summary: An early-stage AI tensor framework with CPU tensors, autograd, and backend extension scaffolding.
 Author: ModelStudio Contributors
 License-Expression: MIT
@@ -31,7 +31,7 @@ Dynamic: license-file
 
 # ModelStudio
 
-ModelStudio is an early-stage AI tensor framework. Version `0.3.0` provides a
+ModelStudio is an early-stage AI tensor framework. Version `0.4.0` provides a
 CPU tensor/autograd MVP with neural-network modules, optimizers, serialization,
 basic data loading, and small LLM-oriented building blocks.
 
@@ -60,13 +60,15 @@ python -m pip install -e ".[dev]"
 | CPU tensors | Working MVP |
 | Autograd | Reverse-mode for core CPU ops |
 | Reductions | `sum`, `mean`, `max` with axis and keepdims; `max` is value-only |
-| Activations | ReLU, GELU, exp, log, tanh, sigmoid, SiLU, softmax, log-softmax |
+| Activations | ReLU, GELU, LeakyReLU, ELU, Softplus, exp, log, tanh, sigmoid, SiLU, softmax, log-softmax |
 | Losses | MSE and cross entropy with `none`, `mean`, and `sum` reductions |
 | Modules | Parameters, buffers, child traversal, state dicts, save/load |
 | Layers | Linear, Embedding, LayerNorm, RMSNorm, BatchNorm1d, Dropout, Conv1d, Conv2d, pooling, TransformerBlock |
-| Optimizers | SGD and AdamW with state serialization |
-| Data | Dataset, TensorDataset, DataLoader with deterministic seeded shuffle |
+| Optimizers | SGD and AdamW with state serialization, parameter groups, and LR schedulers |
+| Data | Dataset, TensorDataset, random_split, DataLoader with deterministic seeded shuffle |
 | Randomness | `manual_seed`, RNG-backed `randn`, dropout, and init helpers |
+| Interop | `asarray`, `from_numpy`, `to_numpy`, and `ms.numpy` |
+| Metrics | accuracy and top-k accuracy |
 | Compiler | Placeholder IR and passes |
 
 ## Backend Status
@@ -165,7 +167,7 @@ y = block(x)
 print(y.shape)
 ```
 
-## 0.3.0 Training Utilities
+## 0.4.0 Training Utilities
 
 ```python
 ms.manual_seed(123)
@@ -180,6 +182,34 @@ New CPU-only helpers include `ms.concat`, `ms.stack`, `Tensor.flatten`,
 `nn.BatchNorm1d`, `nn.Conv1d`, `nn.Conv2d`, `nn.AvgPool2d`, `nn.MaxPool2d`,
 and `nn.utils` gradient clipping.
 
+## NumPy Interop
+
+```python
+x = ms.asarray([[1, 2, 3], [4, 5, 6]], dtype=ms.float32)
+arr = ms.to_numpy(x)
+y = ms.from_numpy(arr)
+```
+
+CPU uses NumPy internally. Normal examples prefer ModelStudio APIs; `ms.numpy`
+is exposed for advanced users who explicitly want NumPy access.
+
+## Schedulers and Metrics
+
+```python
+optimizer = ms.optim.AdamW(model.parameters(), lr=1e-3)
+scheduler = ms.optim.lr_scheduler.StepLR(optimizer, step_size=1, gamma=0.5)
+scheduler.step()
+
+acc = ms.metrics.accuracy(logits, targets)
+```
+
+## Checkpointing
+
+```python
+ms.save_checkpoint("checkpoint.ms", model=model, optimizer=optimizer, scheduler=scheduler, extra={"epoch": 1})
+checkpoint = ms.load_checkpoint("checkpoint.ms", model=model, optimizer=optimizer, scheduler=scheduler)
+```
+
 ## Commands
 
 ```bash
@@ -192,12 +222,18 @@ python examples/save_load.py
 python examples/train_cnn_toy.py
 python examples/dropout_batchnorm.py
 python examples/checkpoint_training.py
+python examples/numpy_interop.py
+python examples/scheduler_training.py
+python examples/checkpoint_resume.py
+python examples/metrics_demo.py
 python benchmarks/bench_matmul.py
 python benchmarks/bench_mlp.py
 python benchmarks/bench_attention.py
 python benchmarks/bench_dataloader.py
 python benchmarks/bench_conv.py
 python benchmarks/bench_dropout.py
+python benchmarks/bench_creation.py
+python benchmarks/bench_manipulation.py
 ```
 
 ## Documentation
@@ -210,6 +246,12 @@ python benchmarks/bench_dropout.py
 - [Serialization](docs/serialization.md)
 - [Randomness](docs/randomness.md)
 - [Native backend roadmap](docs/native-backend-roadmap.md)
+- [NumPy interop](docs/numpy-interop.md)
+- [Tensor creation](docs/tensor-creation.md)
+- [Tensor manipulation](docs/tensor-manipulation.md)
+- [Optimizers](docs/optimizers.md)
+- [Checkpointing](docs/checkpointing.md)
+- [Metrics](docs/metrics.md)
 - [Backend architecture](docs/backend-architecture.md)
 - [Autograd design](docs/autograd.md)
 - [Releasing](docs/releasing.md)

{modelstudio-0.3.0 → modelstudio-0.4.0}/README.md

@@ -1,6 +1,6 @@
 # ModelStudio
 
-ModelStudio is an early-stage AI tensor framework. Version `0.3.0` provides a
+ModelStudio is an early-stage AI tensor framework. Version `0.4.0` provides a
 CPU tensor/autograd MVP with neural-network modules, optimizers, serialization,
 basic data loading, and small LLM-oriented building blocks.
 
@@ -29,13 +29,15 @@ python -m pip install -e ".[dev]"
 | CPU tensors | Working MVP |
 | Autograd | Reverse-mode for core CPU ops |
 | Reductions | `sum`, `mean`, `max` with axis and keepdims; `max` is value-only |
-| Activations | ReLU, GELU, exp, log, tanh, sigmoid, SiLU, softmax, log-softmax |
+| Activations | ReLU, GELU, LeakyReLU, ELU, Softplus, exp, log, tanh, sigmoid, SiLU, softmax, log-softmax |
 | Losses | MSE and cross entropy with `none`, `mean`, and `sum` reductions |
 | Modules | Parameters, buffers, child traversal, state dicts, save/load |
 | Layers | Linear, Embedding, LayerNorm, RMSNorm, BatchNorm1d, Dropout, Conv1d, Conv2d, pooling, TransformerBlock |
-| Optimizers | SGD and AdamW with state serialization |
-| Data | Dataset, TensorDataset, DataLoader with deterministic seeded shuffle |
+| Optimizers | SGD and AdamW with state serialization, parameter groups, and LR schedulers |
+| Data | Dataset, TensorDataset, random_split, DataLoader with deterministic seeded shuffle |
 | Randomness | `manual_seed`, RNG-backed `randn`, dropout, and init helpers |
+| Interop | `asarray`, `from_numpy`, `to_numpy`, and `ms.numpy` |
+| Metrics | accuracy and top-k accuracy |
 | Compiler | Placeholder IR and passes |
 
 ## Backend Status
@@ -134,7 +136,7 @@ y = block(x)
 print(y.shape)
 ```
 
-## 0.3.0 Training Utilities
+## 0.4.0 Training Utilities
 
 ```python
 ms.manual_seed(123)
@@ -149,6 +151,34 @@ New CPU-only helpers include `ms.concat`, `ms.stack`, `Tensor.flatten`,
 `nn.BatchNorm1d`, `nn.Conv1d`, `nn.Conv2d`, `nn.AvgPool2d`, `nn.MaxPool2d`,
 and `nn.utils` gradient clipping.
 
+## NumPy Interop
+
+```python
+x = ms.asarray([[1, 2, 3], [4, 5, 6]], dtype=ms.float32)
+arr = ms.to_numpy(x)
+y = ms.from_numpy(arr)
+```
+
+CPU uses NumPy internally. Normal examples prefer ModelStudio APIs; `ms.numpy`
+is exposed for advanced users who explicitly want NumPy access.
+
+## Schedulers and Metrics
+
+```python
+optimizer = ms.optim.AdamW(model.parameters(), lr=1e-3)
+scheduler = ms.optim.lr_scheduler.StepLR(optimizer, step_size=1, gamma=0.5)
+scheduler.step()
+
+acc = ms.metrics.accuracy(logits, targets)
+```
+
+## Checkpointing
+
+```python
+ms.save_checkpoint("checkpoint.ms", model=model, optimizer=optimizer, scheduler=scheduler, extra={"epoch": 1})
+checkpoint = ms.load_checkpoint("checkpoint.ms", model=model, optimizer=optimizer, scheduler=scheduler)
+```
+
 ## Commands
 
 ```bash
@@ -161,12 +191,18 @@ python examples/save_load.py
 python examples/train_cnn_toy.py
 python examples/dropout_batchnorm.py
 python examples/checkpoint_training.py
+python examples/numpy_interop.py
+python examples/scheduler_training.py
+python examples/checkpoint_resume.py
+python examples/metrics_demo.py
 python benchmarks/bench_matmul.py
 python benchmarks/bench_mlp.py
 python benchmarks/bench_attention.py
 python benchmarks/bench_dataloader.py
 python benchmarks/bench_conv.py
 python benchmarks/bench_dropout.py
+python benchmarks/bench_creation.py
+python benchmarks/bench_manipulation.py
 ```
 
 ## Documentation
@@ -179,6 +215,12 @@ python benchmarks/bench_dropout.py
 - [Serialization](docs/serialization.md)
 - [Randomness](docs/randomness.md)
 - [Native backend roadmap](docs/native-backend-roadmap.md)
+- [NumPy interop](docs/numpy-interop.md)
+- [Tensor creation](docs/tensor-creation.md)
+- [Tensor manipulation](docs/tensor-manipulation.md)
+- [Optimizers](docs/optimizers.md)
+- [Checkpointing](docs/checkpointing.md)
+- [Metrics](docs/metrics.md)
 - [Backend architecture](docs/backend-architecture.md)
 - [Autograd design](docs/autograd.md)
 - [Releasing](docs/releasing.md)

modelstudio-0.4.0/benchmarks/bench_creation.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+import platform
+import time
+
+import modelstudio as ms
+import numpy as np
+
+
+def timeit(fn, iterations: int, warmup: int) -> float:
+    for _ in range(warmup):
+        fn()
+    start = time.perf_counter()
+    for _ in range(iterations):
+        fn()
+    return (time.perf_counter() - start) / iterations
+
+
+def main() -> None:
+    warmup = 5
+    iterations = 50
+    shape = (512, 512)
+
+    print(f"Python:      {platform.python_version()}")
+    print(f"NumPy:       {np.__version__}")
+    print(f"ModelStudio: {ms.__version__}")
+    print(f"Operation:   rand/full/eye shape={shape}")
+    print(f"Warmup:      {warmup}")
+    print(f"Iterations:  {iterations}")
+    print("Backend:     CPU only")
+    print(f"rand avg:    {timeit(lambda: ms.rand(shape), iterations, warmup) * 1_000:.3f} ms")
+    print(f"full avg:    {timeit(lambda: ms.full(shape, 1.25), iterations, warmup) * 1_000:.3f} ms")
+    print(f"eye avg:     {timeit(lambda: ms.eye(512), iterations, warmup) * 1_000:.3f} ms")
+
+
+if __name__ == "__main__":
+    main()
+

modelstudio-0.4.0/benchmarks/bench_manipulation.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+import platform
+import time
+
+import modelstudio as ms
+import numpy as np
+
+
+def timeit(fn, iterations: int, warmup: int) -> float:
+    for _ in range(warmup):
+        fn()
+    start = time.perf_counter()
+    for _ in range(iterations):
+        fn()
+    return (time.perf_counter() - start) / iterations
+
+
+def main() -> None:
+    warmup = 5
+    iterations = 50
+    x = ms.randn((64, 64, 8))
+
+    print(f"Python:      {platform.python_version()}")
+    print(f"NumPy:       {np.__version__}")
+    print(f"ModelStudio: {ms.__version__}")
+    print("Operation:   permute/repeat/tile")
+    print(f"Warmup:      {warmup}")
+    print(f"Iterations:  {iterations}")
+    print("Backend:     CPU only")
+    print(f"permute avg: {timeit(lambda: ms.permute(x, (2, 0, 1)), iterations, warmup) * 1_000:.3f} ms")
+    print(f"repeat avg:  {timeit(lambda: ms.repeat(x, 2, axis=0), iterations, warmup) * 1_000:.3f} ms")
+    print(f"tile avg:    {timeit(lambda: ms.tile(x, (2, 1, 1)), iterations, warmup) * 1_000:.3f} ms")
+
+
+if __name__ == "__main__":
+    main()
+

modelstudio-0.4.0/docs/checkpointing.md

@@ -0,0 +1,30 @@
+# Checkpointing
+
+High-level checkpoint helpers wrap `ms.save` and `ms.load`.
+
+```python
+ms.save_checkpoint(
+    "checkpoint.ms",
+    model=model,
+    optimizer=optimizer,
+    scheduler=scheduler,
+    extra={"epoch": 3},
+)
+
+checkpoint = ms.load_checkpoint(
+    "checkpoint.ms",
+    model=model,
+    optimizer=optimizer,
+    scheduler=scheduler,
+)
+```
+
+The checkpoint dictionary contains:
+
+- `model`
+- optional `optimizer`
+- optional `scheduler`
+- `extra`
+
+The file format is currently ModelStudio's internal pickle-backed format.
+

{modelstudio-0.3.0 → modelstudio-0.4.0}/docs/data.md

@@ -31,3 +31,12 @@ The current `DataLoader` is intentionally simple:
 - deterministic shuffle when `seed` is provided
 - supports tensors, tuples/lists, and simple Python numeric values
 - batches along axis 0
+
+## random_split
+
+```python
+train_set, valid_set = data.random_split(dataset, [80, 20], seed=123)
+```
+
+Split lengths must sum to the dataset length. When `seed` is supplied, split
+order is deterministic.

modelstudio-0.4.0/docs/metrics.md

@@ -0,0 +1,11 @@
+# Metrics
+
+ModelStudio includes small CPU metrics for training loops.
+
+```python
+acc = ms.metrics.accuracy(logits, targets)
+top5 = ms.metrics.top_k_accuracy(logits, targets, k=5)
+```
+
+Metrics accept Tensor inputs and return Python floats.
+

{modelstudio-0.3.0 → modelstudio-0.4.0}/docs/native-backend-roadmap.md

@@ -1,6 +1,6 @@
 # Native Backend Roadmap
 
-The Python runtime still uses NumPy CPU kernels in 0.3.0. The native C++ tree is
+The Python runtime still uses NumPy CPU kernels in 0.4.0. The native C++ tree is
 scaffolding for future backend work and is intentionally not wired into Python
 dispatch yet.
 
@@ -23,4 +23,3 @@ The intended path is:
 
 CUDA, ROCm, and oneAPI remain unavailable placeholders. Requesting those device
 types raises `ModelStudioBackendUnavailable`.
-

{modelstudio-0.3.0 → modelstudio-0.4.0}/docs/nn.md

@@ -45,6 +45,9 @@ Current CPU layers include:
 - `TransformerBlock`
 - `ReLU`
 - `GELU`
+- `LeakyReLU`
+- `ELU`
+- `Softplus`
 - `MSELoss`
 - `CrossEntropyLoss`
 

modelstudio-0.4.0/docs/numpy-interop.md

@@ -0,0 +1,22 @@
+# NumPy Interop
+
+ModelStudio CPU tensors use NumPy internally, but normal user code does not need
+to import NumPy directly.
+
+```python
+import modelstudio as ms
+
+x = ms.asarray([[1, 2], [3, 4]], dtype=ms.float32)
+arr = ms.to_numpy(x)
+y = ms.from_numpy(arr)
+```
+
+APIs:
+
+- `ms.asarray(obj, dtype=None, device="cpu")`
+- `ms.from_numpy(array, copy=True, requires_grad=False)`
+- `ms.to_numpy(obj)`
+- `ms.numpy` for advanced users who explicitly want NumPy access
+
+`Tensor.numpy()` remains supported and returns a copy.
+

modelstudio-0.4.0/docs/optimizers.md

@@ -0,0 +1,28 @@
+# Optimizers
+
+ModelStudio includes `SGD` and `AdamW`.
+
+Flat parameter lists still work:
+
+```python
+optimizer = ms.optim.AdamW(model.parameters(), lr=1e-3)
+```
+
+Parameter groups are supported:
+
+```python
+optimizer = ms.optim.AdamW([
+    {"params": model.fc1.parameters(), "lr": 1e-3},
+    {"params": model.fc2.parameters(), "lr": 1e-4, "weight_decay": 0.01},
+])
+```
+
+Schedulers live under `ms.optim.lr_scheduler`:
+
+- `StepLR`
+- `ExponentialLR`
+- `CosineAnnealingLR`
+
+Schedulers support `step()`, `get_last_lr()`, `state_dict()`, and
+`load_state_dict()`.
+

{modelstudio-0.3.0 → modelstudio-0.4.0}/docs/tensor-api.md

@@ -38,8 +38,13 @@ y = x.sum(axis=-1, keepdims=True)
 z = x.softmax(axis=-1)
 flat = x.flatten(start_dim=1)
 joined = ms.concat([flat, flat], axis=-1)
+mask = ms.where(ms.ones_like(joined, dtype=ms.bool), joined, ms.zeros_like(joined))
 ```
 
+Creation helpers added in 0.4.0 include `full`, `*_like`, `eye`, `linspace`,
+`rand`, and `randint`. Manipulation helpers include `permute`, `swapaxes`,
+`broadcast_to`, `repeat`, `tile`, and `where`.
+
 Autograd is implemented for the core CPU ops used by the neural-network API.
 `max` is available as a value operation, but its result does not currently track
 gradients.

modelstudio-0.4.0/docs/tensor-creation.md

@@ -0,0 +1,23 @@
+# Tensor Creation
+
+ModelStudio 0.4.0 expands CPU tensor creation utilities:
+
+- `tensor`
+- `empty`, `zeros`, `ones`, `full`
+- `empty_like`, `zeros_like`, `ones_like`, `full_like`
+- `randn`, `rand`, `randint`
+- `arange`, `linspace`, `eye`
+
+Random functions use `ms.manual_seed`.
+
+```python
+import modelstudio as ms
+
+ms.manual_seed(123)
+x = ms.rand((2, 3))
+y = ms.randint(0, 10, shape=(2, 3))
+z = ms.eye(3)
+```
+
+Only floating tensors may require gradients.
+

modelstudio-0.4.0/docs/tensor-manipulation.md

@@ -0,0 +1,25 @@
+# Tensor Manipulation
+
+ModelStudio supports common CPU tensor manipulation with autograd where the
+operation is differentiable:
+
+- `permute`
+- `swapaxes`
+- `broadcast_to`
+- `repeat`
+- `tile`
+- `where`
+- `concat` / `cat`
+- `stack`
+- `flatten`, `squeeze`, `unsqueeze`
+
+```python
+x = ms.randn((2, 3, 4), requires_grad=True)
+y = x.permute((2, 0, 1)).repeat(2, axis=0)
+loss = y.mean()
+loss.backward()
+```
+
+`where` propagates gradients to the selected `x` and `y` values, not to the
+condition.
+

{modelstudio-0.3.0 → modelstudio-0.4.0}/docs/training.md

@@ -1,6 +1,6 @@
 # Training
 
-ModelStudio 0.3.0 supports CPU-only training loops with modules, optimizers,
+ModelStudio 0.4.0 supports CPU-only training loops with modules, optimizers,
 loss functions, DataLoader batching, dropout, BatchNorm1d, and checkpointing.
 
 ```python
@@ -26,4 +26,3 @@ Dropout masks are active only in training mode. BatchNorm1d updates running
 statistics only in training mode and reads those buffers in eval mode.
 
 Loss reductions support `none`, `mean`, and `sum` for MSE and cross entropy.
-

modelstudio-0.4.0/examples/checkpoint_resume.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+import tempfile
+from pathlib import Path
+
+import modelstudio as ms
+from modelstudio import nn, optim
+
+
+def main() -> None:
+    ms.manual_seed(33)
+    model = nn.Linear(3, 2)
+    optimizer = optim.AdamW(model.parameters(), lr=1e-2)
+    scheduler = optim.lr_scheduler.ExponentialLR(optimizer, gamma=0.9)
+    x = ms.randn((8, 3))
+    target = ms.randint(0, 2, shape=(8,))
+
+    loss = ms.cross_entropy(model(x), target)
+    optimizer.zero_grad()
+    loss.backward()
+    optimizer.step()
+    scheduler.step()
+
+    with tempfile.TemporaryDirectory() as tmpdir:
+        path = Path(tmpdir) / "checkpoint.ms"
+        ms.save_checkpoint(path, model=model, optimizer=optimizer, scheduler=scheduler, extra={"epoch": 1})
+        restored = nn.Linear(3, 2)
+        restored_optimizer = optim.AdamW(restored.parameters(), lr=1e-3)
+        restored_scheduler = optim.lr_scheduler.ExponentialLR(restored_optimizer, gamma=0.1)
+        checkpoint = ms.load_checkpoint(
+            path,
+            model=restored,
+            optimizer=restored_optimizer,
+            scheduler=restored_scheduler,
+        )
+
+    print(f"extra={checkpoint['extra']}")
+    print(f"restored_lr={restored_scheduler.get_last_lr()[0]:.6f}")
+
+
+if __name__ == "__main__":
+    main()
+

modelstudio-0.4.0/examples/metrics_demo.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+import modelstudio as ms
+from modelstudio import nn
+
+
+def main() -> None:
+    ms.manual_seed(99)
+    model = nn.Linear(5, 4)
+    x = ms.randn((10, 5))
+    target = ms.randint(0, 4, shape=(10,))
+    logits = model(x)
+
+    print(f"accuracy={ms.metrics.accuracy(logits, target):.3f}")
+    print(f"top2_accuracy={ms.metrics.top_k_accuracy(logits, target, k=2):.3f}")
+
+
+if __name__ == "__main__":
+    main()
+

modelstudio-0.4.0/examples/numpy_interop.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+import modelstudio as ms
+import numpy as np
+
+
+def main() -> None:
+    arr = np.array([[1, 2, 3], [4, 5, 6]], dtype=np.float32)
+    x = ms.from_numpy(arr)
+    y = ms.asarray([[10, 20, 30], [40, 50, 60]], dtype=ms.float32)
+    out = x + y
+
+    print(f"version={ms.__version__}")
+    print(f"tensor_shape={out.shape}")
+    print(f"numpy_sum={ms.to_numpy(out).sum():.1f}")
+    print(f"advanced_namespace_shape={ms.numpy.zeros((2, 2)).shape}")
+
+
+if __name__ == "__main__":
+    main()
+

modelstudio-0.4.0/examples/scheduler_training.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+import modelstudio as ms
+from modelstudio import nn, optim
+
+
+def main() -> None:
+    ms.manual_seed(12)
+    model = nn.Linear(4, 3)
+    optimizer = optim.AdamW(model.parameters(), lr=1e-2)
+    scheduler = optim.lr_scheduler.StepLR(optimizer, step_size=1, gamma=0.5)
+    x = ms.randn((12, 4))
+    target = ms.randint(0, 3, shape=(12,))
+
+    for epoch in range(3):
+        logits = model(x)
+        loss = ms.cross_entropy(logits, target)
+        optimizer.zero_grad()
+        loss.backward()
+        optimizer.step()
+        scheduler.step()
+        print(f"epoch={epoch} loss={loss.item():.6f} lr={scheduler.get_last_lr()[0]:.6f}")
+
+
+if __name__ == "__main__":
+    main()
+

{modelstudio-0.3.0 → modelstudio-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "modelstudio"
-version = "0.3.0"
+version = "0.4.0"
 description = "An early-stage AI tensor framework with CPU tensors, autograd, and backend extension scaffolding."
 readme = "README.md"
 requires-python = ">=3.10"