API Documentation

C3objs

Basic custom objects.

class c3.c3objs.C3obj(name, desc='', comment='', params=None)

Bases: object

Represents an abstract object with parameters. To be inherited from.

Parameters

• name (str) – short name that will be used as identifier

• desc (str) – longer description of the component

• comment (str) – additional information about the component

• params (dict) – Parameters in this dict can be accessed and optimized

asdict() → dict

class c3.c3objs.Quantity(value, unit='undefined', min_val=None, max_val=None, symbol='\\alpha')

Bases: object

Represents any physical quantity used in the model or the pulse specification. For arithmetic operations just the numeric value is used. The value itself is stored in an optimizer friendly way as a float between -1 and 1. The conversion is given by

scale (value + 1) / 2 + offset

Parameters

• value (np.array(np.float64) or np.float64) – value of the quantity

• min_val (np.array(np.float64) or np.float64) – minimum this quantity is allowed to take

• max_val (np.array(np.float64) or np.float64) – maximum this quantity is allowed to take

• unit (str) – physical unit

• symbol (str) – latex representation

add(val)

asdict() → dict

Return a config-compatible dictionary representation.

get_limits()

get_opt_value() → numpy.ndarray

Get an optimizer friendly representation of the value.

get_value(val: tf.float64 = None, dtype: <module 'tensorflow._api.v2.dtypes' from '/home/docs/checkouts/readthedocs.org/user_builds/c3-toolset/envs/master/lib/python3.7/site-packages/tensorflow/_api/v2/dtypes/__init__.py'> = None) → tensorflow.python.framework.ops.Tensor

Return the value of this quantity as tensorflow.

Parameters

• val (tf.float64) –

• dtype (tf.dtypes) –

numpy() → numpy.ndarray

Return the value of this quantity as numpy.

set_limits(min_val, max_val)

set_opt_value(val: float) → None

Set value optimizer friendly.

Parameters

val (tf.float64) – Tensorflow number that will be mapped to a value between -1 and 1.

set_value(val, extend_bounds=False)

subtract(val)

c3.c3objs.hjson_decode(z)

c3.c3objs.hjson_encode(z)

c3.c3objs.jsonify_list(data, transform_arrays=True)

Experiment module

Experiment class that models and simulates the whole experiment.

It combines the information about the model of the quantum device, the control stack and the operations that can be done on the device.

Given this information an experiment run is simulated, returning either processes, states or populations.

class c3.experiment.Experiment(pmap: Optional[c3.parametermap.ParameterMap] = None, prop_method=None)

Bases: object

It models all of the behaviour of the physical experiment, serving as a host for the individual parts making up the experiment.

Parameters

pmap (ParameterMap) –

including model: Model

The underlying physical device.

generator: Generator

The infrastructure for generating and sending control signals to the device.

gateset: GateSet

A gate level description of the operations implemented by control pulses.

asdict() → Dict

Return a dictionary compatible with config files.

compute_propagators()

Compute the unitary representation of operations. If no operations are specified in self.opt_gates the complete gateset is computed.

Returns

A dictionary of gate names and their unitary representation.

Return type

dict

compute_states() → Dict[c3.signal.gates.Instruction, List[tensorflow.python.framework.ops.Tensor]]

Employ a state solver to compute the trajectory of the system.

Returns

List of states of the system from simulation.

Return type

List[tf.tensor]

enable_qasm() → None

Switch the sequencing format to QASM. Will become the default.

evaluate_legacy(sequences)

Compute the population values for a given sequence of operations.

Parameters

sequences (str list) – A list of control pulses/gates to perform on the device.

Returns

A list of populations

Return type

list

evaluate_qasm(sequences)

Compute the population values for a given sequence (in QASM format) of operations.

Parameters

sequences (dict list) – A list of control pulses/gates to perform on the device in QASM format.

Returns

A list of populations

Return type

list

expect_oper(state, lindbladian, oper)

from_dict(cfg: Dict) → None

Load experiment from dictionary

get_VZ(target, params)

Returns the appropriate Z-rotation.

get_perfect_gates(gate_keys: Optional[list] = None) → Dict[str, numpy.ndarray]

Return a perfect gateset for the gate_keys.

Parameters

gate_keys (list) – (Optional) List of gates to evaluate.

Returns

A dictionary of gate names and np.array representation of the corresponding unitary

Return type

Dict[str, np.array]

Raises

Exception – Raise general exception for undefined gate

load_quick_setup(filepath: str) → None

Load a quick setup file.

Parameters

filepath (str) – Location of the configuration file

lookup_gate(name, qubits, params=None) → tensorflow.python.framework.constant_op.constant

Returns a fixed operation or a parametric virtual Z gate. To be extended to general parametric gates.

populations(state, lindbladian)

Compute populations from a state or density vector.

Parameters

• state (tf.Tensor) – State or densitiy vector.

• lindbladian (boolean) – Specify if conversion to density matrix is needed.

Returns

Vector of populations.

Return type

tf.Tensor

process(populations, labels=None)

Apply a readout procedure to a population vector. Very specialized at the moment.

Parameters

• populations (list) – List of populations from evaluating.

• labels (list) – List of state labels specifying a subspace.

Returns

A list of processed populations.

Return type

list

quick_setup(cfg) → None

Load a quick setup cfg and create all necessary components.

Parameters

cfg (Dict) – Configuration options

read_config(filepath: str) → None

Load a file and parse it to create a Model object.

Parameters

filepath (str) – Location of the configuration file

set_created_by(config)

Store the config file location used to created this experiment.

set_enable_store_unitaries(flag, logdir, exist_ok=False)

Saving of unitary propagators.

Parameters

• flag (boolean) – Enable or disable saving.

• logdir (str) – File path location for the resulting unitaries.

set_opt_gates(gates)

Specify a selection of gates to be computed.

Parameters

gates (Identifiers of the gates of interest. Can contain duplicates.) –

set_opt_gates_seq(seqs)

Specify a selection of gates to be computed.

Parameters

seqs (Identifiers of the sequences of interest. Can contain duplicates.) –

set_prop_method(prop_method=None) → None

Configure the selected propagation method by either linking the function handle or looking it up in the library.

store_Udict(goal)

Save unitary as text and pickle.

goal: tf.float64

Value of the goal function, if used.

write_config(filepath: str) → None

Write dictionary to a HJSON file.

Model module

The model class, containing information on the system and its modelling.

class c3.model.Model(subsystems=None, couplings=None, tasks=None, max_excitations=0)

Bases: object

What the theorist thinks about from the system.

Class to store information about our system/problem/device. Different models can represent the same system.

Parameters

• subsystems (list) – List of individual, non-interacting physical components like qubits or resonators

• couplings (list) – List of interaction operators between subsystems, like couplings or drives.

• tasks (list) – Badly named list of processing steps like line distortions and read out modeling

• max_excitations (int) – Allow only up to max_excitations in the system

asdict() → dict

Return a dictionary compatible with config files.

blowup_excitations(op)

cut_excitations(op)

fromdict(cfg: dict) → None

Load a file and parse it to create a Model object.

Parameters

cfg (dict) – configuration file

get_Frame_Rotation(t_final: numpy.float64, freqs: dict, framechanges: dict)

Compute the frame rotation needed to align Lab frame and rotating Eigenframes of the qubits.

Parameters

• t_final (tf.float64) – Gate length

• freqs (list) – Frequencies of the local oscillators.

• framechanges (list) – List of framechanges. A phase shift applied to the control signal to compensate relative phases of drive oscillator and qubit.

Returns

A (diagonal) propagator that adjust phases

Return type

tf.Tensor

get_Hamiltonian(signal=None)

Get a hamiltonian with an optional signal. This will return an hamiltonian over time. Can be used e.g. for tuning the frequency of a transmon, where the control hamiltonian is not easily accessible. If max.excitation is non-zero the resulting Hamiltonian is cut accordingly

get_Hamiltonians()

get_Lindbladians()

get_dephasing_channel(t_final, amps)

Compute the matrix of the dephasing channel to be applied on the operation.

Parameters

• t_final (tf.float64) – Duration of the operation.

• amps (dict of tf.float64) – Dictionary of average amplitude on each drive line.

Returns

Matrix representation of the dephasing channel.

Return type

tf.tensor

get_ground_state() → tensorflow.python.framework.constant_op.constant

get_qubit_freqs() → List[float]

get_sparse_Hamiltonian(signal=None)

get_sparse_Hamiltonians()

get_state_indeces(states: List[Tuple]) → List[int]

get_state_index(state: Tuple) → int

list_parameters()

read_config(filepath: str) → None

Load a file and parse it to create a Model object.

Parameters

filepath (str) – Location of the configuration file

set_FR(use_FR)

Setter for the frame rotation option for adjusting the individual rotating frames of qubits when using gate sequences

set_components(subsystems, couplings=None, max_excitations=0) → None

set_dephasing_strength(dephasing_strength)

set_dressed(dressed)

Go to a dressed frame where static couplings have been eliminated.

Parameters

dressed (boolean) –

set_lindbladian(lindbladian)

Set whether to include open system dynamics.

Parameters

lindbladian (boolean) –

set_max_excitations(max_excitations) → None

Set the maximum number of excitations in the system used for propagation.

set_tasks(tasks) → None

update_Hamiltonians()

Recompute the matrix representations of the Hamiltonians.

update_Lindbladians()

Return Lindbladian operators and their prefactors.

update_dressed(ordered=True)

Compute the Hamiltonians in the dressed basis by diagonalizing the drift and applying the resulting transformation to the control Hamiltonians.

update_drift_eigen(ordered=True)

Compute the eigendecomposition of the drift Hamiltonian and store both the Eigenenergies and the transformation matrix.

update_model(ordered=True)

write_config(filepath: str) → None

Write dictionary to a HJSON file.

Parameter map

ParameterMap class

class c3.parametermap.ParameterMap(instructions: List[c3.signal.gates.Instruction] = [], generator=None, model=None)

Bases: object

Collects information about control and model parameters and provides different representations depending on use.

asdict(instructions_only=True) → dict

Return a dictionary compatible with config files.

check_limits(opt_map)

Check if all elements of equal ids have the same limits. This has to be checked against if setting values optimizer friendly.

Parameters

opt_map –

fromdict(cfg: dict) → None

get_full_params() → Dict[str, c3.c3objs.Quantity]

Returns the full parameter vector, including model and control parameters.

get_key_from_scaled_index(idx, opt_map=None) → str

Get the key of the value at position ìdx of the scaled_parameters output :param idx: :param opt_map:

get_not_opt_params(opt_map=None) → Dict[str, c3.c3objs.Quantity]

get_opt_limits()

get_opt_map(opt_map=None) → List[List[str]]

get_opt_units() → List[str]

Returns a list of the units of the optimized quantities.

get_parameter(par_id: Tuple[str, ...]) → c3.c3objs.Quantity

Return one the current parameters.

Parameters

par_id (tuple) – Hierarchical identifier for parameter.

Returns

Return type

Quantity

get_parameter_dict(opt_map=None) → Dict[str, c3.c3objs.Quantity]

Return the current parameters in a dictionary including keys. :param opt_map:

Returns

Return type

Dictionary with Quantities

get_parameters(opt_map=None) → List[c3.c3objs.Quantity]

Return the current parameters.

Parameters

opt_map (list) – Hierarchical identifier for parameters.

Returns

Return type

list of Quantity

get_parameters_scaled(opt_map=None) → numpy.ndarray

Return the current parameters. This fuction should only be called by an optimizer. Are you an optimizer?

Parameters

opt_map (tuple) – Hierarchical identifier for parameters.

Returns

Return type

list of Quantity

load_values(init_point)

Load a previous parameter point to start the optimization from.

Parameters

init_point (str) – File location of the initial point

print_parameters(opt_map=None) → None

Print current parameters to stdout.

read_config(filepath: str) → None

Load a file and parse it to create a ParameterMap object.

Parameters

filepath (str) – Location of the configuration file

set_opt_map(opt_map) → None

Set the opt_map, i.e. which parameters will be optimized.

set_parameters(values: Union[List, numpy.ndarray], opt_map=None, extend_bounds=False) → None

Set the values in the original instruction class.

Parameters

• values (list) – List of parameter values. Can be nested, if a parameter is matrix valued.

• opt_map (list) – Corresponding identifiers for the parameter values.

• extend_bounds (bool) – If true bounds of quantity objects will be extended.

set_parameters_scaled(values: Union[tensorflow.python.framework.constant_op.constant, tensorflow.python.ops.variables.Variable], opt_map=None) → None

Set the values in the original instruction class. This fuction should only be called by an optimizer. Are you an optimizer?

Parameters

values (list) – List of parameter values. Matrix valued parameters need to be flattened.

store_values(path: str, optim_status=None) → None

Write current parameter values to file. Stores the numeric values, as well as the names in form of the opt_map and physical units. If an optim_status is given that will be used.

Parameters

• path (str) – Location of the resulting logfile.

• optim_status (dict) – Dictionary containing current parameters and goal function value.

str_parameters(opt_map: Optional[Union[List[List[Tuple[str]]], List[List[str]]]] = None) → str

Return a multi-line human-readable string of the optmization parameter names and current values.

Parameters

opt_map (list) – Optionally use only the specified parameters.

Returns

Parameters and their values

Return type

str

update_parameters()

write_config(filepath: str) → None

Write dictionary to a HJSON file.

Main module

Base script to run the C3 code from a main config file.

c3.main.run_cfg(cfg, opt_config_filename, debug=False)

Execute an optimization problem described in the cfg file.

Parameters

• cfg (Dict[str, Union[str, int, float]]) – Configuration file containing optimization options and information needed to completely setup the system and optimization problem.

• debug (bool, optional) – Skip running the actual optimization, by default False

Module contents

Subpackages

• Generator package
  • Submodules
  • Devices module
  • Generator module
  • Module contents
    • AWG
      • asdict
      • create_IQ
      • create_IQ_pwc
      • enable_drag
      • enable_drag_2
      • enable_pwc
      • get_I
      • get_Q
      • get_average_amp
      • log_shapes
    • Additive_Noise
      • get_noise
      • process
    • Crosstalk
      • process
    • DC_Noise
      • get_noise
    • DC_Offset
      • process
    • Device
      • asdict
      • calc_slice_num
      • create_ts
      • write_config
    • DigitalToAnalog
      • process
    • ExponentialIIR
      • step_response_function
    • Filter
      • process
    • FluxTuning
      • get_factor
      • get_freq
      • process
    • FluxTuningLinear
      • frequency
    • HighpassExponential
      • step_response_function
    • HighpassFilter
      • convolve
      • process
    • LO
      • process
    • LONoise
      • process
    • Mixer
      • process
    • Pink_Noise
      • get_noise
    • Readout
      • readout
    • Response
      • convolve
      • process
    • ResponseFFT
      • process
    • SkinEffectResponse
      • step_response_function
    • StepFuncFilter
      • process
      • step_response_function
    • VoltsToHertz
      • process
    • dev_reg_deco
    • Generator
      • asdict
      • fromdict
      • generate_signals
      • read_config
      • write_config
