Add option to use mimalloc as global allocator (#16024)

mtreinish · web-flow · commit 32b3eceec4f5 · 2026-04-28T19:50:49.000Z
* Add option to use mimalloc as global allocator This commit adds a new feature to the cext and pyext crates to switch the global allocator to use mimalloc [1] instead of the system allocator. mimalloc promises better allocation performance and also lower resident set size over glibc, macOS's libmalloc, or window's allocator [2]. In local benchmarking using mimalloc improves runtime performance on transpiler bencmarks in asv about 10% on my x86_64 benchmarking system. The tradeoff for this is the mimalloc crate [3] internally builds and statically links the mimalloc c library from source as part of cargo's build process. This is all encapsulated in the mimalloc-sys's build.rs using the cc [4] crate so it embeds very cleanly into the build system. However, this does however require that a C compiler is available when building from source. For building the Python package and ironically the C standalone lib this was previously not a requirement. When the feature is enabled it switches the global allocator to use mimalloc. Since this is global for a compilation artifact we can only do it once in qiskit crate, and we'll want to do it either in pyext xor cext based on whether we're building a python extension or c standalone lib so that only the outermost crate is opinionated about which allocator to use. By default this feature is disabled on both crates and we opt-in to it in the build system. For building pyext the setup.py file updates the features we pass to setuptools-rust when building the extension to enable the mimalloc crate and set the global allocator in the pyext code. Similarly, the makefile is updated to do the same for build cext in standalone mode. If we don't want to make this enabled by default (primarily because of the dependency on a C compiler) for building from source we can update the logic in the build scripts to expose an option and only enable in CI for testing and for release artifacts. This is something we'll need to discuss before releasing this option. [1] https://github.com/microsoft/mimalloc [2] Leijen, D., Zorn, B., de Moura, L. (2019). Mimalloc: Free List Sharding in Action. In: Lin, A. (eds) Programming Languages and Systems. APLAS 2019. Lecture Notes in Computer Science(), vol 11893. Springer, Cham. https://doi.org/10.1007/978-3-030-34175-6_13 [3] https://crates.io/crates/mimalloc [4] https://docs.rs/cc/latest/cc/ * Make mimalloc opt-in by default This commit switches the mimalloc feature to be opt-in by default everywhere. Since building mimalloc requires a C compiler and this does significantly change the requirements for building Qiskit from source, making it opt-in for people that want it is the best course of action for now. This commit adds a new environment variable `QISKIT_BUILD_WITH_MIMALLOC=1` which is used to enable building mimalloc when building Qiskit. The CI jobs are updated to mix mimalloc and not in Python test jobs and also to always enable mimalloc in wheel builds for release. * Improve CONTRIBUTING.md build section formatting * Improve release notes * Enable mimalloc for asv This commti adds the mimalloc environment variable to the asv config too so that we are enabling the use of mimalloc when running asv numbers. This will mean the performance numbers we measure with asv are showing the performance with mimalloc. This is desired as it will better capture the performance of the packages we ship on release.
diff --git a/.github/workflows/branch-protection.yml b/.github/workflows/branch-protection.yml
@@ -106,6 +106,7 @@ jobs:
             install-optionals: true
             install-from-sdist: false
             qiskit-pycache: false
+            mimalloc: false
           - id: "Python newest"
             python: ${{ needs.config.outputs.python-new }}
             install-optionals: false
@@ -127,6 +128,7 @@ jobs:
           - id: "Python oldest"
             python: ${{ needs.config.outputs.python-old }}
             install-optionals: true
+            mimalloc: false
           - id: "Python newest"
             python: ${{ needs.config.outputs.python-new }}
             install-optionals: false
@@ -146,6 +148,7 @@ jobs:
           - id: "Python oldest"
             python: ${{ needs.config.outputs.python-old }}
             install-optionals: true
+            mimalloc: false
           - id: "Python newest"
             python: ${{ needs.config.outputs.python-new }}
             install-optionals: false
diff --git a/.github/workflows/test-linux.yml b/.github/workflows/test-linux.yml
@@ -29,6 +29,11 @@ on:
           structures when building Qiskit.
         type: boolean
         default: true
+      mimalloc:
+        description: >
+          Whether to build with mimalloc or not
+        type: boolean
+        default: true
 
 jobs:
   unit-tests:
@@ -61,6 +66,9 @@ jobs:
       - name: Set gate-caching settings for build
         if: ${{ !inputs.qiskit-pycache }}
         run: 'echo "QISKIT_NO_CACHE_GATES=1" >> $GITHUB_ENV'
+      - name: Set mimalloc for build
+        if: ${{ inputs.mimalloc }}
+        run: 'echo "QISKIT_BUILD_WITH_MIMALLOC=1" >> $GITHUB_ENV'
       - name: Install Qiskit from sdist
         if: ${{ inputs.install-from-sdist }}
         run: |
diff --git a/.github/workflows/test-mac.yml b/.github/workflows/test-mac.yml
@@ -8,18 +8,22 @@ on:
           Python version to currently test
         type: string
         required: true
-
       install-optionals:
         description: >
           Decides whether we install optyional dependencies
         type: boolean
         default: false
-
       runner:
         description: >
           Describes the system this workflow should run on.
         type: string
         required: true
+      mimalloc:
+        description: >
+          Whether to build with mimalloc or not
+        type: boolean
+        default: true
+
 jobs:
   tests-mac:
     name: ${{ inputs.runner }} - Python ${{ inputs.python-version }}
@@ -42,6 +46,9 @@ jobs:
             stestr | "${{ runner.os }}"
             stestr
           path: .stestr
+      - name: Set mimalloc for build
+        if: ${{ inputs.mimalloc }}
+        run: 'echo "QISKIT_BUILD_WITH_MIMALLOC=1" >> $GITHUB_ENV'
       - name: "Install dependencies"
         run: |
           set -e
diff --git a/.github/workflows/test-windows.yml b/.github/workflows/test-windows.yml
@@ -8,18 +8,21 @@ on:
           Python version to currently test
         type: string
         required: true
-
       runner:
         description: >
           Describes the system this workflow should run on.
         type: string
         required: true
-
       install-optionals:
         description: >
           Decides whether we install optyional dependencies
         type: boolean
         default: false
+      mimalloc:
+        description: >
+          Whether to build with mimalloc or not
+        type: boolean
+        default: true
 jobs:
   test-windows:
     name: ${{ inputs.runner }} - Python ${{ inputs.python-version }}
@@ -42,6 +45,9 @@ jobs:
             stestr | "${{ runner.os }}"
             stestr
           path: .stestr
+      - name: Set mimalloc for build
+        if: ${{ inputs.mimalloc }}
+        run: 'echo "QISKIT_BUILD_WITH_MIMALLOC=1" >> $GITHUB_ENV'
       - name: Install dependencies
         run: |
           python -m venv test-job
diff --git a/.github/workflows/wheels-build.yml b/.github/workflows/wheels-build.yml
@@ -108,9 +108,9 @@ jobs:
           cat >>"$GITHUB_ENV" <<EOF
           CIBW_BEFORE_ALL_LINUX=dnf install -y wget && {package}/tools/install_rust.sh
           CIBW_BEFORE_BUILD=bash ./tools/build_pgo.sh $PGO_WORK_DIR $PGO_OUT_PATH
-          CIBW_ENVIRONMENT=RUSTUP_TOOLCHAIN=stable RUSTFLAGS='-Cprofile-use=$PGO_OUT_PATH -Cllvm-args=-pgo-warn-missing-function'
-          CIBW_ENVIRONMENT_MACOS=MACOSX_DEPLOYMENT_TARGET='10.12' RUSTUP_TOOLCHAIN=stable RUSTFLAGS='-Cprofile-use=$PGO_OUT_PATH -Cllvm-args=-pgo-warn-missing-function'
-          CIBW_ENVIRONMENT_LINUX=RUSTUP_TOOLCHAIN=stable RUSTFLAGS='-Cprofile-use=$PGO_OUT_PATH -Cllvm-args=-pgo-warn-missing-function' PATH="\$PATH:\$HOME/.cargo/bin" CARGO_NET_GIT_FETCH_WITH_CLI="true"
+          CIBW_ENVIRONMENT=RUSTUP_TOOLCHAIN=stable RUSTFLAGS='-Cprofile-use=$PGO_OUT_PATH -Cllvm-args=-pgo-warn-missing-function' QISKIT_BUILD_WITH_MIMALLOC=1
+          CIBW_ENVIRONMENT_MACOS=MACOSX_DEPLOYMENT_TARGET='10.12' RUSTUP_TOOLCHAIN=stable RUSTFLAGS='-Cprofile-use=$PGO_OUT_PATH -Cllvm-args=-pgo-warn-missing-function' QISKIT_BUILD_WITH_MIMALLOC=1
+          CIBW_ENVIRONMENT_LINUX=RUSTUP_TOOLCHAIN=stable QISKIT_BUILD_WITH_MIMALLOC=1 RUSTFLAGS='-Cprofile-use=$PGO_OUT_PATH -Cllvm-args=-pgo-warn-missing-function' PATH="\$PATH:\$HOME/.cargo/bin" CARGO_NET_GIT_FETCH_WITH_CLI="true"
           EOF
         env:
           PGO_WORK_DIR: ${{ github.workspace }}/pgo-data
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -165,16 +165,27 @@ to `build_rust` overrides this default.
 
 ### Compile time options
 
-When building qiskit from source there are options available to control how
-Qiskit is built. Right now the only option is if you set the environment
-variable `QISKIT_NO_CACHE_GATES=1` this will disable runtime caching of
-Python gate objects when accessing them from a `QuantumCircuit` or `DAGCircuit`.
-This makes a tradeoff between runtime performance for Python access and memory
-overhead. Caching gates will result in better runtime for users of Python at
-the cost of increased memory consumption. If you're working with any custom
-transpiler passes written in Python or are otherwise using a workflow that
-repeatedly accesses the `operation` attribute of a `CircuitInstruction` or `op`
-attribute of `DAGOpNode` enabling caching is recommended.
+When building Qiskit from source there are options available to control how
+Qiskit is built. These options are set with the following environment variables:
+
+* `QISKIT_BUILD_WITH_MIMALLOC=1`: this will enable using
+  [mimalloc](https://github.com/microsoft/mimalloc) as the global allocator for
+  Qiskit instead of the default system allocator. This improves the runtime and
+  memory performance of Qiskit but will require having a C compiler installed
+  when building Qiskit.
+* `QISKIT_NO_CACHE_GATES=1`: this will disable runtime caching of
+  Python gate objects when accessing them from a `QuantumCircuit` or `DAGCircuit`.
+  This makes a tradeoff between runtime performance for Python access and memory
+  overhead. Caching gates will result in better runtime for users of Python at
+  the cost of increased memory consumption. If you're working with any custom
+  transpiler passes written in Python or are otherwise using a workflow that
+  repeatedly accesses the `operation` attribute of a `CircuitInstruction` or `op`
+  attribute of `DAGOpNode` enabling caching is recommended.
+
+These environment variables are only valid when building Qiskit the Python package
+with a PEP 517 compatible build tool or calling `setup.py` directly.
+Or as a standalone C library with `make c` (`QISKIT_NO_CACHE_GATES` has no effect
+when building a standalone C library).
 
 ## Issues and pull requests
 
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/Cargo.toml b/Cargo.toml
@@ -43,6 +43,7 @@ uuid = { version = "1.23", features = ["v4", "fast-rng"], default-features = fal
 anyhow = "1.0"
 binrw = "0.15"
 cbindgen = "0.29.2"
+mimalloc = "0.1.48"
 
 # Most of the crates don't need the feature `extension-module`, since only `qiskit-pyext` builds an
 # actual C extension (the feature disables linking in `libpython`, which is forbidden in Python
diff --git a/Makefile b/Makefile
@@ -14,6 +14,10 @@ ifneq ($(OS), Windows_NT)
 	OS := $(shell uname -s)
 endif
 
+ifeq ($(QISKIT_BUILD_WITH_MIMALLOC), 1)
+	MIMALLOC := --features=mimalloc
+endif
+
 .PHONY: default ruff env lint lint-incr style black test test_randomized pytest pytest_randomized test_ci coverage coverage_erase clean
 
 default: style lint-incr test ;
@@ -135,7 +139,7 @@ fix_cformat:
 # instead.
 .PHONY: build-clib build-clib-release build-clib-dev
 build-clib:
-	cargo rustc -p qiskit-cext --crate-type cdylib ${C_LIB_CARGO_FLAGS} -- ${C_LIB_RUSTC_FLAGS}
+	cargo rustc -p qiskit-cext ${MIMALLOC} --crate-type cdylib ${C_LIB_CARGO_FLAGS} -- ${C_LIB_RUSTC_FLAGS}
 build-clib-release: C_LIB_CARGO_FLAGS=--release
 build-clib-release: build-clib
 build-clib-dev: C_LIB_CARGO_FLAGS=--profile dev
diff --git a/asv.conf.json b/asv.conf.json
@@ -11,7 +11,7 @@
     ],
     "build_command": [
         "python -m pip install -U build",
-        "python -m build --outdir {build_cache_dir} --wheel {build_dir}"
+        "QISKIT_BUILD_WITH_MIMALLOC=1 python -m build --outdir {build_cache_dir} --wheel {build_dir}"
     ],
     "branches": ["main"],
     "dvcs": "git",
diff --git a/crates/cext/Cargo.toml b/crates/cext/Cargo.toml
@@ -30,6 +30,7 @@ hashbrown.workspace = true
 rand.workspace = true
 rand_pcg.workspace = true
 anyhow.workspace = true
+mimalloc = { workspace = true, optional = true}
 
 [features]
 python_binding = ["dep:pyo3"]
diff --git a/crates/cext/src/lib.rs b/crates/cext/src/lib.rs
@@ -25,6 +25,13 @@ pub mod transpiler;
 
 pub use exit_codes::ExitCode;
 
+#[cfg(feature = "mimalloc")]
+use mimalloc::MiMalloc;
+
+#[cfg(feature = "mimalloc")]
+#[global_allocator]
+static GLOBAL: MiMalloc = MiMalloc;
+
 /// Get the C API version of the loaded library.
 ///
 /// If you are dynamically linking against Qiskit, in either a stand-alone or Python-extension
diff --git a/crates/pyext/Cargo.toml b/crates/pyext/Cargo.toml
@@ -41,3 +41,4 @@ qiskit-cext-vtable = { workspace = true, features = ["python_binding", "addr"] }
 qiskit-transpiler.workspace = true
 qiskit-quantum-info.workspace = true
 qiskit-synthesis.workspace = true
+mimalloc = { workspace = true, optional = true }
diff --git a/crates/pyext/src/lib.rs b/crates/pyext/src/lib.rs
@@ -15,6 +15,13 @@ pub use qiskit_cext::*;
 
 mod capi;
 
+#[cfg(feature = "mimalloc")]
+use mimalloc::MiMalloc;
+
+#[cfg(feature = "mimalloc")]
+#[global_allocator]
+static GLOBAL: MiMalloc = MiMalloc;
+
 #[inline(always)]
 #[doc(hidden)]
 fn add_submodule<F>(m: &Bound<PyModule>, constructor: F, name: &str) -> PyResult<()>
diff --git a/pyproject.toml b/pyproject.toml
@@ -300,16 +300,16 @@ before-test = "pip install --only-binary=numpy,scipy numpy scipy -c constraints.
 # specific job override is needed. For example tier 1 platforms locally override
 # the before-build and environment configuration to enable PGO,
 # see: .github/workflows/wheels.yml for the jobs where this is done
-environment = 'RUSTUP_TOOLCHAIN="stable"'
+environment = 'RUSTUP_TOOLCHAIN="stable" QISKIT_BUILD_WITH_MIMALLOC=1'
 
 [tool.cibuildwheel.linux]
 before-all = "yum install -y wget && {package}/tools/install_rust.sh"
-environment = 'PATH="$PATH:$HOME/.cargo/bin" CARGO_NET_GIT_FETCH_WITH_CLI="true" RUSTUP_TOOLCHAIN="stable"'
+environment = 'PATH="$PATH:$HOME/.cargo/bin" CARGO_NET_GIT_FETCH_WITH_CLI="true" RUSTUP_TOOLCHAIN="stable" QISKIT_BUILD_WITH_MIMALLOC=1'
 repair-wheel-command = "auditwheel repair -w {dest_dir} {wheel} && pipx run abi3audit --strict --report {wheel}"
 
 [tool.cibuildwheel.macos]
 repair-wheel-command = "delocate-wheel --require-archs {delocate_archs} -w {dest_dir} -v {wheel} && pipx run abi3audit --strict --report {wheel}"
-environment = "MACOSX_DEPLOYMENT_TARGET='10.12' RUSTUP_TOOLCHAIN=stable"
+environment = "MACOSX_DEPLOYMENT_TARGET='10.12' RUSTUP_TOOLCHAIN=stable QISKIT_BUILD_WITH_MIMALLOC=1"
 
 [tool.cibuildwheel.windows]
 test-command = "cp -r {project}/test . && stestr --test-path test/python run --abbreviate"
diff --git a/releasenotes/notes/mimalloc-403d3300aa698fae.yaml b/releasenotes/notes/mimalloc-403d3300aa698fae.yaml
@@ -0,0 +1,11 @@
+---
+features_misc:
+  - The precompiled wheels on PyPI are now built using `mimalloc <https://github.com/microsoft/mimalloc>`__
+    as the global allocator. This improves the runtime performance of Qiskit and also should
+    reduce the resident set size when running Qiskit.
+build:
+  - Qiskit can now be optionally built using `mimalloc <https://github.com/microsoft/mimalloc>`__
+    as the global allocator to improve the runtime performance of Qiskit.
+    To opt-in to using mimalloc, set the environment variable ``QISKIT_BUILD_WITH_MIMALLOC=1``.
+    This option can be used when either building the Python package or when using the Makefile
+    (`make c`) to build a standalone shared library.
diff --git a/setup.py b/setup.py
@@ -135,6 +135,9 @@ def get_package_dir(package: str) -> Path:
 else:
     features = ["cache_pygates"]
 
+if os.getenv("QISKIT_BUILD_WITH_MIMALLOC") == "1":
+    features.append("mimalloc")
+
 
 setup(
     rust_extensions=[
