Merged dev-4-2-0-rc branch

CHANGELOG.md

@@ -1,3 +1,20 @@
+# 4.2.0 (2023/04/03)
+
+- Added support for choosing between multiple approaches to suggesting the regularization parameter (lambda) in DRT methods utilizing Tikhonov regularization.
+- Added a `Data set palette` for searching and selecting data sets via a window similar to the `Command palette`.
+- Added a `Result palette` for searching and selecting various results (depending on the context) via a window similar to the `Command palette`.
+- Added an `Add parallel impedance` window, which is accessible via the `Process` button in the `Data sets` tab. This is useful for, e.g., Kramers-Kronig testing impedance data that include negative differential resistances.
+- Updated the table of fitted parameters in the `Fitting` tab to highlight parameters with large estimated errors.
+- Updated the table of statistics in the `Fitting` tab to highlight values that may be indicative of issues.
+- Updated tooltips.
+- Refactored code.
+- Fixed a bug that caused two click of the `Accept` button in the `Subtract impedance` window after opening and closing the circuit editor.
+- Fixed a bug that caused an exception when opening and closing the circuit editor in the `Subtract impedance` window two or more times in a row.
+- Fixed a bug where loading a simulation result as a data set would also cause the `Simulation` tab to switch to the latest simulation result.
+- Fixed a mistake in the docstring of the DRTResult class.
+- Possibly fixed a bug where resizing signals could sometimes cause an exception to occur while launching the program.
+
+
 # 4.1.0 (2023/03/22)
 
 - Added a `Copy` button next to the fit results in the `Subtract impedance` window. This button can be used to copy a fitted circuit to the `Circuit` option above.

build.sh

@@ -1,4 +1,23 @@
 #!/bin/bash
+# DearEIS is licensed under the GPLv3 or later (https://www.gnu.org/licenses/gpl-3.0.html).
+# Copyright 2023 DearEIS developers
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <https://www.gnu.org/licenses/>.
+#
+# The licenses of DearEIS' dependencies and/or sources of portions of code are included in
+# the LICENSES folder.
+
 # Stop when a non-zero exit code is encountered
 set -e
 
@@ -85,6 +104,9 @@ python3 -m build
 # Validate the source and wheel distributions
 validate_tar
 validate_wheel
+if [ "$1" == "distros" ]; then
+	exit
+fi
 
 # Update documentation
 # - The contents of ./dist/html should be committed to the gh-pages branch

docs/source/conf.py

@@ -36,6 +36,10 @@
 autodoc_typehints = "description"
 autodoc_typehints_format = "short"
 
+plot_formats = ["svg", "pdf"]
+plot_html_show_formats = False
+plot_rcparams = {"savefig.transparent": True}
+
 
 def autodoc_skip_member_handler(app, what, name, obj, skip, options):
     module_string = str(getmodule(obj))

docs/source/guide.rst

@@ -22,5 +22,5 @@ Here are some quick guides to getting started with DearEIS.
    guide_plotting
    guide_batch
    guide_settings
-   guide_command_palette
+   guide_palettes
    guide_api

docs/source/guide_data.rst

@@ -46,7 +46,7 @@ Several different file formats are supported:
 Additional file formats may be supported in the future.
 
 Not all CSV files and spreadsheets are necessarily supported as-is but the parsing of those types of files should be quite flexible in terms of, e.g., the characters that are used as separators.
-The parsers expect to find at least a column with frequencies (Hz) and columns for either the real and imaginary parts of the impedance (ohm), or the absolute magnitude (ohm) and the phase angle/shift (degrees).
+The parsers expect to find at least a column with frequencies (Hz) and columns for either the real and imaginary parts of the impedance (|ohm|), or the absolute magnitude (|ohm|) and the phase angle/shift (degrees).
 The supported column headers are:
 
 - frequency: ``frequency``, ``freq``, or ``f``
@@ -104,7 +104,7 @@ If multiple data sets will need to have the same (or very similar) masks, then t
 Processing data sets
 --------------------
 
-DearEIS includes a few functions for processing data sets: averaging, interpolation, and subtraction.
+DearEIS includes a few functions for processing data sets: averaging, interpolation, addition of parallel impedances, and subtraction of impedances.
 All of these functions are available via the **Process** button that can be found above the table of data points (:numref:`data_tab`).
 The results of these functions are added to the project as a new data set (i.e., without getting rid of the original data set).
 
@@ -152,9 +152,54 @@ Alternatively, if the smoothing and interpolation cannot provide a reasonable re
 
     \clearpage
 
+.. _parallel impedances:
 
-Subtraction
-~~~~~~~~~~~
+Adding parallel impedances
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Impedance data that include negative differential resistances cannot be validated directly using the included implementations of linear Kramers-Kronig tests.
+Kramers-Kronig tests can be performed on such data either after transforming it into admittance data (not currently supported) or after adding a suitable parallel resistance to the impedance data.
+The addition of a parallel resistance does not affect the Kramers-Kronig compliance of the data.
+
+.. plot::
+   :alt: A circuit where the a parallel resistance, R, has been added to the original impedance data, Z.
+
+   from pyimpspec import parse_cdc
+   # A Warburg impedance is used here just to have two different symbols
+   circuit = parse_cdc("(WR)")
+   elements = circuit.get_elements()
+   custom_labels = {
+       elements[0]: r"$Z_{\rm data}$",
+       elements[1]: r"$R_{\rm par}$",
+   }
+   circuit.to_drawing(custom_labels=custom_labels).draw()
+
+
+The magnitude of the parallel resistance to add depends on the original impedance data.
+In the example below (:numref:`parallel_figure`), a resistance of 30 |ohm| was chosen since the absolute value of the real impedance at the lowest frequency was approximately 50 |ohm| (i.e., the point near the x-axis on the left-hand side).
+
+
+.. note::
+
+   Equivalent circuits can be fitted to the original impedance data that include negative differential resistances provided that negative resistances are allowed (i.e., the lower limits of resistances are disabled or modified prior to fitting).
+
+.. _parallel_figure:
+.. figure:: https://raw.githubusercontent.com/wiki/vyrjana/DearEIS/images/data-sets-tab-parallel.png
+   :alt: Addition of parallel impedance to impedance data
+
+   An impedance spectrum that includes a negative differential resistance was generated for this example (marked here as **Before**).
+   Performing Kramers-Kronig tests using the implementations included in DearEIS on this impedance data would incorrectly indicate non-compliance even for compliant impedance data.
+   Adding a parallel resistance of 30 |ohm| produces impedance data (marked here as **After**) that can be validated.
+   The added parallel resistance is always Kramers-Kronig compliant, which means that the compliance of the resulting circuit and its impedance data depends on the compliance of the original data.
+
+
+.. raw:: latex
+
+    \clearpage
+
+
+Subtracting impedances
+~~~~~~~~~~~~~~~~~~~~~~
 
 The recorded impedances can also be corrected by subtracting one of the following (:numref:`subtraction_figure`):
 
@@ -169,7 +214,7 @@ This feature can be used to, e.g., correct for some aspect of a measurement setu
 .. figure:: https://raw.githubusercontent.com/wiki/vyrjana/DearEIS/images/data-sets-tab-subtraction.png
    :alt: Subtraction of impedances from a recorded spectrum
 
-   A resistance of 100 ohm is subtracted from a data set.
+   A resistance of 100 |ohm| is subtracted from a data set.
 
 
 .. raw:: latex

docs/source/guide_drt.rst

