scitex-resource 0.4.0

System resource info, processor usage logging, RAM limit — standalone module from the SciTeX ecosystem

scitex-resource

System resource info, processor usage logging, RAM limiting + machine-identity config.

Full Documentation · uv pip install scitex-resource[all]

---

Installation

pip install scitex-resource

Architecture

src/scitex_resource/
├── __init__.py                # public API surface
├── _machine.py                # canonical machine name + config resolution
├── _log_processor_usages.py   # CPU / RAM CSV logger (continuous)
├── limit_ram.py               # cap process RSS via resource.RLIMIT_AS
├── _compat.py                 # vendored str / gen helpers (decoupling)
├── _utils/                    # psutil wrappers (metrics / specs)
└── _specs/                    # rich human-readable snapshot helpers

1 Interfaces

Python API

import scitex_resource as r

# Hub-friendly metrics (cross-platform via psutil)
metrics = r.get_metrics()

# Canonical machine identity
name = r.get_machine_name()
cfg = r.get_machine_config()        # {"canonical_name", "aliases", "role", "hpc": {...}}

# Rich snapshot
specs = r.get_specs()

# CPU/RAM samples + continuous CSV logging
usage = r.get_processor_usages()
r.log_processor_usages("/tmp/usage.csv", limit_min=30, interval_s=1)

# Cap process RAM
r.limit_ram(0.5)

Demo

flowchart LR
    env["$SCITEX_RESOURCE_MACHINE"] --> resolve["resolve canonical name"]
    proj["./.scitex/resource/config.yaml"] --> resolve
    home["~/.scitex/resource/config.yaml"] --> resolve
    host["socket.gethostname()"] --> resolve
    resolve --> name["get_machine_name() → 'mba'"]
    resolve --> cfg["get_machine_config()"]
    psutil["psutil"] --> metrics["get_metrics()"]
    metrics --> snapshot[("cpu / mem / disk / gpu / load")]
    psutil --> log["log_processor_usages('/tmp/usage.csv', limit_min=30)"]
    log --> csv[("usage.csv (continuous)")]

Quick Start

import scitex_resource as r

print(r.get_machine_name())          # canonical machine identity
metrics = r.get_metrics()            # cpu / mem / disk / gpu / load
specs = r.get_specs()                # rich human-readable snapshot

Machine identity config — ~/.scitex/resource/config.yaml

machine:
  canonical_name: mba                  # what every scitex-* package uses to refer to this host
  aliases:                              # optional; cross-package discovery / drift detection
    - Yusukes-MacBook-Air
    - Yusukes-MacBook-Air.local
  role: head                            # generic role tag (head, worker, hpc-login, ...)
  hpc:                                  # optional; HPC-only
    cluster: spartan
    login_only: true
    partitions: [physical, sapphire]

Resolution cascade (highest precedence first):

1. $SCITEX_RESOURCE_MACHINE
2. <project>/.scitex/resource/config.yaml machine.canonical_name
3. ~/.scitex/resource/config.yaml machine.canonical_name
4. socket.gethostname().split(".", 1)[0]

Status

Standalone fork of scitex.resource. Deps: pandas, psutil, PyYAML, matplotlib.

Decoupling notes:

• scitex.str.readable_bytes / scitex.gen.fmt_size / scitex.str.printc → vendored as 3 small helpers in _compat.py.
• scitex.io._load.load / scitex.io._save.save → use pandas.read_csv / to_csv directly for the CSV log files.
• scitex.sh.sh → prefer scitex_sh if installed, fall back to plain subprocess.run (list-only).

The umbrella package's scitex.resource import path is preserved via a sys.modules-alias bridge.

Part of SciTeX

scitex-resource is part of SciTeX. Install via the umbrella with pip install scitex[resource] to use as scitex.resource (Python) or scitex resource ... (CLI).

Four Freedoms for Research

0. The freedom to run your research anywhere — your machine, your terms.
1. The freedom to study how every step works — from raw data to final manuscript.
2. The freedom to redistribute your workflows, not just your papers.
3. The freedom to modify any module and share improvements with the community.

AGPL-3.0 — because we believe research infrastructure deserves the same freedoms as the software it runs on.

License

AGPL-3.0-only (see LICENSE).

---