{"id":3824,"library":"tcmlib","title":"Thread Composability Manager","description":"tcmlib is a Python library by Intel that implements the Thread Composability Manager. It coordinates CPU resource usage between Intel® oneAPI Threading Building Blocks (oneTBB) and Intel® OpenMP to prevent excessive oversubscription when both runtimes are used concurrently within a single process. This helps optimize performance for multi-threaded Python applications, particularly in AI/ML and scientific computing workloads. The library is currently at version 1.4.1 and is actively maintained by Intel.","status":"active","version":"1.4.1","language":"en","source_language":"en","source_url":"https://github.com/oneapi-src/oneTBB","tags":["threading","performance","intel","oneapi","openmp","concurrency"],"install":[{"cmd":"pip install tcmlib","lang":"bash","label":"Install via pip"}],"dependencies":[],"imports":[{"note":"While the package can be imported, its primary functionality, the Thread Composability Manager, is often activated via an environment variable (TCM_ENABLE=1) rather than direct Python API calls for global effect. Specific direct Python APIs within 'tcmlib' itself are not extensively documented publicly, unlike the 'tbb' module within the oneTBB project, which offers a context manager like `tbb.Monkey()` for similar composability.","symbol":"tcmlib (module)","correct":"import tcmlib"}],"quickstart":{"code":"import os\nimport numpy as np\nimport time\n\n# The Thread Composability Manager is often enabled via an environment variable.\n# For demonstration, we'll set it here, but typically it's set before the Python process starts.\n# Ensure Intel oneTBB and OpenMP runtimes are installed and configured for optimal effect.\n\n# NOTE: For actual use, set this environment variable BEFORE running your Python script,\n# e.g., in bash: export TCM_ENABLE=1 python your_script.py\n# Or in a system-wide environment configuration.\n\nos.environ['TCM_ENABLE'] = os.environ.get('TCM_ENABLE', '1') # Set to '1' to enable, '0' to disable if not already set.\n\nprint(f\"TCM_ENABLE is set to: {os.environ.get('TCM_ENABLE')}\")\n\ndef heavy_computation(size):\n    # Simulate a compute-intensive task that might use OpenMP/oneTBB internally\n    start_time = time.time()\n    matrix_a = np.random.rand(size, size)\n    matrix_b = np.random.rand(size, size)\n    result = np.dot(matrix_a, matrix_b)\n    end_time = time.time()\n    return end_time - start_time\n\nif __name__ == '__main__':\n    print(\"Starting heavy computation...\")\n    duration = heavy_computation(1000) # Adjust size based on your CPU/memory\n    print(f\"Computation finished in {duration:.4f} seconds.\")\n    print(\"To observe the effects of tcmlib, compare performance with and without TCM_ENABLE=1,\")\n    print(\"especially when other Intel-optimized libraries (like NumPy with oneMKL) are also used.\")\n\n# Clean up environment variable for subsequent runs in the same shell/notebook session if needed\n# del os.environ['TCM_ENABLE']","lang":"python","description":"The primary way to enable the Thread Composability Manager's effects is by setting the `TCM_ENABLE` environment variable to `1` before running your Python application. This allows `tcmlib` to coordinate multi-threading runtimes like oneTBB and OpenMP used by underlying libraries (e.g., NumPy with Intel® oneAPI Math Kernel Library (oneMKL)). The Python package itself provides the necessary hooks and runtime components for this coordination."},"warnings":[{"fix":"Ensure `export TCM_ENABLE=1` is set in your shell environment or configured at a system level before launching Python applications that use Intel-optimized libraries with concurrent threading.","message":"The Thread Composability Manager's core functionality is largely activated by setting the `TCM_ENABLE=1` environment variable *before* your Python script executes, rather than through direct Python API calls within your code. Failing to set this environment variable will prevent the manager from coordinating resources.","severity":"gotcha","affected_versions":"All versions"},{"fix":"For maximum benefit, ensure you are using Intel-optimized Python distributions or libraries linked against Intel® oneAPI components (like oneMKL) in your environment.","message":"tcmlib operates by coordinating Intel® oneAPI Threading Building Blocks (oneTBB) and Intel® OpenMP. Its benefits are most pronounced when your Python application, or the libraries it depends on (e.g., NumPy, SciPy if linked against oneMKL), utilize these underlying Intel runtimes. Without these components, the `tcmlib` package may have little to no discernible effect on performance.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Consult the license documentation provided with the `tcmlib` package or on its PyPI page for full details.","message":"The `tcmlib` package is distributed under an 'Other/Proprietary License (Intel Simplified Software License)'. Users should review the terms of this license to ensure compliance with their project requirements.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Deploy on systems with Intel CPUs and recommended software stacks (e.g., Intel oneAPI Toolkits) to leverage the full benefits.","message":"As `tcmlib` is an Intel-specific optimization library, its performance benefits are primarily targeted at Intel CPU architectures. While it may not cause issues on other architectures, its intended performance gains might not be realized without compatible Intel hardware and software stacks. The wheels available on PyPI target `manylinux` and `win_amd64` for `x86_64` architecture, supporting Python 2 and 3.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}