numpy-demo

A hands-on, progressive tour of NumPy that takes you from "hello, array" all the way to building a small neural network from scratch — with an eye on big data, AI, and machine learning.

Every lesson is a self-contained folder with:

• a short README.md explaining the why and the math,
• one or more heavily commented .py scripts you can just run,
• a checklist of what you should be able to do after finishing it.

No setup magic, no notebooks, no Jupyter required. If you have Python 3.9+ and pip, you can run every example.

---

Why NumPy if I want to do ML?

Almost every machine-learning library you'll touch — PyTorch, TensorFlow, JAX, scikit-learn, pandas — is, at its core, a wrapper around or descendant of NumPy. The mental model NumPy teaches you (think in arrays, not loops; broadcast; vectorize; understand shapes and dtypes) is the exact same mental model you need to read PyTorch code and reason about a GPU kernel. Master NumPy and the rest becomes "the same idea with a .cuda() at the end."

Concretely, after this repo you should be comfortable:

• Manipulating multi-dimensional tensors (shape, stride, dtype, broadcasting).
• Reading vectorized code and writing it yourself instead of for loops.
• Implementing the math behind linear regression, logistic regression, k-means, PCA, and a feed-forward neural net using only NumPy.
• Reasoning about memory and performance well enough to handle bigger-than-RAM data (memmap, chunking).

---

Quick start

# 1. clone
git clone https://github.com/<your-username>/numpy-demo.git
cd numpy-demo

# 2. (optional but recommended) make a virtual environment
python -m venv .venv
# Windows:    .venv\Scripts\activate
# macOS/Linux:  source .venv/bin/activate

# 3. install requirements
pip install -r requirements.txt

# 4. run any lesson
python 01_hello_numpy/hello.py

That's it. No environment variables, no config files, no dataset downloads — every lesson generates its own data.

---

Curriculum

The lessons are designed to be done in order. Each one builds on the last.

Part 1 — Foundations (lessons 01–05)

#	Folder	What you'll learn
01	01_hello_numpy	Your first array; what ndarray actually is
02	02_arrays_and_dtypes	Creating arrays, dtypes, memory layout
03	03_indexing_and_slicing	Basic, advanced, boolean, fancy indexing
04	04_broadcasting	The single most important NumPy concept
05	05_ufuncs_and_math	Universal functions, reductions, axis

Part 2 — Working with real data (lessons 06–10)

#	Folder	What you'll learn
06	06_reshaping_and_stacking	reshape, transpose, concatenate, split
07	07_random_and_simulation	The new Generator API, Monte Carlo
08	08_file_io_and_data	np.save, CSV, JSON-ish data, mini-pandas
09	09_structured_arrays	Records, fields, the bridge to pandas
10	10_performance_and_vectorization	Why loops are slow; benchmarking

Part 3 — The math under ML (lessons 11–15)

#	Folder	What you'll learn
11	11_linear_algebra	Matrices, dot products, solving Ax=b
12	12_eigen_and_svd	Eigendecomposition, SVD, low-rank approx
13	13_statistics_and_probability	Mean, var, covariance, correlations
14	14_fft_and_signals	FFT for signals & 1D convolution
15	15_big_data_tactics	memmap, chunked processing, dtypes for memory

Part 4 — Machine learning from scratch (lessons 16–20)

#	Folder	What you'll learn
16	16_gradient_descent	Vanilla, SGD, mini-batch, momentum
17	17_linear_and_logistic_regression	Closed form + gradient descent
18	18_kmeans_clustering	Vectorized k-means, elbow method
19	19_pca_dimensionality_reduction	PCA via SVD, image compression demo
20	20_neural_network_from_scratch	A 2-layer net trained on a toy MNIST-ish dataset

---

How to read this repo

For each lesson:

1. Open the folder's README.md — it sets up the idea and the math.
2. Run the script(s) with python <lesson>/<file>.py.
3. Read the comments in the code. They're the lesson; the script's output is just confirmation.
4. Try the "Exercises" section at the bottom of each README. Modify the code and see what changes.

---

Requirements

• Python 3.9+
• numpy (>= 1.24 — works fine with 2.x as well)
• matplotlib (only used in a few lessons, all optional — code degrades gracefully if missing)

See requirements.txt.

---

License

MIT — do whatever you want with it. Educational material wants to be free.