Qcodes

==========================

**NOTE**: this release includes changes from :doc:`0.35.0b1`,
refer to that changelog for details of those changes.

In this release a large refactoring of the QCoDeS modules organization has taken place.
Among other changes the ``instrument`` module has been split into a ``parameters`` and
``instrument`` module, the ``dond`` functions have been moved to the ``dataset`` module
and several methods removed from the public API of the ``utils`` module.

The new API is documented in the :ref:`api` section of the QCoDeS homepage.

Going forward we aim to establish a policy where the QCoDeS public API is defined
by modules explicitly documented in the :ref:`api` and importable from submodules at most
one level deep. I.e. ``from qcodes.instrument import InstrumentChannel`` is supported but
``f`rom qcodes.instrument.channel import InstrumentChannel`` is considered unsupported.

Importing from previously existing locations should continue to work
but it is recommended to update to the new API.
In the future we may deprecate and eventually remove these modules
but no firm date is set for this.

Please report any issues you may see with importing from the previously existing API
or if you depend on any functions, classes etc. not available from the new public API.

This release also includes a significant but still incomplete refactoring of the QCoDeS
instrument drivers in ``qcodes.instrument_drivers``. Many but not all drivers have been updated
to use names that conform to the standard documented
`here <../examples/writing_drivers/Creating-Instrument-Drivers.ipynbNaming-the-Instrument-class>`__
i.e. they use CamelCase as other classes and are named as ``InstrumentvendorModel``
and are importable directly from the instrument vendor module i.e.
``from qcodes.instrument_drivers.AimTTi import AimTTiPL068P`` .
Older names for the classes are still importable from their original places unless explicitly
documented otherwise. In the future we may deprecate and eventually remove the instrument driver classes whos names don't conform to the standard,
but no firm date is set for this.

Breaking Changes:
-----------------

- The standard metadata as defined by pep621 has moved from setup.cfg
to pyproject.toml. This should have no user facing consequences unless
you install qcodes from source using a very old version of pip (<19)
or use unusual pip configurations. (4382)
- :class:`VisaInstrument` no longer calls :meth:`VisaInstrument.set_address` as part of its
initialization. If you customize :meth:`VisaInstrument.set_address` in a subclass you may have
to adapt that class. (:pr:`4397`)
- The deprecated method check_error has been removed from the visa instrument class. (4426)
- The unused attribute shared_kwargs on the ``Instrument`` class has been removed. (4427)
- The following ``InstrumentChannel`` classes have changed name for consistency.
This is expected to be a change with few user facing implications unless you are explicitly
subclassing the mentioned classes.

* ``DG1062Burst`` has changed name to ``RigolDG1062Burst``
* ``DG1062Channel`` has changed name to ``RigolDG1062Channel`` (4538)
- ``DataSet.get_metadata`` method for retrieving a metadata value for a
given tag is now case-sensitive with respect to the tag.
For example, if metadata was added with ``dataset.add_metadata('something', 1)``,
it can only be retrieved by using its exact casing of the tag,
``dataset.get_metadata('something')``, and not e.g.
``dataset.get_metadata('SomeThinG')``. In the previous versions of QCoDeS,
any casing of the tag in ``DataSet.get_metadata`` would work and return the
value stored under that tag. Note that this change brings consistency
with how getting metadata via the ``dataset.metadata`` works:
``dataset.metadata['something']`` does return the value, and
``dataset.metadata['SomeThinG']`` does not. (4658)


Improved:
---------

- ``ChannelTuple`` and ``ChannelList`` has gained the ability to call methods defined on the channels
in the sequence in a way similar to how QCoDeS Functions can be called. (4292)
- ``dond`` has gained the ability to sweep multiple parameters at the same time enabling the creation of more complex
measurements. (4325)
- Improve performance of ``sqlite3`` converters and adapters used to write and read in the database.

Get rid of ``sqlite3.Row`` and irrelevant unpacking to ``list``. (4446)
- Settings of QCoDeS Validators are now available as properties (mostly read-only),
e.g. ``min_value`` and ``max_value`` of the ``Numbers`` validator can now be accessed
via ``numbers_validator_instance.min_value`` and ``numbers_validator_instance.max_value`` (4602)
- Fixed a bug in the QCoDeS JSON encoder that would trigger an infinite recursion for snapshots containing
bytes (bytestrings with a b prefix). (4621)
- InstrumentBase and ParameterBase now call snapshot() on _meta_attrs attributes that inherit from Metadatable. (4655)
- The Dataset no longer prints upgrade progressbars when upgrading an empty database. This means that
the progressbar will no longer be shown when creating a new database. (4969)


Improved Drivers:
-----------------

- A parameter `auto_freq_ref` was added to the `Keysight.N51x1` class.
From the Keysight manual:
This command enables or disables the ability of the signal generator to
automatically select between the internal and an external reference oscillator.

In addition, the val_mapping dictionary of the `rf_output` parameter is now using the `create_on_off_val_mapping` function. (4472)
- Add ``get_idn`` to AMI 430 3D virtual instrument driver so that it does not raise a warning when added to a station (4610)

New:
----

- :class:`InstrumentBase` has a property ``label`` that can host
a human-readable label/title of the instrument.
The label can be set in the __init__. (4460)

============================

This is a beta release of the upcoming QCoDeS 0.35.0 release.

In this release a large refactoring of the QCoDeS modules organization has taken place.
Among other changes the `instrument` module has been split into a `parameters` and
`instrument` module, the `dond` functions have been moved to the `dataset` module
and several methods removed from the public API of the `utils` module.

The new API is documented in the :ref:`api` section of the QCoDeS homepage.

Going forward we aim to establish a policy where the QCoDeS public API is defined
by modules explicitly documented in the :ref:`api` and importable from submodules at most
one level deep. I.e. `from qcodes.instrument import InstrumentChannel` is supported but
`from qcodes.instrument.channel import InstrumentChannel` is considered unsupported.

Importing from previously existing locations should continue to work
but it is recommended to update to the new API.
In the future we may deprecate and eventually remove these modules
but no firm date is set for this.

Please report any issues you may see with importing from the previously existing API
or if you depend on any functions, classes etc. not available from the new public API.

Breaking Changes:
-----------------

- Removed deprecated units property from `DataArray`. (4358)
- Removed deprecated ``qcodes.version`` module. Use ``qcodes.__version__`` (4307)

Improved:
---------

- :func:`qcodes.dataset.doNd` now logs more information about how parameters are
unpacked and grouped making it easier to debug. (4288)
- do_nd: save plot with 'tight' bbox to prevent tick marks with long labels
pusing out the axis label out of the canvas window and not visible (4360)
- Significant refactor of internal modules and public API (4357, 4355,
4353, 4351, 4350, 4349, 4348, 4334, 4330,
4326, 4316, 4309, 4307, 4306, 4300, 4294,
4286, 4283, 4275, 4274, 4272, 4266, 4237,
4224, 3972, 4265, 3536)
- Fixed bug in fallback code for Sphinx extension breaking documentation of certain attributes (4223)

New Drivers:
------------

- Add Keithley 2634B model to 2600 driver (4290)


Improved Drivers:
-----------------

- The Keysight N52 series drivers have gained a parameter to control RF output. (4301)
- Improved Keysight N51x1 driver: make frequency option detection compatible with multiple options installed on device. (4342)

==========================

Breaking Changes:
-----------------

- Restrictions on instrument names are now less strict than in ``0.34.0``. Submodules are allowed
to have names that are not valid identifier as long as the full name is an valid identifier. (4257)

Breaking Changes:
-----------------

- The deprecated driver for ZI UHFLI has been removed. Please use the drivers provided by `zhinst-qcodes`. (4081)
- InstrumentBase class now raises error if name is an invalid identifier.
This effects creation of instruments, channels, modules. (4178)
- The deprecated fallback for visa addresses containing an ` and the backend has been removed. (4219)
- QCoDeS no longer explicitly sets the read and write terminators to `""` (The empty string) by default.
The default terminators are now set by PyVISA. This should only have implications for RS232 instruments where
the default read and write terminators now are ``\r``. (4219)


New:
----

- The QCoDeS instrument baseclass has gained a method `invalidate_cache`.
This will mark the cache of all parameters on the instrument and its submodules as
invalid. This is useful if you manually (e.g. via the front panel) make changes to
the instrument that QCoDeS cannot know about. (4161`)


Improved:
---------

- Improved conversion between `qcodes.data.data_set.DataSet` and `xarray`. The conversion from `xarray` format to QCoDeS is more robust in reordering the coordinates.
The dataset attributes `label` and `unit` are now converted as well. (4011`)


Improved Drivers:
-----------------

- Fixed issue 4121 of setting the mode of the Keithley 6500 by adding single quotes around the mode value in the set_cmd string. (4122)
- Add db/phase sweep parameter for rohde_schwarz ZNB driver (4139)
- Add polar parameter to Keysight PNA to fetch the data using the polar format.
This reduces the measurement time; instead of pulling magnitude and phase separately,
we now get all complex data points in a single trace. (4182)

New:
----

- Added a function ``qcodes.dataset.get_guids_by_run_spec`` to look up dataset guids
from run specficiations. This replaces the now deprecated semi-public method
``get_guids_from_run_spec``. It has a better handling of connections and more filtering options matching
``load_by_run_spec``. (3863)
- A new set of validators ``MultiTypeAnd`` and ``MultiTypeOr`` that allows combination of
other validators with And and Or were added. For backwards compatibility the existing
``MultiType`` validator takes a ``combiner`` argument defaulting to Or. (3917)


