mainboard 0.0.1__py3-none-any.whl

mainboard/__init__.py

@@ -0,0 +1,113 @@
+from __future__ import annotations
+
+from .enums import (
+    CmakeBuildType,
+    CompilerKind,
+    CudaPythonVariant,
+    DiskKind,
+    Scheduler,
+    SystemFamily,
+    UnitKind,
+    Vendor,
+)
+from .gpu import GPU
+from .host import Host
+from .machine import Machine
+from .models import (
+    Board,
+    Clock,
+    ClockInfo,
+    CompilerInfo,
+    ComputeCapability,
+    CpuSnapshot,
+    CudaPythonInfo,
+    DriveInfo,
+    EnergyInterval,
+    EnergyReading,
+    Environment,
+    GPUSnapshot,
+    HostDisk,
+    HostMemory,
+    MachineSnapshot,
+    MemInfo,
+    MemoryCard,
+    MemoryUsage,
+    PartitionInfo,
+    PcieInfo,
+    ProcessInfo,
+    SystemCompilers,
+    ThermalState,
+    ThermalTracker,
+    ThrottleReason,
+    UnitSnapshot,
+    Utilization,
+)
+from .npu import NPU
+from .providers import (
+    AMDGPU,
+    AppleGPU,
+    AppleNPU,
+    IntelGPU,
+    IntelNPU,
+    NvidiaGPU,
+    QualcommGPU,
+    QualcommNPU,
+)
+from .unit import CPU, Unit
+from .visual import MachineView
+
+NAME = __name__  # the package folder is the single source of the name
+
+__all__ = [
+    "NAME",
+    "CPU",
+    "GPU",
+    "NPU",
+    "AMDGPU",
+    "AppleGPU",
+    "AppleNPU",
+    "Board",
+    "Clock",
+    "ClockInfo",
+    "CmakeBuildType",
+    "CompilerInfo",
+    "CompilerKind",
+    "ComputeCapability",
+    "CpuSnapshot",
+    "CudaPythonInfo",
+    "CudaPythonVariant",
+    "DiskKind",
+    "DriveInfo",
+    "EnergyInterval",
+    "EnergyReading",
+    "Environment",
+    "GPUSnapshot",
+    "Host",
+    "HostDisk",
+    "HostMemory",
+    "IntelGPU",
+    "IntelNPU",
+    "Machine",
+    "MachineSnapshot",
+    "MachineView",
+    "MemInfo",
+    "MemoryCard",
+    "MemoryUsage",
+    "NvidiaGPU",
+    "PartitionInfo",
+    "PcieInfo",
+    "ProcessInfo",
+    "QualcommGPU",
+    "QualcommNPU",
+    "Scheduler",
+    "SystemCompilers",
+    "SystemFamily",
+    "ThermalState",
+    "ThermalTracker",
+    "ThrottleReason",
+    "Unit",
+    "UnitKind",
+    "UnitSnapshot",
+    "Utilization",
+    "Vendor",
+]

mainboard/__main__.py

@@ -0,0 +1,2 @@
+if __name__ == "__main__":
+    __import__(f"{__package__}.cli", fromlist=["main"]).main()

mainboard/assets/banner.svg