@@ -57,7 +57,7 @@ The overlay plots shown below are created using the **Plotting** tab (more infor
    Additional DRT spectra, which were obtained by fitting **R(RC)(RQ)** circuits and calculating the DRT using the m(RQ)fit method, overlaid on top of :numref:`drt_overlay`.
    The presence of the outlier has shifted the peaks toward lower time constants (original).
    The m(RQ)fit method is less sensitive to the omission of the outlier as can be seen from the two DRT spectra (omitted and interpolated) that are almost identical.
-   The two latter spectra also have, e.g., their left-most peaks in the correct position of approximately 0.00016 s which is the expected value based on the known resistance and capacitance values (200 ohm and 0.8 :math:`\mathrm{\mu F}`, respectively) of the circuit that was used to generate the data sets.
+   The two latter spectra also have, e.g., their left-most peaks in the correct position of approximately 0.00016 s which is the expected value based on the known resistance and capacitance values (200 |ohm| and 0.8 :math:`\mathrm{\mu F}`, respectively) of the circuit that was used to generate the data sets.
 
 .. raw:: latex
 

docs/source/guide_fitting.rst

@@ -25,7 +25,17 @@ Different iterative methods and weights are available.
 If one or both of these settings are set to **Auto**, then combinations of iterative method(s) and weight(s) are used to perform multiple fits in parallel and the best fit is returned.
 
 The results are presented in the form of a table containing the fitted parameter values (and, if possible, error estimates for the fitted parameter values), a table containing statistics pertaining to the quality of the fit, three plots (Nyquist, Bode, and relative errors of the fit), and a preview of the circuit that was fitted to the data set.
-If you hover the mouse cursor over cells in the tables, then you can get additional information (e.g., more precise values or explanations).
+If you hover the mouse cursor over the cells in the tables, then you can get additional information (e.g., more precise values or explanations).
+
+.. note::
+
+   It may not always be possible to estimate errors for fitted parameters.
+   Common causes include:
+
+   - A parameter's fitted value is close to the parameter's lower or upper limit.
+   - An inappropriate equivalent circuit has been chosen.
+   - The maximum number of function evaluations is set too low.
+   - The data contains no noise and the equivalent circuit is very good at reproducing the data.
 
 
 Equivalent circuits

docs/source/guide_command_palette.rst → docs/source/guide_palettes.rst

@@ -1,14 +1,21 @@
 .. include:: ./substitutions.rst
 
+Palettes
+========
+
 Command palette
-===============
+---------------
 
 DearEIS supports the use of keybindings to perform many but not all of the actions available in the various windows and tabs (e.g., switch to a specific tab, switch to a certain plot type, a Kramers-Kronig test, or perform a Kramers-Kronig test).
 These keybindings are in many cases similar from window to window and tab to tab, and the keybindings can be reassigned via the corresponding settings window.
 However, in some cases the keybindings are unique to the window (e.g., the file dialog).
 
-When there isn't a modal/popup window open, then it is possible to perform actions via the **Command palette** (:numref:`command_palette`) that can be opened by default via ``Ctrl+P``.
+When a modal/popup window isn't open, then it is possible to perform actions via the **Command palette** (:numref:`command_palette`) that can be opened by default via ``Ctrl+P``.
 The contents of the list of actions depends upon the context (e.g., which tab is currently open).
+The list of actions can be navigated using, e.g., the arrow keys.
+Alternatively, the input field at the top can be used to search of a specific action.
+If the input field is empty, then the order of the options depends upon how recently an option was chosen.
+This should help with finding actions that are used frequently.
 
 .. _command_palette:
 .. figure:: https://raw.githubusercontent.com/wiki/vyrjana/DearEIS/images/command-palette.png
@@ -18,6 +25,14 @@ The contents of the list of actions depends upon the context (e.g., which tab is
    Actions can be navigated with the ``Up/Down`` arrow keys, ``Page Up/Down`` keys, and ``Home/End`` keys.
    The window also supports fuzzy matching for finding a specific action (e.g., ``saw`` should bring the ``Show the 'About' window`` action to the top).
 
+
+Data set and result palettes
+----------------------------
+
+The **Data set palette** and **Result palette** are similar to the **Command palette** but they instead facilitate switching between data sets or various results depending on the current tab (Kramers-Kronig test results, fit results, plots, etc.).
+The **Data set palette** and **Result palette** can be opened by default via ``Ctrl+Shift+P`` and ``Ctrl+Shift+Alt+P``, respectively.
+
+
 .. raw:: latex
 
     \clearpage

docs/source/guide_validation.rst

@@ -34,6 +34,11 @@ An additional weight is also used in the **Exploratory** mode when suggesting th
 The test results are presented in the form of a table of statistics (e.g., |pseudo chi-squared|) and different plots such as one of the relative residuals of the fit.
 
 
+.. note::
+
+   See :ref:`parallel impedances` for information about how to process impedance data that include negative differential resistances before attempting to validate the data using the included implementations of the linear Kramers-Kronig tests.
+
+
 Exploratory mode
 ~~~~~~~~~~~~~~~~
 

docs/source/substitutions.rst

@@ -26,6 +26,8 @@
 .. |lambda| replace:: :math:`\lambda`
 .. |chi-squared| replace:: :math:`\chi^2`
 .. |pseudo chi-squared| replace:: :math:`\chi^2_{ps.}`
+.. |ohm| replace:: :math:`\Omega`
+.. |degrees| replace:: :math:`^{\circ}`
 
 .. functions
 .. |get_default_num_procs| replace:: :func:`~deareis.get_default_num_procs`

post-build.py

@@ -1,3 +1,24 @@
+# DearEIS is licensed under the GPLv3 or later (https://www.gnu.org/licenses/gpl-3.0.html).
+# Copyright 2023 DearEIS developers
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <https://www.gnu.org/licenses/>.
+#
+# The licenses of DearEIS' dependencies and/or sources of portions of code are included in
+# the LICENSES folder.
+
+from dataclasses import dataclass
+from datetime import date
 from os import (
     makedirs,
     remove,
@@ -9,12 +30,19 @@
     join,
     splitext,
 )
+from re import search
 from shutil import (
     copy,
     copytree,
     rmtree,
 )
-from typing import List
+from typing import (
+    IO,
+    List,
+    Match,
+    Optional,
+    Union,
+)
 
 
 def copy_html(src: str, dst: str):
@@ -32,9 +60,9 @@ def copy_html(src: str, dst: str):
         in (
             ".html",
             ".js",
-            ".py",
             ".png",
-            ".pdf",
+            ".py",
+            ".svg",
         )
     ]
     dirs: List[str] = ["_images", "_static", "_sources"]
@@ -49,6 +77,7 @@ def copy_html(src: str, dst: str):
 
 def copy_pdf(src: str, dst: str, name: str, version_path: str):
     version: str = ""
+    fp: IO
     with open(version_path, "r") as fp:
         version = fp.read().strip().replace(".", "-")
     assert version != ""
@@ -59,6 +88,79 @@ def copy_pdf(src: str, dst: str, name: str, version_path: str):
     copy(src, dst)
 
 
+@dataclass(frozen=True)
+class Version:
+    major: int
+    minor: int
+    patch: int
+    year: int
+    month: int
+    day: int
+
+
+def validate_changelog(path: str):
+    def parse_version(match: Match) -> Version:
+        return Version(
+            major=int(match.group("major")),
+            minor=int(match.group("minor")),
+            patch=int(match.group("patch")),
+            year=int(match.group("year")),
+            month=int(match.group("month")),
+            day=int(match.group("day")),
+        )
+
+    def validate_date(
+        version: Version, comparison: Union[Version, date] = date.today()
+    ):
+        assert version.year <= comparison.year, (version, comparison)
+        assert 1 <= version.month <= 12, version
+        assert 1 <= version.day <= 31, version
+        if version.year == comparison.year:
+            assert version.month <= comparison.month, (version, comparison)
+            if version.month == comparison.month:
+                assert version.day <= comparison.day, (version, comparison)
+
+    def validate_version(earlier: Version, current: Version):
+        assert earlier.major <= current.major, (earlier, current)
+        if earlier.major < current.major:
+            return
+        assert earlier.minor <= current.minor, (earlier, current)
+        if earlier.minor < current.minor:
+            return
+        assert earlier.patch < current.patch, (earlier, current)
+
+    assert exists(path), path
+    fp: IO
+    with open(path, "r") as fp:
+        lines: List[str] = fp.readlines()
+    pattern: str = (
+        r"# (?P<major>\d+)\.(?P<minor>\d+)\.(?P<patch>\d+)"
+        r" \((?P<year>\d{4})/(?P<month>\d{2})/(?P<day>\d{2})\)"
+    )
+    try:
+        match: Optional[Match] = search(pattern, lines.pop(0))
+        assert match is not None, pattern
+        versions: List[Version] = list(
+            map(
+                parse_version,
+                [match]
+                + [
+                    match
+                    for match in map(lambda _: search(pattern, _), lines)
+                    if match is not None
+                ],
+            )
+        )
+        list(map(validate_date, versions))
+        while len(versions) > 1:
+            current: Version = versions.pop(0)
+            earlier = versions[0]
+            validate_date(earlier, current)
+            validate_version(earlier, current)
+    except AssertionError:
+        raise Exception("The changelog needs to be updated!")
+
+
 if __name__ == "__main__":
     copy_html(
         src="./docs/build/html",
@@ -70,3 +172,4 @@ def copy_pdf(src: str, dst: str, name: str, version_path: str):
         name="DearEIS",
         version_path="./version.txt",
     )
+    validate_changelog("./CHANGELOG.md")