Implement a builder-like constructor for Target

[raynelfss]

Summary

In an oversight during #14228, we forgot to expose the Target::new() method to the rest of the crate. The following commits expose a Rust native Target::new() as well as some other methods which enable us to construct the Target using a builder-like architecture.

Details

The following commits add a rust native constructor for the Target that uses a builder-like architecture to add all of the specified attributes in a more dynamic manner.

// To create a target with a specified description and number of qubits:
let sydney_target: Target = Target::new()
    .with_description("Sydney-Target")
    .with_num_qubits(4)
    .unwrap();

// To create a target with a specific dt value:
let seoul_target: Target = Target::new()
    .with_dt(10e-9)
    .unwrap();

The methods include the following:

• new - Rust native constructor, must be called before using any builder methods. Equivalent to Default::default().
• with_description - To create a target with a specific description.
• with_num_qubits - (Fallible) Assigns an explicit number of qubits to the Target, may fail if the specified qubit_properties list length differs from the value of this number.
• with_dt - Assigns the dt value.
• with_granularity - Assigns a granularity value in units of dt.
• with_min_length - Assigns a minimal pulse length in units of dt.
• with_pulse_alignment - Assigns a gate instruction starting time.
• with_acquire_alignment - Assigns a measure instruction starting time.
• with_qubit_properties - (Fallible) Specifies the properties of each of the backend's qubits, if associated. May fail if the specified qubit_properties list length differs from the value of num_qubits.
• with_concurrent_measurements - Specifies which qubits need to be measured together.

[qiskit-bot]

One or more of the following people are relevant to this code:

• @Qiskit/terra-core

[jakelishman]

Rust doesn't have keyword arguments, so a new method that's 8 Option<T>s long perhaps isn't the cleanest user interface. Perhaps a builder-like interface would be cleaner?

let mut target = Target::new()
    .with_description("target")
    .with_num_qubits(4)
    .with_dt(10e-9);

or such?

[coveralls]

Pull Request Test Coverage Report for Build 21005445683

Details

• 171 of 173 (98.84%) changed or added relevant lines in 4 files are covered.
• 19 unchanged lines in 3 files lost coverage.
• Overall coverage increased (+0.003%) to 88.32%

---

Changes Missing Coverage	Covered Lines	Changed/Added Lines	%
crates/transpiler/src/target/mod.rs	165	167	98.8%

Files with Coverage Reduction	New Missed Lines	%
crates/qasm2/src/lex.rs	3	92.54%
crates/circuit/src/parameter/symbol_expr.rs	4	72.98%
crates/qasm2/src/parse.rs	12	96.62%

Totals
Change from base Build 21005190367:	0.003%
Covered Lines:	97056
Relevant Lines:	109891

---

💛 - Coveralls

[raynelfss]

Out of curiosity, would it be easier to just have the constructor setter methods for num_qubits and qubit_properties (or have them together as one method), and allow the user to edit the rest of the values (dt, minimal_length, granularity pulse_alignment, acquire_alignment and concurrent_measurements)? Since all of these attributes are public and the only ones that are fallible are num_qubits and qubit_properties in respect to each other values, it would make sense to allow the users to do something like:

let mut target = Target::new().try_with_num_qubits(5)?.try_with_qubit_properties(vec![])?;
target.dt = Some(10e-9);
target.min_length = 2;

[mtreinish]

Is this actually a thing we should have in the rust builder api? It doesn't seem like it's something we'll ever define in Rust while it's a PyObject.

[raynelfss]

Not until we have qubit properties in Rust. We may want to have this ready as a placeholder though.

[mtreinish]

Do we have an issue tracking the move of qubit properties to rust?

[raynelfss]

Yes #14306

[mtreinish]

Is this correct? In sphinx-napoleon/google style which we use for qiskit it should be Returns:. See:https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html

[raynelfss]

Will change it back to Returns:

[mtreinish]

Given the timeframe and that this is a good to have internal usability thing I deferred this 2.2 to minimize the risk to 2.1.

[Cryoris]

Basically the same reason to defer to 2.4 given that we're 2 days off RC1:

Given the timeframe and that this is a good to have internal usability thing I deferred this 2.2 to minimize the risk to 2.1.