@@ -0,0 +1,54 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1280" height="420" viewBox="0 0 1280 420" role="img" aria-labelledby="title desc">
+  <title id="title">Maquina</title>
+  <desc id="desc">CPU, GPU, and NPU hardware topology for Python.</desc>
+  <defs>
+    <linearGradient id="bg" x1="0" x2="1" y1="0" y2="1">
+      <stop offset="0" stop-color="#020617"/>
+      <stop offset="0.46" stop-color="#0f172a"/>
+      <stop offset="1" stop-color="#1e3a8a"/>
+    </linearGradient>
+    <linearGradient id="unit" x1="0" x2="1" y1="0" y2="1">
+      <stop offset="0" stop-color="#38bdf8"/>
+      <stop offset="1" stop-color="#2563eb"/>
+    </linearGradient>
+    <filter id="glow" x="-50%" y="-50%" width="200%" height="200%">
+      <feGaussianBlur stdDeviation="10" result="blur"/>
+      <feMerge>
+        <feMergeNode in="blur"/>
+        <feMergeNode in="SourceGraphic"/>
+      </feMerge>
+    </filter>
+  </defs>
+
+  <rect width="1280" height="420" rx="42" fill="url(#bg)"/>
+  <circle cx="1030" cy="70" r="210" fill="#2563eb" opacity="0.18"/>
+  <circle cx="230" cy="380" r="260" fill="#38bdf8" opacity="0.10"/>
+  <path d="M0 310 C170 245 270 370 430 310 C610 242 725 160 920 220 C1070 268 1120 160 1280 185 L1280 420 L0 420 Z" fill="#0ea5e9" opacity="0.08"/>
+
+  <g transform="translate(760 92)" filter="url(#glow)">
+    <rect x="0" y="0" width="360" height="220" rx="28" fill="#020617" stroke="#38bdf8" stroke-opacity="0.42" stroke-width="2"/>
+    <rect x="38" y="44" width="82" height="58" rx="16" fill="url(#unit)"/>
+    <rect x="139" y="44" width="82" height="58" rx="16" fill="url(#unit)" opacity="0.82"/>
+    <rect x="240" y="44" width="82" height="58" rx="16" fill="url(#unit)" opacity="0.66"/>
+    <rect x="38" y="128" width="284" height="34" rx="17" fill="#0f172a" stroke="#60a5fa" stroke-opacity="0.32"/>
+    <path d="M72 198 H288" stroke="#38bdf8" stroke-width="8" stroke-linecap="round" opacity="0.55"/>
+    <path d="M106 18 V-18 M180 18 V-18 M254 18 V-18 M106 238 V202 M180 238 V202 M254 238 V202" stroke="#38bdf8" stroke-width="8" stroke-linecap="round" opacity="0.34"/>
+    <text x="79" y="81" text-anchor="middle" font-family="Inter, ui-sans-serif, system-ui, sans-serif" font-size="22" font-weight="800" fill="#e0f2fe">CPU</text>
+    <text x="180" y="81" text-anchor="middle" font-family="Inter, ui-sans-serif, system-ui, sans-serif" font-size="22" font-weight="800" fill="#e0f2fe">GPU</text>
+    <text x="281" y="81" text-anchor="middle" font-family="Inter, ui-sans-serif, system-ui, sans-serif" font-size="22" font-weight="800" fill="#e0f2fe">NPU</text>
+  </g>
+
+  <g transform="translate(96 92)">
+    <text x="0" y="0" font-family="Inter, ui-sans-serif, system-ui, sans-serif" font-size="86" font-weight="900" fill="#f8fafc" letter-spacing="-3">Maquina</text>
+    <text x="3" y="58" font-family="Inter, ui-sans-serif, system-ui, sans-serif" font-size="28" font-weight="600" fill="#bfdbfe">Hardware topology for heterogeneous Python systems.</text>
+    <text x="3" y="112" font-family="JetBrains Mono, ui-monospace, SFMono-Regular, Menlo, monospace" font-size="22" fill="#93c5fd">from maquina import Machine</text>
+    <g transform="translate(3 154)">
+      <rect x="0" y="0" width="88" height="38" rx="19" fill="#0f172a" stroke="#60a5fa" stroke-opacity="0.35"/>
+      <rect x="104" y="0" width="88" height="38" rx="19" fill="#0f172a" stroke="#60a5fa" stroke-opacity="0.35"/>
+      <rect x="208" y="0" width="88" height="38" rx="19" fill="#0f172a" stroke="#60a5fa" stroke-opacity="0.35"/>
+      <text x="44" y="25" text-anchor="middle" font-family="Inter, ui-sans-serif, system-ui, sans-serif" font-size="16" font-weight="800" fill="#dbeafe">CPU</text>
+      <text x="148" y="25" text-anchor="middle" font-family="Inter, ui-sans-serif, system-ui, sans-serif" font-size="16" font-weight="800" fill="#dbeafe">GPU</text>
+      <text x="252" y="25" text-anchor="middle" font-family="Inter, ui-sans-serif, system-ui, sans-serif" font-size="16" font-weight="800" fill="#dbeafe">NPU</text>
+    </g>
+  </g>
+</svg>

mainboard/cli.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from cyclopts import App
+
+from . import NAME
+from .machine import Machine
+from .visual import MachineView
+
+app = App(name=NAME, help="Inspect CPU, GPU, and NPU hardware topology.")
+
+
+@app.default
+def show(color: bool = True) -> None:
+    """Render a Rich terminal view of the current machine."""
+    MachineView(Machine()).print(color=color)
+
+
+def main() -> None:
+    """Run the Mainboard command-line interface."""
+    app()
+
+
+if __name__ == "__main__":
+    main()

