NumPy dtype and Memory Layout — float32, int64 and C vs F order

# io.thecodeforge: dtype sizes, memory impact, and production patterns
import numpy as np

# ── DEFAULT BEHAVIOUR ─────────────────────────────────────────────────────────
# Python float literals default to float64 — this is the source of most
# accidental float64 usage in ML pipelines.
a = np.array([1.0, 2.0, 3.0])
print(a.dtype)     # float64
print(a.itemsize)  # 8 bytes per element
print(a.nbytes)    # 24 bytes total

# ── EXPLICIT FLOAT32 ──────────────────────────────────────────────────────────
# One keyword argument halves the memory footprint.
b = np.array([1.0, 2.0, 3.0], dtype=np.float32)
print(b.dtype)     # float32
print(b.itemsize)  # 4 bytes — half the memory for the same values

# ── INTEGER TYPES ─────────────────────────────────────────────────────────────
c = np.array([1, 2, 3], dtype=np.int8)   # 1 byte, range -128 to 127
d = np.array([1, 2, 3], dtype=np.uint8)  # 1 byte, range 0 to 255 — exact fit for pixel data
e = np.array([1, 2, 3], dtype=np.int32)  # 4 bytes — safe for most integer indices

print(np.iinfo(np.int8).max)    # 127
print(np.iinfo(np.uint8).max)   # 255
print(np.iinfo(np.int32).max)   # 2147483647

# ── MEMORY IMPACT AT SCALE ────────────────────────────────────────────────────
# 1000x1000 array — the difference starts to matter here.
large = np.ones((1000, 1000))  # float64 by default
print(f"float64 1000x1000: {large.nbytes / 1e6:.1f} MB")                      # 8.0 MB
print(f"float32 1000x1000: {large.astype(np.float32).nbytes / 1e6:.1f} MB")   # 4.0 MB

# 100M elements — the difference is decisive for GPU workloads.
huge = np.ones(100_000_000)  # 100M elements, float64
print(f"float64 100M:  {huge.nbytes / 1e6:.0f} MB")                           # 800 MB
print(f"float32 100M:  {huge.astype(np.float32).nbytes / 1e6:.0f} MB")        # 400 MB
print(f"float16 100M:  {huge.astype(np.float16).nbytes / 1e6:.0f} MB")        # 200 MB
print(f"uint8   100M:  {huge.astype(np.uint8).nbytes / 1e6:.0f} MB")          # 100 MB

# ── DTYPE RANGE LIMITS ────────────────────────────────────────────────────────
# Always check limits before narrowing — overflow is silent in NumPy.
print(np.finfo(np.float32).max)   # 3.4028235e+38
print(np.finfo(np.float16).max)   # 65504.0 — values above this become inf
print(np.finfo(np.float16).eps)   # 0.000977 — precision limit for float16

# ── PRODUCTION PATTERN: dtype assertion at pipeline boundary ──────────────────
def load_image_batch(paths: list) -> np.ndarray:
    """Always returns float32 — never relies on caller to cast."""
    batch = np.stack([np.array(open(p), dtype=np.float32) / 255.0 for p in paths])
    assert batch.dtype == np.float32, f"dtype regression: expected float32, got {batch.dtype}"
    return batch

# io.thecodeforge: C-order vs Fortran-order — cache performance comparison
import numpy as np
import time

# 5000x5000 float64 array — 200MB, large enough to stress CPU cache
m = np.random.randn(5000, 5000)

# Force the layout explicitly — np.random.randn returns C-order by default
c_arr = np.ascontiguousarray(m)   # C-order: rows are contiguous
f_arr = np.asfortranarray(m)      # F-order: columns are contiguous (creates a copy)

print(f"C-order confirmed: {c_arr.flags['C_CONTIGUOUS']}")   # True
print(f"F-order confirmed: {f_arr.flags['F_CONTIGUOUS']}")   # True
print(f"Array size: {c_arr.nbytes / 1e6:.0f} MB each")

# ── ROW-WISE SUM (axis=1): favours C-order ────────────────────────────────────
# C-order: reads rows contiguously — cache lines are fully utilized
start = time.perf_counter()
for _ in range(20):
    _ = c_arr.sum(axis=1)
print(f"C-order row sum (mean 20 runs): {(time.perf_counter()-start)/20*1000:.1f}ms")

# F-order: row reads jump between column-contiguous blocks — cache thrashing
start = time.perf_counter()
for _ in range(20):
    _ = f_arr.sum(axis=1)
print(f"F-order row sum (mean 20 runs): {(time.perf_counter()-start)/20*1000:.1f}ms")

