Plotting styles and logging utils (#98)

Author: fsoubelet

docs/api/plotting.rst

@@ -3,6 +3,17 @@
 Plotting
 ========
 
+
+.. automodule:: pyhdtoolkit.plotting.styles
+   :members:
+
+
+.. automodule:: pyhdtoolkit.plotting.styles.paper
+   :members:
+
+.. automodule:: pyhdtoolkit.plotting.styles.thesis
+   :members:
+
 .. automodule:: pyhdtoolkit.plotting.aperture
    :members:
 

docs/api/utils.rst

@@ -9,15 +9,15 @@ Utils
 .. automodule:: pyhdtoolkit.utils.contexts
    :members:
 
-.. automodule:: pyhdtoolkit.utils.defaults
-   :members:
-
 .. automodule:: pyhdtoolkit.utils.executors
    :members:
 
 .. automodule:: pyhdtoolkit.utils.htc_monitor
    :members:
 
+.. automodule:: pyhdtoolkit.utils.logging
+   :members:
+
 .. automodule:: pyhdtoolkit.utils._misc
    :members:
 

docs/conf.py

@@ -193,7 +193,6 @@ def __call__(self, *args, **kwargs):
 
 # Config for the matplotlib plot directive
 plot_formats = [("svg", 250)]
-plot_rcparams = pyhdtoolkit.utils.defaults.PLOT_PARAMS
 
 # -- Options for HTML output ----------------------------------------------
 
@@ -528,4 +527,5 @@ def __call__(self, *args, **kwargs):
     "tfs": ("https://pylhc.github.io/tfs/", None),
     "cpymad": ("https://hibtc.github.io/cpymad/", None),
     "optics_functions": ("https://pylhc.github.io/optics_functions/", None),
+    "loguru": ("https://loguru.readthedocs.io/en/stable/", None),
 }

docs/quickstart.rst

@@ -100,8 +100,7 @@ One can find many examples of the `~pyhdtoolkit.cpymadtools` apis' use in the :r
 Utilities
 ^^^^^^^^^
 
-The :ref:`utils <pyhdtoolkit-utils>` module contains useful functions to set up logging or
-plotting :ref:`defaults <utils-defaults>`, run external programs through the :ref:`command line <utils-cmdline>`, 
+The :ref:`utils <pyhdtoolkit-utils>` module contains useful functions to set up (:ref:`logging <utils-logging>`, run external programs through the :ref:`command line <utils-cmdline>`, 
 run your functions through :ref:`useful contexts <utils-contexts>`, easily wrap and :ref:`parallelise <utils-executors>`
 functions, or perform many convenient :ref:`operations <utils-operations>` on miscellaneous Python objects.
 
@@ -125,12 +124,12 @@ Alternatively one can easily parallelise an I/O-intensive function through multi
     )
 
 .. tip::
-    A useful tidbit is this line which sets up the logging level for functions in the package:
+    A useful tidbit is the following which sets up the logging level for functions in the package:
 
     .. prompt:: python >>>
 
-        from pyhdtoolkit.utils import defaults
-        defaults.config_logger(level="trace")  # the lowest level used, will give ALL logging
+        from pyhdtoolkit.utils import logging
+        logging.config_logger(level="trace")  # the lowest level used, will give ALL logging
 
 Additional Helpers
 ^^^^^^^^^^^^^^^^^^

docs/releases/v1.0.0.rst

@@ -4,7 +4,7 @@
 -----
 
 Release `1.0.0` brings many breaking changes.
-Be sure to read these release notes carefully before upgrading, as much of the code using ``pyhdtoolki`` will need to be adapted.
+Be sure to read these release notes carefully before upgrading, as much of the code using ``pyhdtoolkit`` will need to be adapted.
 
 Breaking Changes
 ~~~~~~~~~~~~~~~~
@@ -14,23 +14,28 @@ Breaking Changes
 * The `~pyhdtoolkit.plotting.helpers` module has been renamed to `~pyhdtoolkit.plotting.utils` for consistency.
 * The `~pyhdtoolkit.plotting.sbs.utils` module has been merged into `~pyhdtoolkit.plotting.utils`.
 * The `~pyhdtoolkit.cpymadtools.plotters.DynamicAperture` functionality has been completely removed.