mainboard/enums.py

@@ -0,0 +1,78 @@
+from __future__ import annotations
+
+from enum import StrEnum
+
+
+class CompilerKind(StrEnum):
+    """Normalized host compiler kind."""
+
+    CLANG_GRACE = "clang-grace"
+    GCC = "gcc"
+    CLANG = "clang"
+    NVCC = "nvcc"
+    UNKNOWN = "unknown"
+
+
+class SystemFamily(StrEnum):
+    """Machine-family grouping used to guide build choices."""
+
+    GRACE_HOPPER = "grace-hopper"
+    GRACE_BLACKWELL = "grace-blackwell"
+    HOPPER = "hopper"
+    BLACKWELL = "blackwell"
+    GENERIC = "generic"
+
+
+class CudaPythonVariant(StrEnum):
+    """CUDA Python stack family required on the current system."""
+
+    CU12 = "cu12"
+    CU13 = "cu13"
+
+
+class CmakeBuildType(StrEnum):
+    """CMake build type string."""
+
+    RELEASE = "Release"
+
+
+class DiskKind(StrEnum):
+    """Drive technology for a mounted disk or partition."""
+
+    NVME = "nvme"
+    SSD = "ssd"
+    HDD = "hdd"
+    RAMDISK = "ramdisk"
+    UNKNOWN = "unknown"
+
+
+class UnitKind(StrEnum):
+    """Schedulable execution-resource category."""
+
+    CPU = "cpu"
+    GPU = "gpu"
+    NPU = "npu"
+    DSP = "dsp"
+    MEDIA = "media"
+    UNKNOWN = "unknown"
+
+
+class Vendor(StrEnum):
+    """Normalized hardware vendor."""
+
+    ARM = "arm"
+    APPLE = "apple"
+    NVIDIA = "nvidia"
+    QUALCOMM = "qualcomm"
+    AMD = "amd"
+    INTEL = "intel"
+    UNKNOWN = "unknown"
+
+
+class Scheduler(StrEnum):
+    """Job scheduler detected on the host's PATH."""
+
+    SLURM = "slurm"
+    PBS = "pbs"
+    PUEUE = "pueue"
+    NONE = "none"

mainboard/gpu.py

