QPY

QPY는 양자 회로를 저장하기 위한 Qiskit의 이식성 있는 크로스 플랫폼 바이너리 형식입니다. QPY C API는 여러 QkCircuit 객체를 파일이나 메모리 내 버퍼로 직렬화할 수 있으며, 이러한 두 표현 형식 중 어느 쪽에서든 모든 회로를 불러올 수 있습니다. 이 인터페이스에서 생성된 QPY 데이터는 Python qiskit.qpy 인터페이스와 호환됩니다.

qk_qpy_read_min_version() 로드된 라이브러리가 읽을 수 있는 가장 오래된 QPY 형식 버전을 반환합니다. 이는 Python 의 qiskit.qpy.QPY_COMPATIBILITY_VERSION.과 동일합니다. qk_qpy_write_min_version() C API가 기록할 수 있는 가장 오래된 버전을 반환합니다. 두 경계값이 다른 이유는 C API가 Rust QPY 구현체를 사용하는 반면, Python 은 구형 형식을 작성할 때 기존 구현체를 사용할 수 있기 때문입니다.

사용 중인 회로는 새로 할당된 것이므로 qk_qpy_free_circuits().을 사용하여 해제해야 합니다.

표준 덤프 함수는 네이티브 객체를 QkCircuit 처리하며, Python 과는 상호작용하지 않습니다. Python 확장 모듈에서 C API를 사용하는 경우, Python 함수인 qpy.dump() 및 를 사용해야 합니다. C API 함수는 Python 이 회로에서 QPY 페이로드를 생성하거나 불러와야 하는 경우 오류를 반환하기 때문입니다 qpy.load() .

다음 예제는 두 개의 회로도를 파일에 저장한 다음 다시 불러오는 방법입니다:

#include <qiskit.h>
#include <stddef.h>

int main(void) {
    QkCircuit *bell = qk_circuit_new(2, 0);
    qk_circuit_gate(bell, QkGate_H, (uint32_t[]){0}, NULL);
    qk_circuit_gate(bell, QkGate_CX, (uint32_t[]){0, 1}, NULL);

    QkCircuit *plus = qk_circuit_new(1, 0);
    qk_circuit_gate(plus, QkGate_H, (uint32_t[]){0}, NULL);

    const QkCircuit *circuits[] = {bell, plus};

    if (qk_qpy_dump_file(circuits, 2, "circuits.qpy", NULL) != QkExitCode_Success) {
        qk_circuit_free(plus);
        qk_circuit_free(bell);
        return 1;
    }

    QkQpyLoadedCircuits loaded = {NULL, 0};
    if (qk_qpy_load_file(&loaded, "circuits.qpy", NULL) != QkExitCode_Success) {
        qk_circuit_free(plus);
        qk_circuit_free(bell);
        return 1;
    }

    int result = loaded.len == 2 ? 0 : 1;
    qk_qpy_loaded_circuits_clear(&loaded);
    qk_circuit_free(plus);
    qk_circuit_free(bell);
    return result;
}

버퍼 변형들은 직렬화된 데이터를 할당합니다. 더 이상 필요하지 않게 되면 qk_qpy_free_buffer() 반환된 포인터와 그 정확한 크기를 에 전달하십시오. 이 *_with_version 변형들은 특정 QPY 출력 형식 버전을 선택합니다. 지원되는 최소 출력 버전을 확인하려면 qk_qpy_write_min_version() 쿼리를 실행하십시오. 실패할 가능성이 있는 모든 함수는 반환하며 QkExitCode, 여기에는 직렬화, 역직렬화, 경로 및 파일 I/O 오류에 대한 QkExitCode_QpyError 함수도 포함됩니다. 진단 세부 정보를 무시하는 것은 그들의 최종 error 주장이 무의미할 수 있습니다. 그렇지 않은 경우, QPY 오류가 발생하면 할당된, 널 문자로 종료되는 설명이 채워지며, 이는.을 사용하여 해제해야 합니다 qk_str_free(). 성공 시 또는 추가 진단 메시지가 없는 오류 발생 시 출력 포인터는 변경되지 않습니다.

함수

qk_qpy_read_min_version

uint8_t qk_qpy_read_min_version(void)

로드된 라이브러리에서 읽을 수 있는 가장 오래된 QPY 형식 버전을 가져옵니다.

리턴

읽기 지원이 가능한 가장 오래된 QPY 형식 버전.

qk_qpy_write_min_version

uint8_t qk_qpy_write_min_version(void)

로드된 라이브러리에서 쓰기 가능한 가장 오래된 QPY 형식 버전을 가져옵니다.

이 값을 덤프 *_with_version 함수의 하한값으로 사용하십시오.

이는 Python 의 QPY_COMPATIBILITY_VERSION

리턴

쓰기 작업에 대해 지원되는 가장 오래된 QPY 형식 버전입니다.

qk_qpy_dump_file

QkExitCode qk_qpy_dump_file(const QkCircuit *const *circuits, size_t num_circuits, const char *filename, char **error)

회로도를 QPY 파일에 기록합니다.