# ── COLUMN-WISE SUM (axis=0): favours F-order ─────────────────────────────────
# C-order: column reads jump 5000 elements (40KB) per step — L2 cache thrashing
start = time.perf_counter()
for _ in range(20):
    _ = c_arr.sum(axis=0)
print(f"C-order col sum (mean 20 runs): {(time.perf_counter()-start)/20*1000:.1f}ms")

# F-order: reads columns contiguously — cache lines are fully utilized
start = time.perf_counter()
for _ in range(20):
    _ = f_arr.sum(axis=0)
print(f"F-order col sum (mean 20 runs): {(time.perf_counter()-start)/20*1000:.1f}ms")

# ── CHECKING LAYOUT BEFORE CONVERTING ────────────────────────────────────────
# np.asfortranarray() is a no-op if the array is already F-contiguous.
# Always check before converting to avoid an unnecessary 200MB allocation.
if not f_arr.flags['F_CONTIGUOUS']:
    f_arr = np.asfortranarray(f_arr)
    print("Converted to F-order (copy made)")
else:
    print("Already F-contiguous — no copy needed")

# io.thecodeforge: dtype casting — astype vs view vs silent promotion
import numpy as np

# ── astype(): VALUE CONVERSION, ALWAYS CREATES A COPY ─────────────────────────
arr = np.array([1.9, 2.7, 3.1], dtype=np.float64)

ints = arr.astype(np.int32)   # Truncates toward zero: 1.9 → 1, 2.7 → 2, 3.1 → 3
print(ints)          # [1 2 3] — note: truncation, not rounding
print(ints is arr)   # False — always a new array

# Rounding before truncation if you intend nearest-integer:
rounded = np.round(arr).astype(np.int32)
print(rounded)       # [2 3 3] — rounds first, then truncates

# float64 → float32: precision is reduced but values are close
f32 = arr.astype(np.float32)
print(f32)           # [1.9 2.7 3.1] — representable values in float32
print(f32.dtype)     # float32
print(arr.nbytes, f32.nbytes)  # 24, 12 — half the memory

# ── view(): BYTE REINTERPRETATION, ZERO-COPY ──────────────────────────────────
# view() does NOT convert values — it reinterprets the raw bytes.
# float64 is 8 bytes; viewing as uint8 gives 8 bytes per original element.
bytes_view = arr.view(np.uint8)
print(bytes_view.shape)  # (24,) — 3 float64 elements × 8 bytes each = 24 uint8 values
print(bytes_view[:8])    # Raw IEEE 754 bytes of arr[0] — useful for serialization debugging

# Mismatched view: float64 viewed as float32 gives WRONG values
# The bytes are reinterpreted, not converted — results are garbage.
bad_view = arr.view(np.float32)
print(bad_view)       # Garbage values — not [1.9, 2.7, 3.1] as float32
print(bad_view.shape) # (6,) — 3 float64 × 8 bytes / 4 bytes per float32 = 6 elements

# ── SILENT TYPE PROMOTION IN ARITHMETIC ───────────────────────────────────────
# This is the most common source of accidental float64 in ML pipelines.
a = np.array([1, 2, 3], dtype=np.int32)
b = np.array([1.0, 2.0, 3.0], dtype=np.float32)

result = a + b
print(result.dtype)   # float64 — NOT float32! int32 + float32 promotes to float64.
print(result.nbytes)  # 24 bytes (float64) instead of expected 12 bytes (float32)

# Fix: cast explicitly before arithmetic
result_safe = a.astype(np.float32) + b
print(result_safe.dtype)   # float32 — as intended
print(result_safe.nbytes)  # 12 bytes — correct

# ── PRODUCTION PATTERN: dtype gate at every pipeline boundary ─────────────────
def process_batch(images: np.ndarray) -> np.ndarray:
    """
    Defensive dtype checking at the processing boundary.
    Catches dtype regressions introduced upstream before they cause an OOM.
    """
    if images.dtype != np.float32:
        raise TypeError(
            f"process_batch requires float32 input. "
            f"Got {images.dtype} — call .astype(np.float32) before passing."
        )
    # All downstream operations stay in float32 safely
    return images / images.max()

# ── IN-PLACE OPERATIONS TO AVOID INTERMEDIATE ALLOCATIONS ────────────────────
large = np.ones(10_000_000, dtype=np.float32)  # 40MB

# Bad: allocates a new 40MB array, then rebinds the name — peak usage is 80MB
large = large * 2.0

# Good: operates in-place, peak usage stays at 40MB
np.multiply(large, 2.0, out=large)

# Also good for simple scalar ops:
large *= 2.0  # in-place, no new allocation