xrdPlanner 2.3.0__tar.gz → 2.4.0__tar.gz

{xrdplanner-2.3.0 → xrdplanner-2.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: xrdPlanner
-Version: 2.3.0
+Version: 2.4.0
 Summary: A tool to project X-ray diffraction cones on a detector screen at different geometries (tilt, rotation, offset) and X-ray energies
 Author-email: Lennard Krause <lkrause@chem.au.dk>
 Project-URL: Homepage, https://github.com/LennardKrause/xrdPlanner
@@ -21,57 +21,49 @@ Requires-Dist: PyQt6>=6.5
 Requires-Dist: pyFAI>=2023.5
 
 # xrdPlanner
+## Version 2.4.0 (released 04.03.2025)
 #### A tool to project X-ray diffraction cones on a detector screen at different geometries (tilt, rotation, offset) and X-ray energies
  - Article published in [_J. Synchrotron Rad._ (2024). **31**](https://doi.org/10.1107/S1600577523011086).
  - Main application is to visualize the maximum achievable resolution at a given geometry.
  - Is able to project diffraction cones for standard samples or directly from cif files.
  - Can turn out valuable when planning beamtimes at synchrotron facilities (e.g. [DanMAX](https://www.maxiv.lu.se/beamlines-accelerators/beamlines/danmax/)).
  - Helps in deciding on the geometry of an experiment.
- - Meant to run standalone but is readily [insertable](#example-code-for-adding-xrdplanner-as-a-widget-into-an-existing-gui) as a widget into an existing PyQt6 GUI.
+ - Has a 1D [PXRD plot window](#pxrd-pattern-plot) for cif files to show the diffraction pattern and [intrumental peak broadening](#instrumental-broadening).
+ - Meant to run standalone but is readily [insertable](#example-code) as a widget into an existing PyQt6 GUI.
  - The math used is not meant to bring people to the moon but to provide a quick and simple preview.
  - This is not meant to accurately simulate a diffraction experiment, the step sizes are integer values in mm or degrees.
  - The module building code is designed for [Dectris](https://www.dectris.com) [PILATUS3](https://www.dectris.com/detectors/x-ray-detectors/pilatus3/) / [EIGER2](https://www.dectris.com/detectors/x-ray-detectors/eiger2/) or [SACLA](https://sacla.xfel.jp/?lang=en) MPCCD Detectors (central hole geometry) but one-module systems like the [Bruker](https://www.bruker.com/en.html) [Photon II](https://www.bruker.com/en/products-and-solutions/diffractometers-and-scattering-systems/single-crystal-x-ray-diffractometers/sc-xrd-components/detectors.html) and [Rayonix](https://www.rayonix.com/) [MX-HS](https://www.rayonix.com/rayonix-mx-hs-series/) are possible as well.
  - It uses [python3](https://www.python.org), [numpy](https://numpy.org), [pyqt6](https://www.riverbankcomputing.com/software/pyqt/), [pyqtgraph](https://pyqtgraph.readthedocs.io/en/latest/), [pyFAI](https://pyfai.readthedocs.io/en/v2023.1/) and [Dans_Diffraction](https://github.com/DanPorter/Dans_Diffraction).
 
-## Update to Version 2.0.0 (released 23.09.2024)
- - The definition of detector modules was changed from mm to px to be more accurate and consistent.
- - Consequently, custom detectors added to the detector_db file are no longer available.
- - A new detector editor was added (_Settings_ > _Detector db editor_) to make the addition of custom detectors more feasible.
- - Define and add whatever detector you collect your data with, now more easily.
- - If something goes wrong use _Settings_ > _Reset detector db_.
- - There is a backup of your _custom_ detector_db (detector_db.json.bak) in the xrdPlanner folder (_Help_ > _xrdPlanner_).
- - A new parameter was added to allow for detector screen padding (geo.plot_padding), default is 0.
-
-## Short how-to:
- - (python3 -m) pip install xrdPlanner.
- - Type _xrdPlanner_ in a terminal and hit enter.
- - Choose a detector and a model from the _Detector_ menu.
- - Plot diffraction cone contours:
-   - Pick a reference from the _Reference_ menu ([pyFAI](https://pyfai.readthedocs.io/en/v2023.1/)), no hkl tooltip available.
-   - Drop a .cif file onto the window ([Dans_Diffraction](https://github.com/DanPorter/Dans_Diffraction)), click a contour to get a hkl tooltip.
-   - Enter custom unit cell dimensions, click a contour to get a hkl tooltip.
- - Use the units from the _Units_ menu you are the most comfortable with.
- - Hover over the grey line at the top to show the sliders. Click it to make it stay open.
- - Drag the sliders to change energy and geometry.
-
-## Customisation:
-  - Use the [export window](#export-window) from the settings menu.
-    - Build up the available detector and beamstop bank.
-    - Review and change the parameters.
-    - Tooltips should help you along the way.
-  - Use the detector db editor.
-    - Define the detector you collect your data with.
-    - Add all the different sizes and versions.
-    - Use _Preview_ to play around and _Save_ to update the data bank.
-  - Or edit the _settings.json_ file and the _detector_db.json_ files directly.
-    - Use _Settings_ -> _Edit files_ to edit the _current settings_ or _Detector db_ file.
-    - Reload the settings file to see the difference.
-    - _geo_ determines the startup defaults.
-    - _plo_ customises the general layout and visuals.
-    - _thm_ makes it look the way you want.
-    - _lmt_ sets the limiting values of the geometry/energy sliders.
-  - Check the [settings file documentation](#settings-file-documentation) to get started.
-  - Add all the missing detectors to the _detector_db.json_, see the [detector db entries](#detector-db-entries).
+>[!TIP]
+>## Short how-to:
+> - (python3 -m) pip install xrdPlanner.
+> - Type _xrdPlanner_ in a terminal and hit enter.
+> - Choose a detector and a model from the _Detector_ menu.
+> - Plot diffraction cone contours:
+>   - Pick a reference from the _Reference_ menu ([pyFAI](https://pyfai.readthedocs.io/en/v2023.1/)), no hkl tooltip available.
+>   - Drop a .cif file onto the window ([Dans_Diffraction](https://github.com/DanPorter/Dans_Diffraction)), click a contour to get a hkl tooltip.
+>   - Enter custom unit cell dimensions, click a contour to get a hkl tooltip.
+> - Use the units from the _Units_ menu you are the most comfortable with.
+> - Hover over the grey line at the top to show the sliders. Click it to make it stay open.
+> - Drag the sliders to change energy and geometry.
+> - Use [hotkeys](#hotkeys) to streamline your experience.
+>
+>## Customisation:
+>  - Use the [export window](#export-window) from the settings menu.
+>    - Build up the available detector and beamstop bank.
+>    - Review and change the parameters.
+>    - Tooltips should help you along the way.
+>  - Use the [detector db editor](#detector-db-editor).
+>    - Define the detector you collect your data with.
+>    - Add all the different sizes and versions.
+>    - Use _Preview_ to play around and _Save_ to update the data bank.
+>  - Or edit the _settings.json_ file and the _detector_db.json_ files directly.
+>    - Use _Settings_ -> _Edit files_ to edit the _current settings_ or _Detector db_ file.
+>    - Check the [settings file documentation](#settings-file-documentation) to get started.
+>  - Use pre-set beamline settings files:
+>    - Download a settings file from here (e.g. settings/DanMAX.json).
+>    - Use the import settings function from the GUI to import.
 
 ## Conventions
 The geometry is defined with the center of rotation at the sample position, such that the radius of the rotation circle is equal to the sample to detector distance (SDD). That is, the rotation moves the detector along the goniometer circle, keeping the point of normal incidence (PONI) at the same position relative to the detector surface. At 0° the detector is vertical and at 90° the detector is horizontal with the detector normal pointing down.
@@ -118,25 +110,41 @@ S_{ij} = \left(\frac{|\vec{v}_{ij}|}{SDD}\right)^{-3}
 ```
 where $SDD$ is the sample to detector distance.
 
-## Use pre-set beamline settings files:
-  - Download a settings file from here (e.g. settings/DanMAX.json).
-  - Use the import settings function from the GUI to import.
-  - You can switch between all imported settings.
-  - Use the export window to customise and export your settings.
-
-## Known bugs and limitations:
-  - On Windows: Switching Dark/Light mode requires restart to change the window frame color.
-  - As of now, there is no consistency check performed on the imported .json file.
-  - The projections fail at a combined angle (rotation + tilt) of 90 degrees and beyond.
-  - If the program crashes (libc++abi) when opening the export window (on a Mac) please update PyQt6 to the latest version.
-
-## After the update:
-   Sometimes I might change the name of a parameter and you will get a warning message upon startup looking something like this: _WARNING: "conic_ref_min_int" is not a valid key_! Either that key is no longer in use or its name got changed and is now reset to the default value. The settings file is updated and the warning should no longer appear after restart. Apart from this, your edited settings file will not be altered after updating.
+>[!NOTE]
+>## Update to Version 2.0.0 and later (released 23.09.2024)
+> - The definition of detector modules was changed from mm to px to be more accurate and consistent.
+> - Consequently, custom detectors added to the detector_db file pre 2.0.0 are no longer working.
+> - A new [detector db editor](#detector-db-editor) was added (_Settings_ > _Detector db editor_) to make the addition of custom detectors more feasible.
+> - Define and add whatever detector you collect your data with, now more easily.
+> - If something goes wrong use _Settings_ > _Reset detector db_.
+> - There is a backup of your _custom_ detector_db (detector_db.json.bak) in the xrdPlanner folder (_Help_ > _xrdPlanner_).
+> - A new parameter was added to allow for detector screen padding (plo.plot_padding), default is 0.
 
 ## Latest updates:
-  - 2024-09-23 Update: Added a detector editor to define and add whatever detector you collect your data with, now more easily.
-  - 2024-09-23 Update: Changed the detector module definition from mm to px (added custom detectors won't be available!).
+  - 2025-03-04 Update: Added pxrd ghost lines to play with and compare the scattering using different parameters.
+  - 2025-03-04 Update: Made some improvements to the highlighting.
+  - 2025-03-04 Update: Trained most sub-windows to remember their place.
+  - 2025-03-04 Update: Started to declutter the code.
+  - 2025-03-04 Bugfix: Resynchronized the menu button for the angular grid (Thanks Frederik).
+  - 2025-02-12 Bugfix: Fixed f-string SyntaxError crash on startup (python version < 3.12).
+  - 2025-02-10 Update: Added the option to estimate Thomas-Cox-Hastings parameters (gaussian) from the estimated instrumental broadening.
+  - 2025-02-10 Update: Reworked the hkl display and cone highlighting to make identification and location of hkl more straightforward.
+  - 2025-02-10 Update: Highlighting is now linked between the main window and the pxrd viewer.
+  - 2024-12-05 Update: Added the option to export the FWHM grid as a compressed numpy .npz file (View > Functions > Export FWHM).
+  - 2024-11-08 Update: Added a visual indicators for azimuthal bins (View > Overlay > Grid or hotkey G).
+  - 2024-11-08 Bugfix: Fixed invisible menus on windows os.
+  - 2024-10-29 Update: Added a menu action to invert the coloring of the resolution and reference conics (_View_ > _Invert cone colors_) to increase visibility, when needed.
+  - 2024-10-28 Update: Added a [PXRD plot window](#pxrd-pattern-plot) for cif files to show the diffraction pattern (gaussian peak shape) including [intrumental peak broadening](#instrumental-broadening) (setup FWHM).
+  - 2024-10-28 Update: cif files are stored now (name and link-to-file).
+  - 2024-10-28 Update: Added somewhat useful doc-strings to all functions (Thanks Github Copilot).
+  - 2024-10-01 Bugfix: Fixed an error crashing the detector db editor on python < 3.12 (Thanks Lise).
+  - 2024-09-23 Update: Added a [detector db editor](#detector-db-editor) to define and add whatever detector you collect your data with, now more easily.
+  - 2024-09-23 Update: Changed the detector module definition from mm to px (pre 2.0.0 custom detectors won't work!).
   - 2024-09-23 Update: Added a preview plot to the FWHM setup window.
+
+<details>
+<summary>Older updates</summary>
+  
   - 2024-06-20 Update: Added highlighting of a clicked contour.
   - 2024-06-20 Bugfix: Incorrect removal of beamstop contour.
   - 2024-05-30 Update: Added support for custom unit cells to calculate and plot conics.
@@ -145,10 +153,6 @@ where $SDD$ is the sample to detector distance.
   - 2024-05-02 Update: Automatic label placement (conic_label_auto, default=True).
   - 2024-05-02 Update: Dynamic cones try to keep the number of visible conics constant (conic_tth_auto, default=True).
   - 2024-05-02 Update: Current colors are displayed in the export window and a colorpicker is used.
-
-<details>
-<summary>Older updates</summary>
-  
   - 2024-02-17 Bugfix: Fixed crash on importing settings files (Thanks Andy).
   - 2024-02-16 Update: Added a unit value at mouse position (hover) to the overlay.
   - 2024-02-09 Update: Updated the About window with links to github and the publication.
@@ -193,22 +197,61 @@ where $SDD$ is the sample to detector distance.
   - 2022-04-25 Bugfix: Calculation of the beamcenter (rotation and tilt).
 </details>
 
+<details>
+<summary>After the update</summary>
+ 
+  - Sometimes I might change the name of a parameter and you will get a warning message upon startup looking something like this: _WARNING: "conic_ref_min_int" is not a valid key_! Either that key is no longer in use or its name got changed and is now reset to the default value. The settings file is updated and the warning should no longer appear after restart. Apart from this, your edited settings file will not be altered after updating.
+</details>
+
+>[!IMPORTANT]
+>## Known bugs and limitations:
+>  - On Windows: Switching Dark/Light mode requires restart to change the window frame color.
+>  - As of now, there is no consistency check performed on the imported .json file.
+>  - The projections fail at a combined angle (rotation + tilt) of 90 degrees and beyond.
+>  - If the program crashes (libc++abi) when opening the export window (on a Mac) please update PyQt6 to the latest version.
+>  - A crash on startup due to an f-string SyntaxError can be circumvented by upgrading python to version 3.12 or later.
+
 ## Examples
 #### A PILATUS3 300K detector and a Rubrene sample.
-![Preview](https://github.com/LennardKrause/xrdPlanner/blob/main/examples/Figure_2_example_light.png)
+<img src="https://github.com/LennardKrause/xrdPlanner/blob/main/examples/Figure_2_example_light.png" width="50%">
 
 #### A rotated EIGER2 9M detector and a Rubrene sample (darkmode).
-![Preview](https://github.com/LennardKrause/xrdPlanner/blob/main/examples/Figure_1_example_dark.png)
+<img src="https://github.com/LennardKrause/xrdPlanner/blob/main/examples/Figure_1_example_dark.png" width="50%">
 
 #### Export window
 ##### Use the export window to select and build up the available detector / beamstop bank and review/change parameters.
-![Preview](https://github.com/LennardKrause/xrdPlanner/blob/main/examples/Figure_3_export_window.png)
+<img src="https://github.com/LennardKrause/xrdPlanner/blob/main/examples/Figure_3_export_window.png" width="50%">
+
+#### Detector db editor
+##### Define and add the detector you collect your data with.
+<img src="https://github.com/LennardKrause/xrdPlanner/blob/main/examples/Figure_4_detector_db_editor.png" width="50%">
+
+#### PXRD pattern plot
+##### Look at a 1D PXRD pattern plot of the calculated intensities (cif-file), displayed using gaussian peak shapes and the estimated peak broadening (FWHM).
+<img src="https://github.com/LennardKrause/xrdPlanner/blob/main/examples/Figure_5_PXRD.png" width="50%">
+
+#### Instrumental broadening
+##### Estimate FWHM (H, in degrees) using the following parameters:
+ - Estimated effective thickness of the detector absorption layer depending on sensor material and incident wavelength
+ - Detector sensor layer material
+ - Estimated beam divergence
+ - Expected bandwidth of the incident X-ray beam
+ - Intersection of the sample size and the beam size as the diameter
+
+> **The interested user is referred to the article:<br>**
+>  <i>On the resolution function for powder diffraction with area detectors</i><br>
+>  [D. Chernyshov <i> et al., Acta Cryst.</i> (2021). <b>A77</b>, 497-505](https://doi.org/10.1107/S2053273321007506)
+<img src="https://github.com/LennardKrause/xrdPlanner/blob/main/examples/Figure_6_FWHM.png" width="50%">
 
 ## Hotkeys
 
 | Key        | Action                    |
 | ---------- | ------------------------- |
 | F1         | Show About window         |
+| F2         | Show Geometry conventions |
+| F3         | Show Hotkeys              |
+| x          | Show PXRD pattern         |
+| f          | Show FWHM window          |
 | #          | *Display units*           |
 | t          | 2-Theta                   |
 | d          | d-spacing                 |
@@ -227,8 +270,9 @@ where $SDD$ is the sample to detector distance.
 | Shift + c  | Previous                  |
 
 ## Settings file documentation
-
-#### geo - startup defaults
+<details>
+<summary>geo - startup defaults</summary>
+ 
     det_type = 'EIGER2'  # [str]  Pilatus3 / Eiger2 / etc.
                          #        -> Detector menu entry
     det_size = '4M'      # [str]  300K 1M 2M 6M / 1M 4M 9M 16M
@@ -255,8 +299,11 @@ where $SDD$ is the sample to detector distance.
                2.5,
                3.0,
                5.0]
+</details>
 
-#### plo - plot settings
+<details>
+<summary>plo - plot settings</summary>
+ 
     # - geometry contour section - 
     conic_tth_min = 5               # [int]    Minimum 2-theta contour line
     conic_tth_max = 100             # [int]    Maximum 2-theta contour line
@@ -326,7 +373,11 @@ where $SDD$ is the sample to detector distance.
     # - debug/testing -
     set_debug = False               # [bool]   Debug mode
 
-#### thm - theme
+</details>
+
+<details>
+<summary>thm - theme</summary>
+ 
     color_dark = '#404040'                # [color]  Global dark color
     color_light = '#EEEEEE'               # [color]  Global light color
     
@@ -360,7 +411,10 @@ where $SDD$ is the sample to detector distance.
     dark_slider_bg_hover = '#303030'      # [color]  Slider frame hover color
     dark_slider_label_color = '#C0C0C0'   # [color]  Slider frame label color
 
-#### lmt - limits
+</details>
+
+<details>
+<summary>lmt - limits</summary>
 
     # energy [keV]
     ener_min =  5    # [int] Energy minimum [keV]
@@ -396,7 +450,10 @@ where $SDD$ is the sample to detector distance.
     bsdx_max = 1000  # [int] Beamstop distance maximum [mm]
     bsdx_stp = 1     # [int] Beamstop distance step size [mm]
 
-## Detector db entries
+</details>
+
+<details>
+<summary>Detector db entries</summary>
 
 The detector_db.json is stored as a dictionary
 - key: detector name e.g. PILATUS3
@@ -404,12 +461,12 @@ The detector_db.json is stored as a dictionary
  
  | Entry |  Value  | Hint |
  |-------|---------|------|
- |  hms  | 83.8    | [mm]   Module size (horizontal)
- |  vms  | 33.5    | [mm]   Module size (vertical)
- |  pxs  | 172e-3  | [mm]   Pixel size
- |  hgp  | 7       | [pix]  Gap between modules (horizontal)
- |  vgp  | 17      | [pix]  Gap between modules (vertical)
- |  cbh  | 0       | [mm]   Central beam hole
+ |  pxs  | 172e-3  | [mm] Pixel size
+ |  hmp  | 487     | [px] Module size (horizontal)
+ |  vmp  | 195     | [px] Module size (vertical)
+ |  hgp  | 7       | [px] Gap between modules (horizontal)
+ |  vgp  | 17      | [px] Gap between modules (vertical)
+ |  cbh  | 0       | [px] Central beam hole
 
 The size Entry is a dictionary {key:value,}
 - key: detector size / type, e.g. 300K
@@ -419,9 +476,9 @@ The size Entry is a dictionary {key:value,}
  
 #### Example of the PILATUS3 entry
     "PILATUS3": {
-        "hms": 83.8,
-        "vms": 33.5,
         "pxs": 0.172,
+        "hmp": 487,
+        "vmp": 195,
         "hgp": 7,
         "vgp": 17,
         "cbh": 0,
@@ -433,7 +490,12 @@ The size Entry is a dictionary {key:value,}
         }
     },
 
-## Example code for adding xrdPlanner as a widget into an existing GUI
+</details>
+
+## Example code
+<details>
+<summary>Example code for adding xrdPlanner as a widget into an existing GUI</summary>
+ 
 #### xrdPlanner uses its own menu bar, setting the GUI as the parent for xrdPlanner makes it add its menus to the parents menu bar, and likely more in the future.
 
     import sys
@@ -457,5 +519,6 @@ The size Entry is a dictionary {key:value,}
         window = MainWindow()
         window.show()
         app.exec()
+</details>
 
-#### I hope this turns out to be useful for someone!
+## I hope this turns out to be useful for someone!