@@ -0,0 +1,178 @@
+from __future__ import annotations
+
+from functools import cached_property
+from typing import TYPE_CHECKING, ClassVar
+
+from pydantic import Field
+
+from .enums import UnitKind, Vendor
+from .models.clock import Clock
+from .models.clock_info import ClockInfo
+from .models.energy_reading import EnergyReading
+from .models.gpu_snapshot import GPUSnapshot
+from .models.mem_info import MemInfo
+from .models.memory_usage import MemoryUsage
+from .models.pcie_info import PcieInfo
+from .models.thermal_state import ThermalState
+from .models.utilization import Utilization
+from .unit import Unit
+
+if TYPE_CHECKING:
+    from .models.process_info import ProcessInfo
+
+
+class GPU(Unit):
+    """GPU with telemetry and legacy profiling sensor accessors."""
+
+    providers: ClassVar[tuple[type[GPU], ...]] = ()
+
+    index: int = 0
+    kind: ClassVar[UnitKind] = UnitKind.GPU
+    vendor: Vendor = Field(default=Vendor.UNKNOWN)
+    backend: str = "none"
+
+    @classmethod
+    def register_providers(cls, *providers: type[GPU]) -> None:
+        """Register concrete providers used by `GPU.all`."""
+        cls.providers = providers
+
+    @classmethod
+    def all(cls) -> tuple[GPU, ...]:
+        """Return GPUs visible to supported providers."""
+        return tuple(gpu for provider in cls.providers for gpu in provider.all())
+
+    @cached_property
+    def name(self) -> str:
+        """Human-readable GPU name."""
+        return "unknown"
+
+    @cached_property
+    def uuid(self) -> str:
+        """Stable GPU identifier when the provider exposes one."""
+        return ""
+
+    @cached_property
+    def architecture(self) -> str:
+        """Human-readable architecture or generation name."""
+        return "unknown"
+
+    @cached_property
+    def total_memory_bytes(self) -> int:
+        """Total memory managed by this accelerator."""
+        return 0
+
+    @cached_property
+    def peak_bandwidth_gbs(self) -> float:
+        """Theoretical peak memory bandwidth in GB/s when known."""
+        return 0.0
+
+    @cached_property
+    def driver_version(self) -> tuple[int, int] | None:
+        """Driver or runtime version as `(major, minor)` when known."""
+        return None
+
+    @property
+    def mem_info(self) -> MemInfo:
+        """Current accelerator memory state."""
+        return MemInfo(total_bytes=self.total_memory_bytes)
+
+    @property
+    def memory_readings(self) -> tuple[MemoryUsage, ...]:
+        """Memory regions visible to this GPU."""
+        mem = self.mem_info
+        return (
+            MemoryUsage(
+                scope="device",
+                total_bytes=mem.total_bytes,
+                used_bytes=mem.used_bytes,
+                free_bytes=mem.free_bytes,
+                source=self.backend,
+                supported=mem.total_bytes > 0,
+            ),
+        )
+
+    @property
+    def clocks(self) -> ClockInfo:
+        """Current compute and memory clocks."""
+        return ClockInfo()
+
+    @property
+    def clock_readings(self) -> tuple[Clock, ...]:
+        """Clock readings grouped by hardware domain."""
+        clocks = self.clocks
+        return (
+            Clock(
+                domain="gpu_compute",
+                current_mhz=clocks.sm_mhz or None,
+                source=self.backend,
+                supported=clocks.sm_mhz > 0,
+            ),
+            Clock(
+                domain="memory",
+                current_mhz=clocks.memory_mhz or None,
+                source=self.backend,
+                supported=clocks.memory_mhz > 0,
+            ),
+        )
+
+    @property
+    def utilization(self) -> Utilization:
+        """Current compute and memory-controller utilization."""
+        return Utilization()
+
+    @property
+    def thermal(self) -> ThermalState:
+        """Current thermal state."""
+        return ThermalState()
+
+    @property
+    def energy(self) -> EnergyReading:
+        """Current power and cumulative energy reading."""
+        return EnergyReading()
+
+    @property
+    def pcie(self) -> PcieInfo:
+        """Current host interconnect throughput."""
+        return PcieInfo()
+
+    @property
+    def fan_speed_pct(self) -> int:
+        """Fan speed percentage, or zero when unavailable."""
+        return 0
+
+    @property
+    def temperature_c(self) -> int:
+        """Current GPU temperature in Celsius."""
+        return self.thermal.temperature_c
+
+    @property
+    def gpu_util_pct(self) -> int:
+        """Current compute utilization percentage."""
+        return self.utilization.gpu_pct
+
+    @property
+    def processes(self) -> list[ProcessInfo]:
+        """Processes using this accelerator."""
+        return []
+
+    def snapshot(self, name: str = "") -> GPUSnapshot:
+        """Point-in-time reading of all common sensor properties.
+
+        name: profiling region label to embed in the snapshot.
+        """
+        return GPUSnapshot(
+            name=name,
+            unit_name=self.name,
+            kind=self.kind,
+            vendor=self.vendor,
+            memory=self.memory_readings,
+            clocks=self.clock_readings,
+            utilization=self.utilization,
+            energy=self.energy,
+            thermal=self.thermal,
+            gpu_memory=self.mem_info,
+            gpu_clocks=self.clocks,
+            pcie=self.pcie,
+            fan_speed_pct=self.fan_speed_pct,
+            processes=self.processes,
+        )

mainboard/host.py