회로의 어떤 부분에서든 QPY 페이로드를 생성하기 위해 Python 인터프리터가 필요한 경우, 이 함수는 오류를 반환합니다. Python 확장 모듈에서 이 함수를 사용하는 경우, 이러한 제한을 피하기 위해 대신 qpy.dump() Python 함수를 사용해야 합니다.

안전

의 모든 요소는 유효한 을 가리켜야 circuits 합니다 QkCircuit. 입력값 중 유효한 정렬된 비공백 포인터가 아닌 것이 있는 경우, 동작은 정의되지 않습니다. filename 이 호출이 진행되는 동안 유효한 널 종료 문자열을 가리켜야 합니다. error null이거나 char 포인터를 가리키는 유효한 쓰기 가능한 포인터여야 합니다.

매개변수

회로 – 회로 num_circuits 포인터 배열을 가리키는 유효하고 null이 아닌 포인터.
num_circuits –.에 포함된 회로 포인터의 개수 circuits.
파일 이름 – 유효하고, null이 아니며, null로 끝나는 UTF-8 경로.
오류 – 오류 설명을 표시할 선택적 출력 위치. 반환된 문자열을 qk_str_free.을 사용하여 해제합니다.

리턴

QkExitCode_Success 성공 시, null 포인터인 QkExitCode_NullPointerError``QkExitCode_QpyError 경우, 또는 유효하지 않은 경로, 지원되지 않는 QPY 데이터, I/O 오류가 발생한 경우.

qk_qpy_dump_file_with_version

QkExitCode qk_qpy_dump_file_with_version(const QkCircuit *const *circuits, size_t num_circuits, const char *filename, uint8_t version, char **error)

특정 형식 버전을 사용하여 회로를 QPY 파일에 기록합니다.

안전

매개변수

회로 – 회로 num_circuits 포인터 배열을 가리키는 유효하고 null이 아닌 포인터.
num_circuits –.에 포함된 회로 포인터의 개수 circuits.
파일 이름 – 유효하고, null이 아니며, null로 끝나는 UTF-8 경로.
버전 – QPY 형식의 버전. 적어도 qk_qpy_write_min_version.에서 반환된 값이어야 합니다.
오류 – 오류 설명을 표시할 선택적 출력 위치. 반환된 문자열을 qk_str_free.을 사용하여 해제합니다.

리턴

.와 동일한 종료 코드입니다 qk_qpy_dump_file.

qk_qpy_load_file

QkExitCode qk_qpy_load_file(QkQpyLoadedCircuits *circuits, const char *filename, char **error)

QPY 파일에서 모든 회로를 불러옵니다.

QPY 페이로드 내 회로의 어떤 부분에서든 QkCircuit 객체를 생성하기 위해 Python 인터프리터가 필요한 경우, 이 함수는 오류를 반환합니다. Python 확장 모듈에서 이 함수를 사용하는 경우, 이러한 제한을 피하기 위해 대신 qpy.dump() Python 함수를 사용해야 합니다.

안전

filename 유효한 널 종료 문자열을 가리켜야 합니다. 유효한 null이 아닌, 정렬된 유효한 포인터여야 circuits 하며, 그렇지 않을 QpyLoadedCircuits 경우 동작이 정의되지 않습니다. error null이거나 char 포인터를 가리키는 유효한 포인터여야 합니다.

매개변수

파일 이름 – 유효하고, null이 아니며, null로 끝나는 UTF-8 경로.
회로 – 로드가 적용된 회로의 출력 위치.
오류 – 오류 설명을 표시할 선택적 출력 위치. 반환된 문자열을 qk_str_free.을 사용하여 해제합니다.

리턴

QkExitCode_Success 성공 시, null 포인터인 QkExitCode_NullPointerError 경우, 또는 파일을 읽을 수 없거나 QPY에서 지원되지 않는 QkExitCode_QpyError 경우. 반환된 배열과 그 배열에 포함된 모든 회로는 qk_qpy_loaded_circuits_clear.을 사용하여 해제해야 합니다.

qk_qpy_dump_buffer

QkExitCode qk_qpy_dump_buffer(const QkCircuit *const *circuits, size_t num_circuits, uint8_t **buffer, size_t *size, char **error)

회로를 새로 할당된 QPY 버퍼에 직렬화합니다.

안전

의 모든 요소는 유효한 을 가리켜야 circuits 합니다 QkCircuit. buffer 또한 이 호출이 진행되는 동안 각각 포인터 크기의 쓰기 작업 하나에 대해 유효해야 size 합니다. error null이거나, 포인터 쓰기 한 번에 대해 유효해야 합니다.

매개변수

회로 – 회로 num_circuits 포인터 배열을 가리키는 유효하고 null이 아닌 포인터.
num_circuits –.에 포함된 회로 포인터의 개수 circuits.
버퍼 – 새로 할당된 버퍼의 출력 위치. 실패 시에는 변경되지 않습니다.
size – 버퍼 크기를 바이트 단위로 표시하는 출력 위치. 실패 시에는 변경되지 않습니다.
오류 – 오류 설명을 표시할 선택적 출력 위치. 반환된 문자열을 qk_str_free.을 사용하여 해제합니다.