Improved:
---------

- Fixed a typo in legacy PyqtGraph plot preventing correct handling of custom units.
Regression from 0.32.0 (3773)
- The warning triggered when a parameter is added to the snapshot incorrectly has been improved to include the
name of the full instrument and two levels of stack information. This should make it easier to find the
problematic parameter. (3884)
- Development versions of QCoDeS are now formatted as
``{version}.dev{distance}+{branch}{vcs}{rev}.dirty``
e.g. ``0.32.0.dev14+name.of.branch.gxxxxx(.dirty)``
rather than "{version}+{distance}.{vcs}{rev}". This is
done since pip in some cases considers the later equal to the released
version and include more info to let you easily identify the
branch installed from. Note that due to limitations in characters
in version numbers `/_-` are normalized to `.` e.g. a branch named
``myname/my_branch-name`` becomes `myname.my.branch.name` in the
version number. (3890)
- ``ChannelTuple`` now has a repr that correctly identifies it as a ``ChannelTuple``
and not a ``ChannelList`` (3911)
- ``Parameter.unit`` is now a settable property rather than an attribute.
This should have few implications for user facing code but makes it possible
to do the same in a parameter subclass implementing validation or other functionality
as needed. (3929)
- Metadata added after ``DataSet`` ``export`` to a netcdf file is now also added
to that exported netcdf file (unless the exported netcdf file has been moved
to a new location and ``set_netcdf_location`` was not called with that new
location of the file) (3932)
- In the interactive widget the total time of a run is now correctly calculated as
end-time - start-time not the other way around. (3944)
- Loading a 2 or higher dimentional qcodes dataset back from a netcdf file has been corrected to
show the dataset in the correct shape.
QCoDeS dataset are now always written to netcdf files from the cache with the same order of axis as in memory. (3945)
- Datasets now correctly preserve the shape information when exported to another database. (3956)
- Functions and classes marked deprecated with the QCoDes Deprecation decorator will now trigger
warnings that reflect where they are called from and not the location of the deprecation decorator. (3959)


Improved Drivers:
-----------------

- AMI430 3D magnet power supply driver: restore ramp rates of individual magnet
axes after simultaneous ramp via calling ``wait_while_all_axes_ramping`` or
automatically if ``block_during_ramp`` is ``True``. (3885)
- Update the Keysight Infiniium oscilloscope driver to use ParameterWithSetpoints and also make the driver
work without needing to run prepare_curvedata before measurement. Measurement subsystem is updated to be
channel aware so it is possible to run measurements on multiple channels in a single qcodes measurement.
For multiple traces, added the option to control automatic sweeping, similar to the N52xx driver. We can
now take data from multiple channels with a single digitize. (3916)
- Fix baud rate of QDevil and QDev QDac's to be 460800 (3931)
- The Zurich instrument driver stubs in ``qcodes.instrument_drivers.zurich_instruments`` have been updated
to use the 0.3 version of ``zhinst-qcodes`` (3969)
- Fixed a typo that prevented initialization of Agilent 34400A (3981)

Breaking Changes:
-----------------

- The ``qcodes.version`` module deprecated and no longer imported by default e.g. if you want to use it you will need
to explicitly import ``qcodes.version``. It is recommended to use ``qcodes.__version__`` as an alternative. (3762)
- IPython measurement magic (Special command staring with % for use in IPython) using the legacy
loop is no longer enabled by default.
To enable it set the corresponding config value (`core.register_magic`) in your ``qcodesrc.json`` config file to true. (3764)
- The ``import_legacy_api`` config option has been deprecated and will be removed in a future release. (3781)


New:
----

- An abstract instrument (An instrument with one or more abstract parameters) will now raise at
instrument creation time preventing such an instrument from being created.
This makes it easier to define interfaces that multiple instruments must implement.
See `here <../examples/writing_drivers/abstract_instruments.ipynb>`__ for examples of how to use
this. (3718)
- Improve the Keithley 2600 SMU calibration routine and make it
a standalone executable function (3783)
- Add ``ArraySweep`` sweep class for use with ``dond`` function
for sweeping parameters on arbitrary arrays of values (3847)
- The instrument channel container ``ChannelList`` has been split into a immutable ``ChannelTuple``
and a mutable ``ChannelList``. The ``ChannelList`` class has gained a ``to_channel_tuple`` method.
The ``lock`` method which locks a ``ChannelList`` has been retained but we do expect to deprecate
this in the future.

All drivers in QCoDeS have been updated to either use a ``ChannelTuple`` or a unlocked
``ChannelList`` as it makes sense.

Furthermore, the ``ChannelList`` class now implements the full
``collections.abc.MutableSequence`` interface behaving like a python list. (3851)


Improved:
---------

- Only register an Instrument in the list of connected instruments if the connection
was successful. This change allows connections to be retried with the same name
if the first attempt fails. (3696)
- Fixed a bug with ``import_legacy_api`` config option which would trigger a circular import error. (3781)
- Instances of ``InstrumentModule`` (and therfor their subclass ``InstrumentChannel``) are now accessible via
the ``Instrument.instrument_modules`` dict on an instrument in addition to the ``Instrument.submodules`` dict
which combines them with instances of ``ChannelList``. (3834)
- ``ChannelList`` now implements the full ``collections.abc.Sequence`` interface.
This also means that ``isinstance(mychannelist, Sequence) is True`` (3835)
- Inserting into a ``ChannelList`` now correctly keeps the internal mapping up to date ensuring that
``get_channel_by_name`` works correctly. (3838)
- ``InstrumentChannel`` now subclasses a new class ``InstrumentModule`` to clarify that instrument modules may
serve other purposes than being channels. At the moment ``InstrumentModule`` and ``InstrumentChannel`` are identical.
The type hints have been updated to clarify that only subclasses of ``InstrumentModule`` and ``ChannelLists``
are allowed submodules. (3840)
- Empty ChannelTuples/Lists now correctly raise an attribute error when trying
to get a non existing attribute. Previously they would raise an IndexError. (3856)


Improved Drivers:
-----------------

- Changed the value mapping of channel_selection on the AlazarTech ATS9440
driver to fix all the combinations where channel D is involved. (3802)
- The VISA version of the AMI driver has been improved to more robustly handle flaky communication. (3833)
- Added a VISA version of the AMI430 driver. This is expected to be more robust with communication issues than the
IP version of the driver. This driver exists alongside the IP version as
``qcodes.instrument_drivers.american_magnetics.AMI430_visa.py::AMI430``. (3842)