14618237876

Committed 23 Apr 2025 12:33PM UTC coverage: 87.925% (-0.3%) from 88.192%

Build # 14618237876

Build Type

push

github

Committed by

web-flow

Commit Message

Add initial C API for circuit construction (#14006)

* Add initial C API for circuit construction

Building off the infrastructure for the sparse observable added in
PR #13445 this commit adds a C FFI for building Quantum Circuits. Right
now there is a function to create an empty circuit with n qubits and m
clbits and then a function to add standard gates to a circuit and then
also get the op counts out of a circuit. This is a start of the
functionality for a C API around interacting with circuits, later PRs
will expand this so we can have a more fully featured C API in the
future.

Part of #13276

* Add functions for standard instructions (except delay)

* Apply suggestions from code review

Co-authored-by: Julien Gacon <gaconju@gmail.com>

* Rename qk_circuit_free_count_ops() to qk_opcounts_free()

This also updates the test logic to make sure we always free even in
case of a failure.

* Add release note

* Add function to get instruction details

* Rename QkStandardGate -> QkGate

* Apply suggestions from code review

Co-authored-by: Julien Gacon <gaconju@gmail.com>

* Add safety comments

* Add methods to lookup num qubits and num params for gates

* Update docs around null pointers for qubits and params on gate append function

* Fix clang-format-14 error

Locally I was using clang-format-19 while in CI we run with
clang-format-14. Version 14 was flagging this difference while version
19 was happy. This commit makes the change to make version 14 happy in
CI.

* Add missing if to docstrings

* Fix merge

* Fix macOS tests

* Fix cformat

* Update test/c/CMakeLists.txt

Co-authored-by: Julien Gacon <gaconju@gmail.com>

* Try static lib for common

* Fix windows build warnings

* Try adding the parent path to the path on windows

* Use const pointers for strings in structs

* Improve docstrings for C API

* Improve equality check failures in sanity check tests

* Fix rustfmt

* Simplify cmake config for tests

* Apply naming suggestions

---------

... (continued)

Coverage Stats

14 of 267 new or added lines in 5 files covered. (5.24%)

28 existing lines in 2 files now uncovered.

74222 of 84415 relevant lines covered (87.93%)

435922.88 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

0.0

/crates/cext/src/pointers.rs

// This code is part of Qiskit.
//
// (C) Copyright IBM 2024
//
// This code is licensed under the Apache License, Version 2.0. You may
// obtain a copy of this license in the LICENSE.txt file in the root directory
// of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
//
// Any modifications or derivative works of this code must retain this
// copyright notice, and modified files need to carry a notice indicating
// that they have been altered from the originals.

use crate::exit_codes::CInputError;

/// Check the pointer is not null and is aligned.
pub(crate) fn check_ptr<T>(ptr: *const T) -> Result<(), CInputError> {
    if ptr.is_null() {
        return Err(CInputError::NullPointerError);
    };
    if !ptr.is_aligned() {
        return Err(CInputError::AlignmentError);
    };
    Ok(())
}

/// Casts a const pointer to a reference. Panics is the pointer is null or not aligned.
///
/// # Safety
///
/// This function requires ``ptr`` to be point to an initialized object of type ``T``.
/// While the resulting reference exists, the memory pointed to must not be mutated.
pub(crate) unsafe fn const_ptr_as_ref<'a, T>(ptr: *const T) -> &'a T {
    check_ptr(ptr).unwrap();
    let as_ref = unsafe { ptr.as_ref() };
    as_ref.unwrap() // we know the pointer is not null, hence we can safely unwrap
}

/// Casts a mut pointer to a mut reference. Panics is the pointer is null or not aligned.
///
/// # Safety
///
/// This function requires ``ptr`` to be point to an initialized object of type ``T``.
/// While the resulting reference exists, the memory pointed to must not be accessed otherwise.
pub(crate) unsafe fn mut_ptr_as_ref<'a, T>(ptr: *mut T) -> &'a mut T {
    check_ptr(ptr).unwrap();
    let as_mut_ref = unsafe { ptr.as_mut() };
    as_mut_ref.unwrap() // we know the pointer is not null, hence we can safely unwrap
}

1	// This code is part of Qiskit.
2	//
3	// (C) Copyright IBM 2024
4	//
5	// This code is licensed under the Apache License, Version 2.0. You may
6	// obtain a copy of this license in the LICENSE.txt file in the root directory
7	// of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
8	//
9	// Any modifications or derivative works of this code must retain this
10	// copyright notice, and modified files need to carry a notice indicating
11	// that they have been altered from the originals.
12
13	use crate::exit_codes::CInputError;
14
15	/// Check the pointer is not null and is aligned.
NEW 16	pub(crate) fn check_ptr<T>(ptr: *const T) -> Result<(), CInputError> {	×
NEW 17	if ptr.is_null() {	×
NEW 18	return Err(CInputError::NullPointerError);	×
NEW 19	};	×
NEW 20	if !ptr.is_aligned() {	×
NEW 21	return Err(CInputError::AlignmentError);	×
NEW 22	};	×
NEW 23	Ok(())	×
NEW 24	}	×
25
26	/// Casts a const pointer to a reference. Panics is the pointer is null or not aligned.
27	///
28	/// # Safety
29	///
30	/// This function requires ``ptr`` to be point to an initialized object of type ``T``.
31	/// While the resulting reference exists, the memory pointed to must not be mutated.
NEW 32	pub(crate) unsafe fn const_ptr_as_ref<'a, T>(ptr: *const T) -> &'a T {	×
NEW 33	check_ptr(ptr).unwrap();	×
NEW 34	let as_ref = unsafe { ptr.as_ref() };	×
NEW 35	as_ref.unwrap() // we know the pointer is not null, hence we can safely unwrap	×
NEW 36	}	×
37
38	/// Casts a mut pointer to a mut reference. Panics is the pointer is null or not aligned.
39	///
40	/// # Safety
41	///
42	/// This function requires ``ptr`` to be point to an initialized object of type ``T``.
43	/// While the resulting reference exists, the memory pointed to must not be accessed otherwise.
NEW 44	pub(crate) unsafe fn mut_ptr_as_ref<'a, T>(ptr: *mut T) -> &'a mut T {	×
NEW 45	check_ptr(ptr).unwrap();	×
NEW 46	let as_mut_ref = unsafe { ptr.as_mut() };	×
NEW 47	as_mut_ref.unwrap() // we know the pointer is not null, hence we can safely unwrap	×
NEW 48	}	×

Qiskit / qiskit / 14618237876

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous