Missing Documentation

Open lazyoracle opened this issue 4 years ago • 1 comments

This is a continuously updated issue to keep track of missing documentation in various parts of the code. Please update the Issue description or add a comment when you find a section of the code that is poorly documented or not intuitive to use or has some quirks that need to be flagged to the user/developer. Make sure you go through the points listed below before adding something new. (ref for writing good software docs here and here.

[x] How does one use evaluate() and process() as defined here? The Simulated_Calibration.ipynb is out of date and the other notebooks don't seem to use it. What all experiment parameters need to be set before running these two functions? (Updated Notebook with usage)
[x] Given an object of the Model class or e.g, a model config, how does one go about programmatically identifying the qubits (or the number of qubits) or identifying which qubits are coupled (or the couplings). It seems like these subsystems don't have different types. Are they all stored in an unstructured manner inside the Model datatype and there is no way to programmatically identify a qubit from a coupling except by the name Q1 and Q1-Q2? What would be the C3 preferred way to eg, get_num_of_qubits(), get_connected_qubits() and get_qubit_levels()?
[x] How is the average gate fidelity calculated and which of the several functions defined here do we need to use? Is there a naming convention or catalogue that better outlines what these functions do?
[x] Regarding gate definition. In quickstart.hjson, we define single_qubit_gates between Q1 and Q2 as "X90p:Id" and two_qubit_gates as CR90. The system model that this quick-start uses also has couplings for Q4-Q6, how would one go about defining that gate, either single qubit or 2 qubit? Since all these gates seem to be only discriminated by their name, its not immediately clear how to have two qubit gates defined simultaneously between Q1-Q2 and Q4-Q6. Also, are the quotes for the gate names required or not? (Pending restructuring of gate names, qubits and indices)
[x] exp.get_gates() - What is the expected usage of this function? Where do I use the output of this function? Is it just a proxy to call exp.propagation()?
[x] How and when are the dUs created? Do I need to run exp.get_gates() for the dUs
[x] Docs and example notebooks dont explain the C3 style vs Qiskit style qubit state labelling and how to use both when working with the C3-Qiskit interface
[ ] Missing updated documentation on parameters for instantiating Transmon class objects - https://github.com/q-optimize/c3/blob/7b1ccc44f1f8d423e01a2a4967b41f81e6684b1b/c3/libraries/chip.py#L289-L302
[x] #73 (update example notebook in docs)
[x] #91 (missing notebook for Model Learning)
[x] Missing Introductory Section explaining what the different parts of codebase encapsulate and how they work together (fixed in #110 )
[x] #121 (missing notebooks and docs)
[ ] Create an FAQ or wiki from various questions and discussions in internal user chat
[x] Missing docstrings and examples for usage of command line tools, eg, the log reader. #151
[x] Missing notebook for Entangling Gate Optimization (closed in #157)
[x] Compatibility with qasm style gates both through the qiskit interface and otherwise (closed in #165)
[ ] Setting a seed for reproducible simulations

Jan 22 '21 04:01 lazyoracle

Current missing documentation, obtained using $ docstr-coverage -i -m --verbose=2 c3/

File: "/home/users/anurag/dev/c3/c3/__init__.py"
 Needed: 1; Found: 0; Missing: 1; Coverage: 0.0%


File: "/home/users/anurag/dev/c3/c3/c3objs.py"
 Needed: 19; Found: 10; Missing: 9; Coverage: 52.6%


File: "/home/users/anurag/dev/c3/c3/experiment.py"
 Needed: 24; Found: 23; Missing: 1; Coverage: 95.8%


File: "/home/users/anurag/dev/c3/c3/generator/devices.py"
 Needed: 66; Found: 46; Missing: 20; Coverage: 69.7%


File: "/home/users/anurag/dev/c3/c3/generator/generator.py"
 Needed: 8; Found: 6; Missing: 2; Coverage: 75.0%


File: "/home/users/anurag/dev/c3/c3/libraries/algorithms.py"
 Needed: 18; Found: 15; Missing: 3; Coverage: 83.3%


File: "/home/users/anurag/dev/c3/c3/libraries/chip.py"
 Needed: 61; Found: 26; Missing: 35; Coverage: 42.6%


File: "/home/users/anurag/dev/c3/c3/libraries/envelopes.py"
 Needed: 29; Found: 28; Missing: 1; Coverage: 96.6%


File: "/home/users/anurag/dev/c3/c3/libraries/estimators.py"
 Needed: 20; Found: 17; Missing: 3; Coverage: 85.0%


File: "/home/users/anurag/dev/c3/c3/libraries/fidelities.py"
 Needed: 30; Found: 17; Missing: 13; Coverage: 56.7%


File: "/home/users/anurag/dev/c3/c3/libraries/propagation.py"
 Needed: 10; Found: 8; Missing: 2; Coverage: 80.0%


File: "/home/users/anurag/dev/c3/c3/libraries/tasks.py"
 Needed: 9; Found: 8; Missing: 1; Coverage: 88.9%


File: "/home/users/anurag/dev/c3/c3/model.py"
 Needed: 32; Found: 20; Missing: 12; Coverage: 62.5%


File: "/home/users/anurag/dev/c3/c3/optimizers/modellearning.py"
 Needed: 11; Found: 9; Missing: 2; Coverage: 81.8%


File: "/home/users/anurag/dev/c3/c3/optimizers/optimalcontrol.py"
 Needed: 8; Found: 5; Missing: 3; Coverage: 62.5%


File: "/home/users/anurag/dev/c3/c3/optimizers/optimalcontrol_robust.py"
 Needed: 4; Found: 2; Missing: 2; Coverage: 50.0%


File: "/home/users/anurag/dev/c3/c3/optimizers/optimizer.py"
 Needed: 25; Found: 13; Missing: 12; Coverage: 52.0%


File: "/home/users/anurag/dev/c3/c3/parametermap.py"
 Needed: 26; Found: 20; Missing: 6; Coverage: 76.9%


File: "/home/users/anurag/dev/c3/c3/qiskit/__init__.py"
 Needed: 1; Found: 0; Missing: 1; Coverage: 0.0%


File: "/home/users/anurag/dev/c3/c3/qiskit/c3_backend.py"
 Needed: 19; Found: 14; Missing: 5; Coverage: 73.7%


File: "/home/users/anurag/dev/c3/c3/qiskit/c3_job.py"
 Needed: 5; Found: 4; Missing: 1; Coverage: 80.0%


File: "/home/users/anurag/dev/c3/c3/qiskit/c3_provider.py"
 Needed: 5; Found: 4; Missing: 1; Coverage: 80.0%


File: "/home/users/anurag/dev/c3/c3/signal/gates.py"
 Needed: 14; Found: 3; Missing: 11; Coverage: 21.4%


File: "/home/users/anurag/dev/c3/c3/signal/pulse.py"
 Needed: 10; Found: 8; Missing: 2; Coverage: 80.0%


File: "/home/users/anurag/dev/c3/c3/utils/log_reader.py"
 Needed: 2; Found: 1; Missing: 1; Coverage: 50.0%


File: "/home/users/anurag/dev/c3/c3/utils/tf_utils.py"
 Needed: 36; Found: 34; Missing: 2; Coverage: 94.4%


File: "/home/users/anurag/dev/c3/c3/utils/utils.py"
 Needed: 10; Found: 8; Missing: 2; Coverage: 80.0%


Overall statistics for 41 files (5 files are empty) (skipped all non-init magic methods) (skipped __init__ methods):
Needed: 564  -  Found: 410  -  Missing: 154
Total coverage: 72.7%  -  Grade: Very good

Feb 01 '21 11:02 lazyoracle