@@ -0,0 +1,133 @@
+from __future__ import annotations
+
+import platform
+import re
+from collections import Counter
+from functools import cached_property
+
+import psutil
+
+from . import shell
+from .enums import Vendor
+from .models.host_disk import HostDisk
+from .models.host_memory import HostMemory
+
+_CPU_MODEL_RE = re.compile(r"^(?:model name|hardware)\s*:\s*(.+)$", re.IGNORECASE | re.MULTILINE)
+_CPU_IMPLEMENTER_RE = re.compile(r"^CPU implementer\s*:\s*(.+)$", re.MULTILINE)
+_CPU_PART_RE = re.compile(r"^CPU part\s*:\s*(.+)$", re.MULTILINE)
+_ARM_IMPLEMENTERS = {
+    "0x41": "Arm",
+    "0x4e": "NVIDIA",
+    "0x51": "Qualcomm",
+    "0x61": "Apple",
+    "0xc0": "Ampere",
+}
+_VENDOR_BY_IMPLEMENTER = {
+    "0x41": Vendor.ARM,
+    "0x4e": Vendor.NVIDIA,
+    "0x51": Vendor.QUALCOMM,
+    "0x61": Vendor.APPLE,
+}
+_ARM_PARTS = {
+    ("0x41", "0xd85"): "Cortex-X925",
+    ("0x41", "0xd87"): "Cortex-A725",
+}
+
+
+class Host:
+    """Host CPU, memory, and disk identity for the current machine."""
+
+    @cached_property
+    def arch(self) -> str:
+        """CPU architecture string, e.g. `x86_64` or `aarch64`."""
+        return platform.machine().lower()
+
+    @cached_property
+    def cpu(self) -> str:
+        """CPU model name from `platform` or `/proc/cpuinfo`."""
+        if platform.system() == "Darwin" and (brand := shell.sysctl("machdep.cpu.brand_string")):
+            return brand
+        text = self.cpuinfo_text
+        if not text:
+            return platform.processor() or "unknown"
+        if m := _CPU_MODEL_RE.search(text):
+            return m.group(1).strip()
+        if name := self.arm_cpu_name:
+            return name
+        return platform.processor() or "unknown"
+
+    @cached_property
+    def cpu_vendor(self) -> Vendor:
+        """CPU core vendor inferred from OS identity records."""
+        if platform.system() == "Darwin":
+            return Vendor.APPLE
+        for record in self.cpuinfo_records:
+            implementer = record.get("CPU implementer", "").lower()
+            if vendor := _VENDOR_BY_IMPLEMENTER.get(implementer):
+                return vendor
+        return Vendor.UNKNOWN
+
+    @cached_property
+    def cpuinfo_text(self) -> str:
+        """Raw Linux `/proc/cpuinfo`, or an empty string when unavailable."""
+        return shell.read("/proc/cpuinfo")
+
+    @cached_property
+    def cpuinfo_records(self) -> tuple[dict[str, str], ...]:
+        """Parsed Linux `/proc/cpuinfo` records."""
+        return tuple(
+            {
+                key.strip(): value.strip()
+                for line in block.splitlines()
+                if ":" in line
+                for key, value in [line.split(":", 1)]
+            }
+            for block in self.cpuinfo_text.strip().split("\n\n")
+            if block.strip()
+        )
+
+    @cached_property
+    def arm_cpu_name(self) -> str:
+        """Human-readable ARM CPU core mix from MIDR implementer and part IDs."""
+        pairs = [
+            (record.get("CPU implementer", "").lower(), record.get("CPU part", "").lower())
+            for record in self.cpuinfo_records
+            if record.get("CPU implementer") and record.get("CPU part")
+        ]
+        counts = Counter(pairs)
+        names = []
+        for implementer, part in dict.fromkeys(pairs):
+            vendor = _ARM_IMPLEMENTERS.get(implementer, f"implementer {implementer}")
+            model = _ARM_PARTS.get((implementer, part), f"part {part}")
+            count = counts[(implementer, part)]
+            names.append(f"{count}x {vendor} {model}" if count > 1 else f"{vendor} {model}")
+        return " + ".join(names)
+
+    @cached_property
+    def logical_cpus(self) -> int:
+        """Number of logical CPU threads (including hyperthreading)."""
+        return psutil.cpu_count(logical=True) or 0
+
+    @cached_property
+    def physical_cpus(self) -> int:
+        """Number of physical CPU cores."""
+        return psutil.cpu_count(logical=False) or 0
+
+    @property
+    def cpu_freq_mhz(self) -> float | None:
+        """Current CPU frequency in MHz; `None` if the platform cannot report it."""
+        try:
+            freq = psutil.cpu_freq()
+        except (AttributeError, NotImplementedError, OSError):
+            return None
+        return freq.current if freq else None
+
+    @property
+    def memory(self) -> HostMemory:
+        """Live system memory snapshot; lazily samples psutil on first field access."""
+        return HostMemory()
+
+    @cached_property
+    def disk(self) -> HostDisk:
+        """All physical drives with their mounted partitions."""
+        return HostDisk()