refactor: 🧹 use hwloc instead of custom topology discovery

[robertodr]

Summary

The CPU topology discovery and thread pinning used a custom implementation that was not really portable. hwloc is the standard tool for this job.

Changes

• Add and integrate hwloc as dependency for cross-platform CPU topology discovery.

Checklist

• Tests added or updated to cover the changes
• Documentation updated (docstrings, docs/, CONTRIBUTING.md) if needed
• CHANGELOG / release notes updated if applicable

AI/LLM disclosure

• I did not use LLM tooling, or used it only privately for ideation
• I used the following tool to help write this PR description:
• I used the following tool to generate or modify code: GitHub Copilot gpt-5.6-sol (plan), claude-haiku-4.5/claude-sonnet-4.6 (execute)

Important

By opening this PR I confirm that I have read CONTRIBUTING.md and I agree to the terms of the Contributor License Agreement.

Warning

If you're contributing on behalf of your employer, contact cla@algorithmiq.fi to arrange a Corporate CLA.

[github-actions]

Docs preview: https://pr-208.monoprop-docs.pages.dev

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.70%. Comparing base (6243661) to head (3fc31ae).
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #208   +/-   ##
=======================================
  Coverage   97.70%   97.70%           
=======================================
  Files          14       14           
  Lines         742      742           
  Branches       98       98           
=======================================
  Hits          725      725           
  Misses         12       12           
  Partials        5        5           

Flag	Coverage Δ
cpp	97.70% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

[Copilot]

Pull request overview

🤖 AI text below 🤖

Refactors the CPU-topology discovery and partition thread pinning in monoprop to use hwloc, aiming for more portable and consistent topology enumeration and affinity binding across supported platforms.

Changes:

• Replace the custom /sys-parsing topology logic with an hwloc-backed implementation (CpuTopology.*) and expose a deterministic placement-policy helper for unit testing.
• Integrate hwloc into the C++ build (CMake + pkg-config) and update C++ unit tests accordingly.
• Update developer tooling and CI environments to install hwloc (scripts, workflows, devcontainer) and refresh related documentation.

Reviewed changes

Copilot reviewed 14 out of 14 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tools/install-deps.sh	Adds optional hwloc installation and broadens OS detection for the dependency installer script.
pyproject.toml	Updates macOS cibuildwheel pre-build dependencies to include hwloc.
docs/content/docs/features/parallelism.mdx	Updates documentation to reflect hwloc-based pinning support beyond Linux.
cpp/tests/cpu_topology_tests.cpp	Reworks CPU-topology tests for hwloc and adds deterministic placement-policy unit tests.
cpp/tests/CMakeLists.txt	Links unit tests against hwloc via PkgConfig::HWLOC.
cpp/monoprop/detail/partition/CpuTopology.h	Updates the public topology/pinning API docs and types for an hwloc implementation.
cpp/monoprop/detail/partition/CpuTopology.cpp	Implements topology discovery and thread pinning via hwloc, plus shared placement-policy logic.
cpp/monoprop/CMakeLists.txt	Adds pkg-config discovery for hwloc and wires PkgConfig::HWLOC into library linkage.
AGENTS.md	Documents hwloc as a required system dependency and where it’s used.
.github/workflows/test.yml	Ensures CI runners install hwloc on macOS and Ubuntu.
.github/workflows/qa-analysis.yml	Adds libhwloc-dev to QA workflow dependency installs.
.github/workflows/docpages.yml	Adds libhwloc-dev to docs build workflow dependency installs.
.github/workflows/copilot-setup-steps.yml	Adds libhwloc-dev to Copilot setup steps.
.devcontainer/Dockerfile	Installs libhwloc-dev in the devcontainer image.

Suppressed comments (1)

tools/install-deps.sh:217

• The script advises setting only CMAKE_PREFIX_PATH, but the build now discovers hwloc via pkg-config (pkg_check_modules(HWLOC …)), which typically requires PKG_CONFIG_PATH to include the install prefix when using a non-system INSTALL_PREFIX. Without that, a custom-prefix hwloc installed by this script may still not be found by CMake.

echo "Dependencies installation completed successfully!"
echo "Install location: $INSTALL_PREFIX"
echo "Make sure to set CMAKE_PREFIX_PATH=$INSTALL_PREFIX when building monoprop"

[Copilot]

Pull request overview

Copilot reviewed 17 out of 17 changed files in this pull request and generated no new comments.

Suppressed comments (1)

docs/content/docs/features/parallelism.mdx:32

• 🤖 AI text below 🤖

This incorrectly lists macOS as supporting thread pinning. hwloc 2.13's Darwin backend installs no CPU-binding hooks, so hwloc_set_cpubind fails and this implementation silently leaves workers unpinned. Please document macOS as topology-discovery-only rather than promising binding there.

| `monoprop_PARTITION_PINNING` | `on` | `0`/`false`/`no` disables pinning each partition to a core. Supported on platforms where hwloc can bind threads (Linux, macOS). |

[sonarqubecloud]

Quality Gate passed

Issues
1 New issue
0 Accepted issues

Measures
0 Security Hotspots
74.2% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud