# API Documentation¶

## C3objs¶

Basic custom objects.

class c3.c3objs.C3obj(name: str, desc: str = ' ', comment: str = ' ')[source]

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

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

list_parameters()[source]
Returns

A list of parameters this object has.

Return type

list

params: dict
print_parameter(par_id)[source]

Print a given parameter.

Parameters

par_id (str) – Parameter identifier

class c3.c3objs.Quantity(value, min, max, symbol: str = '\\alpha', unit: str = 'unspecified')[source]

Bases: object

Represents any physical quantity used in the model or the pulse speficiation. 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 (np.array(np.float64) or np.float64) – minimum this quantity is allowed to take

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

• symbol (str) – latex representation

• unit (str) – physical unit

get_opt_value()[source]

Get an optimizer friendly representation of the value.

get_value(val=None)[source]

Return the value of this quantity as tensorflow.

Parameters

val (tf.float64) – Optionaly give an optimizer friendly value between -1 and 1 to convert to physical scale.

numpy()[source]

Return the value of this quantity as numpy.

set_opt_value(val)[source]

Set value optimizer friendly.

Parameters

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

set_value(val)[source]

Set the value of this quantity as tensorflow. Value needs to be within specified min and max.

## 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(model=None, generator=None, gateset=None)[source]

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
• 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.

evaluate(seqs)[source]

Compute the population values for a given sequence of operations.

Parameters

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

Returns

A list of populations

Return type

list

get_gates()[source]

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

get_parameters(opt_map=None, scaled=False)[source]

Return the current parameters.

Parameters
• opt_map (tuple) – Hierarchical identifier for parameters.

• scaled (boolean) – If true, return the optimizer friendly version. See Quantity.

plot_dynamics(psi_init, seq, goal=- 1, debug=False)[source]

Plotting code for time-resolved populations.

Parameters
• psi_init (tf.Tensor) – Initial state or density matrix.

• seq (list) – List of operations to apply to the initial state.

• goal (tf.float64) – Value of the goal function, if used.

• debug (boolean) – If true, return a matplotlib figure instead of saving.

plot_pulses(instr, goal=- 1, debug=False)[source]

Plotting of pulse shapes.

Parameters
• instr (str) – Identifier of the current instruction.

• goal (tf.float64) – Value of the goal function, if used.

• debug (boolean) – If true, return a matplotlib figure instead of saving.

populations(state, lindbladian)[source]

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

print_parameters(opt_map=None)[source]

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

Parameters

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

process(populations, labels=None)[source]

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

propagation(signal: dict, ts, gate)[source]

Solve the equation of motion (Lindblad or Schrödinger) for a given control signal and Hamiltonians.

Parameters
• signal (dict) – Waveform of the control signal per drive line.

• ts (tf.float64) – Vector of times.

• gate (str) – Identifier for one of the gates.

Returns

Matrix representation of the gate.

Return type

unitary

set_enable_dynamics_plots(flag, logdir)[source]

Plotting of time-resolved populations.

Parameters
• flag (boolean) – Enable or disable plotting.

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

set_enable_pules_plots(flag, logdir)[source]

Plotting of pulse shapes.

Parameters
• flag (boolean) – Enable or disable plotting.

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

set_enable_store_unitaries(flag, logdir)[source]

Saving of unitary propagators.

Parameters
• flag (boolean) – Enable or disable saving.

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

set_opt_gates(opt_gates)[source]

Specify a selection of gates to be computed.

Parameters

opt_gates (Identifiers of the gates of interest.) –

set_parameters(values: list, opt_map: list, scaled=False)[source]

Set the values in the original instruction class.

Parameters
• values (list) – List of parameter values.

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

store_Udict(goal)[source]

Save unitary as text and pickle.

goal: tf.float64

Value of the goal function, if used.

write_config()[source]

Return the current experiment as a JSON compatible dict.

EXPERIMENTAL