리턴

QkExitCode_Success 성공 시, null 포인터인 QkExitCode_NullPointerError 경우, 또는 직렬화가 실패한 QkExitCode_QpyError 경우. 반환된 버퍼는 qk_qpy_free_buffer.을 사용하여 해제해야 합니다.

qk_qpy_dump_buffer_with_version

QkExitCode qk_qpy_dump_buffer_with_version(const QkCircuit *const *circuits, size_t num_circuits, uint8_t **buffer, size_t *size, uint8_t version, char **error)

특정 형식 버전을 사용하여 회로를 새로 할당된 QPY 버퍼로 직렬화합니다.

안전

포인터에 대한 요구 사항은 qk_qpy_dump_buffer.와 동일합니다.

매개변수

회로 – 회로 num_circuits 포인터 배열을 가리키는 유효하고 null이 아닌 포인터.
num_circuits –.에 포함된 회로 포인터의 개수 circuits.
버퍼 – 새로 할당된 버퍼의 출력 위치. 실패 시에는 변경되지 않습니다.
size – 버퍼 크기를 바이트 단위로 표시하는 출력 위치. 실패 시에는 변경되지 않습니다.
버전 – QPY 형식의 버전. 적어도 qk_qpy_write_min_version.에서 반환된 값이어야 합니다.
오류 – 오류 설명을 표시할 선택적 출력 위치. 반환된 문자열을 qk_str_free.을 사용하여 해제합니다.

리턴

.와 동일한 종료 코드입니다 qk_qpy_dump_buffer.

qk_qpy_load_buffer

QkExitCode qk_qpy_load_buffer(QkQpyLoadedCircuits *circuits, const uint8_t *buffer, size_t size, char **error)

QPY 버퍼에서 모든 회로를 불러옵니다.

안전

buffer 는 바이트 size 단위의 읽기 작업에 유효해야 합니다. 는 null이 아니며 정렬된 유효한 포인터여야 circuits 하며, 그렇지 않을 QpyLoadedCircuits 경우 동작이 정의되지 않습니다. error null이거나 char 포인터를 가리키는 유효한 포인터여야 합니다.

매개변수

회로 – 로드가 적용된 회로의 출력 위치.
buffer – QPY 데이터 size 바이트를 포함하는 유효한 버퍼.
크기 – 의 크기를 바이트 단위로 buffer 나타낸 값입니다.
오류 – 오류 설명을 표시할 선택적 출력 위치. 반환된 문자열을 qk_str_free.을 사용하여 해제합니다.

리턴

QkExitCode_Success 성공 시, null 포인터인 QkExitCode_NullPointerError 경우, 또는 버퍼가 QPY에서 지원되지 않는 QkExitCode_QpyError 경우. 반환된 배열과 그 배열에 포함된 모든 회로는 qk_qpy_loaded_circuits_clear.을 사용하여 해제해야 합니다.

qk_qpy_loaded_circuits_clear

void qk_qpy_loaded_circuits_clear(QkQpyLoadedCircuits *circuits)

또는 qk_qpy_load_file 에 의해 반환된 무료 회로 qk_qpy_load_buffer.

안전

circuits null이거나, qk_qpy_load_file 또는 에 의해 채워진 포인터 QkCircuit 배열이 .data 필드에 포함된 QkQpyLoadedCircuits 객체를 가리키는 유효한 정렬된 포인터여야 합니다 qk_qpy_load_buffer. 그렇지 않은 경우, 이 함수의 동작은 정의되지 않습니다.

매개변수

회로 – QPY load 함수에 의해 초기화된 로드된 회로 객체에 대한 포인터이거나 null입니다.

qk_qpy_free_buffer

void qk_qpy_free_buffer(uint8_t *buffer, size_t size)

.에서 반환된 버퍼를 해제합니다 qk_qpy_dump_buffer.

안전

null이 아닌 는 정확히 이 를 가진 qk_qpy_dump_buffer 에 의해 반환되었어야 buffer 하며 size , 이전에 해제된 적이 없어야 합니다.

매개변수

buffer – 에 의해 반환된 버퍼이거나 qk_qpy_dump_buffer null입니다.
크기 –.에서 반환되는 버퍼 크기 qk_qpy_dump_buffer.

QkQpyLoadedCircuits

struct QkQpyLoadedCircuits

에서 출력된 데이터 또는 qk_qpy_load_file qk_qpy_load_buffer

여기에는 포인터 배열과 QkCircuit 길이가 포함되어 있습니다.

QPY 로드 함수를 통해 생성된 배열은 qiskit이 소유하며, 호출을 통해 해제해야 합니다 qk_qpy_loaded_circuits_clear.

QkCircuit **data

QPY 페이로드에서 불러온 포인터 QkCircuit 배열.

size_t len

.의 회로 수 data.

이 페이지가 도움이 되었습니까?

GitHub에서 버그, 오타를 보고하거나 컨텐츠를 요청하십시오.