+* The `~pyhdtoolkit.utils.defaults` module has been removed, and its functionality transferred in the relevant (new) places.
 
 Enhancements
 ~~~~~~~~~~~~
 
 * The machine layout plotting functionality has been made public api in a dedicated module, `~pyhdtoolkit.plotting.layout`.
 * A new module has been added to the `~pyhdtoolkit.cpymadtools`, `~pyhdtoolkit.cpymadtools.setup`, with functions to conveniently set up a `~cpymad.madx.Madx` instance for either the Run 2 or Run 3 of the ``LHC``, also as a context manager.
 * A new module has been added in `~pyhdtoolkit.plotting`, `~pyhdtoolkit.plotting.layout`, to make public the API to plot a machine's element onto an axis.
+* A new module has been added in `~pyhdtoolkit.utils`, `~pyhdtoolkit.utils.logging`, to host the logging setup functionality that was previously in `~pyhdtoolkit.utils.defaults`.
+* A new module has been added in `~pyhdtoolkit.plotting`, `~pyhdtoolkit.plotting.styles`, with various useful styles definitions and the functionality to install them locally.
 * New function in `~pyhdtoolkit.cpymadtools.lhc`, `~pyhdtoolkit.cpymadtools.lhc.add_markers_around_lhc_ip`, to do exactly that, for high granularity of calculations around the IP point.
 * New function in `~pyhdtoolkit.cpymadtools.lhc`, `~pyhdtoolkit.cpymadtools.lhc.get_sizes_at_ip`, to compute horizontal and vertical beam sizes at a given IP through ``Ripken`` parameters, which will be accurate in the presence of coupling.
 * New function in `~pyhdtoolkit.plotting.utils`, `~pyhdtoolkit.plotting.utils.get_lhc_ips_positions`, to get a `dict` of different IP elements and their ``S`` coordinates.
 * New function in `~pyhdtoolkit.plotting.utils`, `~pyhdtoolkit.plotting.utils.draw_ip_locations`, to highlight the positions of given IPs onto the current axis as vertical lines, potentially also writing out their names.
 * The element plotting functionality handled by `~pyhdtoolkit.plotting.layout.plot_machine_layout` now determines reasonable default ``ylimits`` if none were provided. This allowed removing hardcoded default values of these limits, and should help get a good looking plot for any machine by default.
+* The `~pyhdtoolkit.cpymadtools.lhc.make_lhc_beams` function can now handle the ``bv`` flag in case the user is trying to set up for tracking with B2 (which needs loading **lhcb4** and a different bv flag).
+* The `config_logger` function, now in `~pyhdtoolkit.utils.logging`, now accepts custom formats and three default formats are provided in the module.
 
 Maintenance
 ~~~~~~~~~~~
 
-* Documentation has been updated. Refer to the gallery for example uses.
+* Documentation has been updated for all new APIs. Refer to the gallery for example uses.
 * Tests have been adapted.
 
 See `v1.0.0 release notes on GitHub <https://github.com/fsoubelet/PyhDToolkit/releases/tag/1.0.0>`_ and the `full changes since v0.21.0 <https://github.com/fsoubelet/PyhDToolkit/compare/0.21.0...1.0.0>`_.

examples/README.rst

@@ -10,12 +10,17 @@ This page contains a gallery showcasing either plotting functionality provided i
 submodules, or plots made from results of convenient functions available in `~pyhdtoolkit`.
 
 .. important::
-    The examples shown here are plotted with a customized but simple ``rcParams`` style. If one uses
-    this package and sets their own preferences or uses their own **mplstyle**, the resulting plots
-    might look significantly different.
+    The examples shown here are plotted with a customized but simple ``rcParams`` style, simply for
+    visibility in these galleries. If one uses this package and sets their own preferences or uses
+    their own **mplstyle**, the resulting plots might look significantly different.
 
-    The package provides a plotting style in the `~pyhdtoolkit.utils.defaults` module, which should be 
-    compatible with the plotters. One can use the style in two ways:
+    The package provides several plotting styles in the `~pyhdtoolkit.plotting.styles` submodules,
+    which are tailored for good rendering in my LaTeX documents and are made for good compatibility
+    with the various plotters in `~pyhdtoolkit.plotting`. These styles are described in the 
+    :ref:`styles <plotting-styles>` documentation section.
+
+    One can use them in two ways, shown below with as example the ``MEDIUM`` style defined in
+    `pyhdtoolkit.plotting.styles.thesis`.
 
     .. tabbed:: Import and Set the Style
 
@@ -24,21 +29,32 @@ submodules, or plots made from results of convenient functions available in `~py
             .. prompt:: python >>>
 
                 from matplotlib import pyplot as plt
-                from pyhdtoolkit.utils.defaults import PLOT_PARAMS
+                from pyhdtoolkit.plotting.styles.thesis import MEDIUM
+
+                plt.rcParams.update(MEDIUM)
+                # plotting code here
+
+        Or, for a temporary update of the ``rcParams``:
+
+            .. prompt:: python >>>
+
+                from matplotlib import pyplot as plt
+                from pyhdtoolkit.plotting.styles.thesis import MEDIUM
 
-                plt.rcParams.update(PLOT_PARAMS)
+                with plt.rc_context(MEDIUM):
+                    # Plotting code here
 
-    .. tabbed:: Install and Load the Style
+    .. tabbed:: Install the Styles and Load One
 
-        Do a one-time install of the style as an **.mplstyle** file to import in `~matplotlib`:
+        Do a one-time install of the styles as **.mplstyle** files to use in `~matplotlib`:
 
             .. prompt:: python >>>
 
                 from matplotlib import pyplot as plt
-                from pyhdtoolkit.utils import defaults
+                from pyhdtoolkit.plotting.styles import install_mpl_styles
 
-                defaults.install_mpl_style()  # only run this once
-                plt.style.use("phd")  # created file is 'phd.mplstyle'
+                install_mpl_styles()  # only run this once
+                plt.style.use("thesis-medium")  # loaded from created file 'thesis-medium.mplstyle'
 
     In both cases, re-updating the ``rcParams`` later on will always overwrite these settings.
 

examples/demo_acd_tracking_spectra.py

@@ -26,10 +26,11 @@
 from cpymad.madx import Madx
 
 from pyhdtoolkit.cpymadtools import lhc, matching, track
-from pyhdtoolkit.utils import defaults
+from pyhdtoolkit.plotting.styles import _SPHINX_GALLERY_PARAMS
+from pyhdtoolkit.utils import logging
 
-defaults.config_logger(level="warning")
-plt.rcParams.update(defaults._SPHINX_GALLERY_PARAMS)  # for readability of this tutorial
+logging.config_logger(level="warning")
+plt.rcParams.update(_SPHINX_GALLERY_PARAMS)  # for readability of this tutorial
 
 ###############################################################################
 # Let's start by setting up the LHC in ``MAD-X``, in this case at top energy:

examples/demo_aperture.py

@@ -16,10 +16,11 @@
 
 from pyhdtoolkit.cpymadtools import lhc
 from pyhdtoolkit.plotting.aperture import plot_aperture
-from pyhdtoolkit.utils import defaults
+from pyhdtoolkit.plotting.styles import _SPHINX_GALLERY_PARAMS
+from pyhdtoolkit.utils import logging
 
-defaults.config_logger(level="warning")
-plt.rcParams.update(defaults._SPHINX_GALLERY_PARAMS)  # for readability of this tutorial
+logging.config_logger(level="warning")
+plt.rcParams.update(_SPHINX_GALLERY_PARAMS)  # for readability of this tutorial
 
 ###############################################################################
 # Setup a simple LHC simulation in ``MAD-X``, at injection energy (450 GeV)

examples/demo_beam_enveloppe.py

@@ -19,10 +19,11 @@
 
 from pyhdtoolkit.models.beam import BeamParameters
 from pyhdtoolkit.plotting.envelope import plot_envelope, plot_stay_clear
-from pyhdtoolkit.utils import defaults
+from pyhdtoolkit.plotting.styles import _SPHINX_GALLERY_PARAMS
+from pyhdtoolkit.utils import logging
 
-defaults.config_logger(level="warning")
-plt.rcParams.update(defaults._SPHINX_GALLERY_PARAMS)  # for readability of this tutorial
+logging.config_logger(level="warning")
+plt.rcParams.update(_SPHINX_GALLERY_PARAMS)  # for readability of this tutorial
 
 ###############################################################################
 # Define beam parameters for injection and top energy (1.9 GeV -> 19 GeV):

examples/demo_ir_errors.py

@@ -20,10 +20,11 @@
 from cpymad.madx import Madx
 
 from pyhdtoolkit.cpymadtools import errors, lhc, matching
-from pyhdtoolkit.utils import defaults
+from pyhdtoolkit.plotting.styles import _SPHINX_GALLERY_PARAMS
+from pyhdtoolkit.utils import logging
 
-defaults.config_logger(level="warning")
-plt.rcParams.update(defaults._SPHINX_GALLERY_PARAMS)  # for readability of this tutorial
+logging.config_logger(level="warning")
+plt.rcParams.update(_SPHINX_GALLERY_PARAMS)  # for readability of this tutorial
 
 ###############################################################################
 # Setup a simple LHC simulation in ``MAD-X``, at injection energy (450 GeV)

examples/demo_lattice.py

@@ -19,10 +19,11 @@
 from pyhdtoolkit.cpymadtools import lhc, matching, orbit
 from pyhdtoolkit.cpymadtools.generators import LatticeGenerator
 from pyhdtoolkit.plotting.lattice import plot_latwiss
-from pyhdtoolkit.utils import defaults
+from pyhdtoolkit.plotting.styles import _SPHINX_GALLERY_PARAMS
+from pyhdtoolkit.utils import logging
 
-defaults.config_logger(level="warning")
-plt.rcParams.update(defaults._SPHINX_GALLERY_PARAMS)  # for readability of this tutorial
+logging.config_logger(level="warning")
+plt.rcParams.update(_SPHINX_GALLERY_PARAMS)  # for readability of this tutorial
 
 ###############################################################################
 # Let's start by generating a simple lattice and setup your simulation:

examples/demo_lhc_crossing_schemes.py

@@ -18,10 +18,11 @@
 
 from pyhdtoolkit.cpymadtools import lhc
 from pyhdtoolkit.plotting.crossing import plot_two_lhc_ips_crossings
-from pyhdtoolkit.utils import defaults
+from pyhdtoolkit.plotting.styles import _SPHINX_GALLERY_PARAMS
+from pyhdtoolkit.utils import logging
 
-defaults.config_logger(level="warning")
-plt.rcParams.update(defaults._SPHINX_GALLERY_PARAMS)  # for readability of this tutorial
+logging.config_logger(level="warning")
+plt.rcParams.update(_SPHINX_GALLERY_PARAMS)  # for readability of this tutorial
 
 
 ###############################################################################

examples/demo_lhc_rigid_waist_shift.py

@@ -28,10 +28,11 @@
 
 from pyhdtoolkit.cpymadtools import lhc, matching
 from pyhdtoolkit.plotting.lattice import plot_latwiss
-from pyhdtoolkit.utils import defaults
+from pyhdtoolkit.plotting.styles import _SPHINX_GALLERY_PARAMS
+from pyhdtoolkit.utils import logging
 
-defaults.config_logger(level="warning")
-plt.rcParams.update(defaults._SPHINX_GALLERY_PARAMS)  # for readability of this tutorial
+logging.config_logger(level="warning")
+plt.rcParams.update(_SPHINX_GALLERY_PARAMS)  # for readability of this tutorial
 
 ###############################################################################
 # Showcasing the Waist Shift

examples/demo_machine_survey.py

@@ -16,10 +16,11 @@
 
 from pyhdtoolkit.cpymadtools.generators import LatticeGenerator
 from pyhdtoolkit.plotting.lattice import plot_machine_survey
-from pyhdtoolkit.utils import defaults
+from pyhdtoolkit.plotting.styles import _SPHINX_GALLERY_PARAMS
+from pyhdtoolkit.utils import logging
 
-defaults.config_logger(level="warning")
-plt.rcParams.update(defaults._SPHINX_GALLERY_PARAMS)  # for readability of this tutorial
+logging.config_logger(level="warning")
+plt.rcParams.update(_SPHINX_GALLERY_PARAMS)  # for readability of this tutorial
 
 ###############################################################################
 # Generate a simple lattice and setup your simulation:

examples/demo_phase_space.py

@@ -26,10 +26,11 @@
     plot_courant_snyder_phase_space,
     plot_courant_snyder_phase_space_colored,
 )
-from pyhdtoolkit.utils import defaults
+from pyhdtoolkit.plotting.styles import _SPHINX_GALLERY_PARAMS
+from pyhdtoolkit.utils import logging
 
-defaults.config_logger(level="warning")
-plt.rcParams.update(defaults._SPHINX_GALLERY_PARAMS)  # for readability of this tutorial
+logging.config_logger(level="warning")
+plt.rcParams.update(_SPHINX_GALLERY_PARAMS)  # for readability of this tutorial
 
 ###############################################################################
 # Define some constants, generate a simple lattice and setup your simulation:

examples/demo_sbs_plotting.py

@@ -14,10 +14,11 @@
 import tfs
 
 from pyhdtoolkit.plotting.sbs import coupling, phase
-from pyhdtoolkit.utils import defaults
+from pyhdtoolkit.plotting.styles import _SPHINX_GALLERY_PARAMS
+from pyhdtoolkit.utils import logging
 
-defaults.config_logger(level="warning")
-plt.rcParams.update(defaults._SPHINX_GALLERY_PARAMS)  # for readability of this tutorial
+logging.config_logger(level="warning")
+plt.rcParams.update(_SPHINX_GALLERY_PARAMS)  # for readability of this tutorial
 plt.rcParams.update({"text.usetex": True, "legend.fontsize": 16})  # for these specific plots
 
 ###############################################################################

examples/demo_stats_fitting.py

@@ -23,11 +23,12 @@
 import scipy.stats as st
 
 from pyhdtoolkit.maths import stats_fitting as fitting
+from pyhdtoolkit.plotting.styles import _SPHINX_GALLERY_PARAMS
 from pyhdtoolkit.plotting.utils import set_arrow_label
-from pyhdtoolkit.utils import defaults
+from pyhdtoolkit.utils import logging
 
-defaults.config_logger(level="warning")
-plt.rcParams.update(defaults._SPHINX_GALLERY_PARAMS)  # for readability of this tutorial
+logging.config_logger(level="warning")
+plt.rcParams.update(_SPHINX_GALLERY_PARAMS)  # for readability of this tutorial
 
 ###############################################################################
 # We will for this example create a chi-square_ distribution with known parameters. As the

examples/demo_track_spectra.py

@@ -19,10 +19,11 @@
 from cpymad.madx import Madx
 
 from pyhdtoolkit.cpymadtools import lhc, track
-from pyhdtoolkit.utils import defaults
+from pyhdtoolkit.plotting.styles import _SPHINX_GALLERY_PARAMS
+from pyhdtoolkit.utils import logging
 
-defaults.config_logger(level="warning")
-plt.rcParams.update(defaults._SPHINX_GALLERY_PARAMS)  # for readability of this tutorial
+logging.config_logger(level="warning")
+plt.rcParams.update(_SPHINX_GALLERY_PARAMS)  # for readability of this tutorial
 
 ###############################################################################
 # Let's start by setting up the LHC in ``MAD-X``, in this case at top energy:

examples/demo_tune_diagram.py

@@ -12,11 +12,12 @@
 # sphinx_gallery_thumbnail_number = -1
 import matplotlib.pyplot as plt
 
+from pyhdtoolkit.plotting.styles import _SPHINX_GALLERY_PARAMS
 from pyhdtoolkit.plotting.tune import plot_tune_diagram
-from pyhdtoolkit.utils import defaults
+from pyhdtoolkit.utils import logging
 
-defaults.config_logger(level="warning")
-plt.rcParams.update(defaults._SPHINX_GALLERY_PARAMS)  # for readability of this tutorial
+logging.config_logger(level="warning")
+plt.rcParams.update(_SPHINX_GALLERY_PARAMS)  # for readability of this tutorial
 
 ###############################################################################
 # The tune diagram allows on to visualise resonance lines up to certain orders,