• Libraries package
  • Algorithms module
  • Chip module
  • Constants module
  • Envelopes module
  • Estimators module
  • Fidelities module
  • Hamiltonians module
  • Sampling module
  • Tasks module
  • Module contents
    • adaptive_scan
    • algo_reg_deco
    • cma_pre_lbfgs
    • cmaes
    • gcmaes
    • grid2D
    • lbfgs
    • lbfgs_grad_free
    • oneplusone
    • single_eval
    • sweep
    • tf_adadelta
    • tf_adam
    • tf_rmsprop
    • tf_sgd
    • CShuntFluxQubit
      • get_Hamiltonian
      • get_anharmonicity
      • get_freq
      • get_frequency
      • get_minimum_phi_var
      • get_potential_function
      • get_third_order_prefactor
      • init_Hs
    • CShuntFluxQubitCos
      • cosm
      • get_Hamiltonian
      • get_freq
      • get_n_variable
      • get_phase_variable
      • init_Hs
      • init_exponentiated_vars
    • Coupling
      • get_Hamiltonian
      • init_Hs
    • Drive
      • get_Hamiltonian
      • init_Hs
    • Fluxonium
      • get_potential_function
    • LineComponent
      • asdict
    • PhysicalComponent
      • asdict
      • get_Hamiltonian
      • get_transformed_hamiltonians
      • set_subspace_index
    • Qubit
      • get_Hamiltonian
      • get_Lindbladian
      • init_Hs
      • init_Ls
    • Resonator
      • get_Hamiltonian
      • get_Lindbladian
      • init_Hs
      • init_Ls
    • SNAIL
      • get_Hamiltonian
      • init_Hs
    • Transmon
      • get_Hamiltonian
      • get_Lindbladian
      • get_anhar
      • get_factor
      • get_freq
      • init_Hs
      • init_Ls
    • TransmonExpanded
      • energies_from_frequencies
      • get_Hamiltonian
      • get_Hs
      • get_prefactors
      • init_Hs
    • dev_reg_deco
    • cosine
    • cosine_flattop
    • delta_pulse
    • drag_der
    • drag_sigma
    • env_reg_deco
    • flattop
    • flattop_cut
    • flattop_cut_center
    • flattop_risefall
    • flattop_risefall_1ns
    • flattop_variant
    • fourier_cos
    • fourier_sin
    • gaussian_der
    • gaussian_der_nonorm
    • gaussian_nonorm
    • gaussian_sigma
    • no_drive
    • pwc
    • pwc_shape
    • pwc_shape_plateau
    • pwc_symmetric
    • rect
    • slepian_fourier
    • trapezoid
    • dv_g_LL_prime
    • estimator_reg_deco
    • g_LL_prime
    • g_LL_prime_combined
    • mean_dist
    • mean_exp_stds_dist
    • mean_sim_stds_dist
    • median_dist
    • neg_loglkh_binom
    • neg_loglkh_binom_norm
    • neg_loglkh_gauss
    • neg_loglkh_gauss_norm
    • neg_loglkh_gauss_norm_sum
    • neg_loglkh_multinom
    • neg_loglkh_multinom_norm
    • rms_dist
    • rms_exp_stds_dist
    • rms_sim_stds_dist
    • std_of_diffs
    • RB
    • average_infid
    • average_infid_seq
    • average_infid_set
    • epc_analytical
    • fid_reg_deco
    • leakage_RB
    • lindbladian_RB_left
    • lindbladian_RB_right
    • lindbladian_average_infid
    • lindbladian_average_infid_set
    • lindbladian_epc_analytical
    • lindbladian_population
    • lindbladian_unitary_infid
    • lindbladian_unitary_infid_set
    • open_system_deco
    • orbit_infid
    • population
    • populations
    • set_deco
    • state_deco
    • state_transfer_infid
    • state_transfer_infid_set
    • unitary_deco
    • unitary_infid
    • unitary_infid_set
    • duffing
    • hamiltonian_reg_deco
    • int_XX
    • int_YY
    • resonator
    • third_order
    • x_drive
    • y_drive
    • z_drive
    • all
    • even
    • even_fid
    • from_end
    • from_start
    • high_std
    • random_sample
    • sampling_reg_deco
    • ConfusionMatrix
      • confuse
    • InitialiseGround
      • initialise
    • MeasurementRescale
      • rescale
    • Task
    • task_deco
• Optimizers
  • C1 - Optimal control
  • C2 - Calibration
  • C3 - Characterization
  • Optimizer module
  • Sensitivity analysis
  • Module contents
    • OptimalControl
      • goal_run
      • load_model_parameters
      • log_setup
      • optimize_controls
      • set_callback_fids
      • set_fid_func
    • Calibration
      • goal_run
      • log_pickle
      • log_setup
      • optimize_controls
      • set_eval_func
    • ModelLearning
      • confirm
      • goal_run
      • goal_run_with_grad
      • learn_model
      • log_setup
      • read_data
      • select_from_data
    • BaseLogger
      • log_parameters
      • start_log
    • BestPointLogger
    • Optimizer
      • end_log
      • fct_to_min
      • fct_to_min_autograd
      • goal_run
      • goal_run_with_grad
      • load_best
      • log_best_unitary
      • log_parameters
      • lookup_gradient
      • replace_logdir
      • set_algorithm
      • set_created_by
      • set_exp
      • start_log
    • TensorBoardLogger
      • log_parameters
      • set_logdir
      • start_log
      • write_params
    • Sensitivity
      • sensitivity
• Signal package
  • Submodules
  • Gates module
  • Pulse module
  • Module contents
    • Instruction
      • comps
      • Example
      • add_component
      • as_openqasm
      • asdict
      • auto_adjust_t_end
      • from_dict
      • get_awg_signal
      • get_full_gate_length
      • get_ideal_gate
      • get_key
      • get_optimizable_parameters
      • get_timings
      • quick_setup
    • Carrier
      • write_config
    • Envelope
      • asdict
      • get_shape_values
      • write_config
    • EnvelopeNetZero
      • get_shape_values
    • comp_reg_deco
• Utilities package
  • Qutip utilities module
  • Tensorflow utilities module
  • Log Reader utilities module
  • Miscellaneous utilities module
  • Module contents
    • T1_sequence
    • basis
    • expand_dims
    • get_basis_matrices
    • hilbert_space_kron
    • insert_mat_kron
    • inverseC
    • kron_ids
    • np_kron_n
    • pad_matrix
    • pauli_basis
    • perfect_cliffords
    • perfect_parametric_gate
    • perfect_single_q_parametric_gate
    • projector
    • ramsey_echo_sequence
    • ramsey_sequence
    • rotation
    • single_length_RB
    • two_qubit_gate_tomography
    • xy_basis
    • Id_like
    • get_tf_log_level
    • set_tf_log_level
    • super_to_choi
    • tf_abs
    • tf_abs_squared
    • tf_ave
    • tf_average_fidelity
    • tf_choi_to_chi
    • tf_convolve
    • tf_diff
    • tf_dm_to_vec
    • tf_dmdm_fid
    • tf_dmket_fid
    • tf_ketket_fid
    • tf_kron
    • tf_limit_gpu_memory
    • tf_list_avail_devices
    • tf_log10
    • tf_log_level_info
    • tf_matmul_left
    • tf_matmul_n
    • tf_matmul_right
    • tf_measure_operator
    • tf_project_to_comp
    • tf_setup
    • tf_spost
    • tf_spre
    • tf_state_to_dm
    • tf_super
    • tf_super_to_fid
    • tf_superoper_average_fidelity
    • tf_superoper_unitary_overlap
    • tf_unitary_overlap
    • tf_vec_to_dm
    • show_table
    • ask_yn
    • deprecated
    • eng_num
    • flatten
    • log_setup
    • num3str
    • replace_symlink
• Qiskit modules for C3
  • C3 Backend module
  • C3 Provider module
  • C3 Job module
  • C3 Exceptions module
  • C3 Backend Utilities module
  • Module contents
    • C3QasmPerfectSimulator
      • DEFAULT_OPTIONS
      • MAX_QUBITS_MEMORY
      • run_experiment
    • C3QasmPhysicsSimulator
      • DEFAULT_OPTIONS
      • MAX_QUBITS_MEMORY
      • run_experiment
    • C3QasmSimulator
      • disable_flip_labels
      • get_labels
      • run
      • run_experiment
      • set_device_config
    • C3Provider
      • backends
    • C3Job
      • result
      • status
      • submit
    • C3QiskitError
    • flip_labels
    • get_init_ground_state
    • get_sequence
    • make_gate_str