From 86e858af6fa80495483079b5d9d9ad06d6d04ba4 Mon Sep 17 00:00:00 2001 From: Pete Jemian Date: Tue, 10 Dec 2024 15:30:06 -0600 Subject: [PATCH] MNT #14 "cycle" -> "run" --- CHANGES.rst | 19 ++++++++- apsbss/apsbss.adl | 4 +- apsbss/apsbss.db | 2 +- apsbss/apsbss.py | 12 +++--- apsbss/apsbss.ui | 4 +- apsbss/apsbss_makedb.py | 2 +- apsbss/apsbss_ophyd.py | 6 +-- apsbss/server_interface.py | 7 ++-- apsbss/tests/test_apsbss.py | 16 ++++---- apsbss/tests/test_bss_is.py | 4 +- docs/source/_static/apsbss_report.txt | 2 +- docs/source/apsbss.rst | 58 +++++++++++++-------------- docs/source/ioc.rst | 2 +- 13 files changed, 77 insertions(+), 61 deletions(-) diff --git a/CHANGES.rst b/CHANGES.rst index e7eb54f..d33d52f 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -28,19 +28,36 @@ describe the future plans. * Complete overhaul for APS-U era. + Breaking Changes + ---------------- + + * Standardize on **run** instead of **cycle** as the reference used for the + name of an APS operations *run* period. + + * Includes EPICS PV: ``record(stringout, "$(P)esaf:run")`` + New Features ------------ * Add support for direct access to read IS database. + * Add Server class that chooses between DM or IS interface. Maintenance ----------- - * Add requests to project requirements. + * Increased code coverage of unit testing. + * Moved report and table generation to new Server class. + * Refactored (and simplified) IOC report table. + * Relocated functions out of apsbss module. * Switch documentation to use pydata sphinx theme. * Update to install and run with Python versions 3.9, 3.10, 3.11. + Deprecations + ------------- + + * Removed all items marked for deprecation. + ------------- 1.5.6 diff --git a/apsbss/apsbss.adl b/apsbss/apsbss.adl index c8ebe3d..b4e597f 100644 --- a/apsbss/apsbss.adl +++ b/apsbss/apsbss.adl @@ -146,7 +146,7 @@ composite { "basic attribute" { clr=14 } - textix="APS run cycle" + textix="APS run" align="horiz. right" } "text entry" { @@ -157,7 +157,7 @@ composite { height=16 } control { - chan="$(P)esaf:cycle" + chan="$(P)esaf:run" clr=14 bclr=50 } diff --git a/apsbss/apsbss.db b/apsbss/apsbss.db index 6fb8a0a..7e5b9fa 100644 --- a/apsbss/apsbss.db +++ b/apsbss/apsbss.db @@ -27,7 +27,7 @@ record(stringout, "$(P)ioc_host") record(stringout, "$(P)ioc_user") -record(stringout, "$(P)esaf:cycle") +record(stringout, "$(P)esaf:run") record(waveform, "$(P)esaf:description") { field(FTVL, "CHAR") diff --git a/apsbss/apsbss.py b/apsbss/apsbss.py index 783bb31..6bf4029 100755 --- a/apsbss/apsbss.py +++ b/apsbss/apsbss.py @@ -213,8 +213,8 @@ def epicsSetup(prefix, beamline, run=None): Name of beam line (as defined by the BSS) run *str* : - Name of APS run cycle (as defined by the BSS). - optional: default is current APS run cycle name. + Name of APS run (as defined by the BSS). + optional: default is current APS run name. """ bss = connect_epics(prefix) @@ -262,7 +262,7 @@ def get_options(): subcommand.add_parser("beamlines", help="print list of beamlines") - p_sub = subcommand.add_parser("runs", help="print APS run cycle names") + p_sub = subcommand.add_parser("runs", help="print APS run names") p_sub.add_argument( "-f", "--full", @@ -283,7 +283,7 @@ def get_options(): p_sub = subcommand.add_parser("list", help="list by run") msg = ( - "APS run (cycle) name." + "APS run name." " One of the names returned by ``apsbss runs``" " or one of these (``past``, ``prior``, ``previous``)" " for the previous run, (``current`` or ``now``)" @@ -302,7 +302,7 @@ def get_options(): p_sub = subcommand.add_parser("proposal", help="print specific proposal") p_sub.add_argument("proposalId", type=str, help="proposal ID number") - p_sub.add_argument("run", type=str, help="APS run (cycle) name") + p_sub.add_argument("run", type=str, help="APS run name") p_sub.add_argument("beamlineName", type=str, help="Beamline name") p_sub = subcommand.add_parser("clear", help="EPICS PVs: clear") @@ -311,7 +311,7 @@ def get_options(): p_sub = subcommand.add_parser("setup", help="EPICS PVs: setup") p_sub.add_argument("prefix", type=str, help="EPICS PV prefix") p_sub.add_argument("beamlineName", type=str, help="Beamline name") - p_sub.add_argument("run", type=str, help="APS run (cycle) name") + p_sub.add_argument("run", type=str, help="APS run name") p_sub = subcommand.add_parser("update", help="EPICS PVs: update from BSS") p_sub.add_argument("prefix", type=str, help="EPICS PV prefix") diff --git a/apsbss/apsbss.ui b/apsbss/apsbss.ui index d97029c..6c8f4ef 100644 --- a/apsbss/apsbss.ui +++ b/apsbss/apsbss.ui @@ -170,7 +170,7 @@ QPushButton::menu-indicator {image: url(none.png); width: 0} - APS run cycle + APS run ESimpleLabel::WidthAndHeight @@ -200,7 +200,7 @@ QPushButton::menu-indicator {image: url(none.png); width: 0} caLineEdit::WidthAndHeight - $(P)esaf:cycle + $(P)esaf:run diff --git a/apsbss/apsbss_makedb.py b/apsbss/apsbss_makedb.py index 2951fb5..e1c9d46 100755 --- a/apsbss/apsbss_makedb.py +++ b/apsbss/apsbss_makedb.py @@ -26,7 +26,7 @@ status stringout ioc_host stringout ioc_user stringout -esaf:cycle stringout +esaf:run stringout esaf:description waveform 4096 esaf:endDate stringout esaf:id stringout diff --git a/apsbss/apsbss_ophyd.py b/apsbss/apsbss_ophyd.py index fc4ffa6..a47c277 100644 --- a/apsbss/apsbss_ophyd.py +++ b/apsbss/apsbss_ophyd.py @@ -65,7 +65,7 @@ class EpicsEsafDevice(Device): ~clear_users """ - aps_run = Component(EpicsSignal, "cycle", string=True) + aps_run = Component(EpicsSignal, "run", string=True) description = Component(EpicsSignal, "description", string=True) end_date = Component(EpicsSignal, "endDate", string=True) esaf_id = Component(EpicsSignal, "id", string=True) @@ -96,11 +96,11 @@ def clear(self): Do not clear these items: - * ``aps_cycle`` + * ``aps_run`` * ``esaf_id`` * ``sector`` """ - # self.aps_cycle.put("") # user controls this + # self.aps_run.put("") # user controls this self.description.put("") self.end_date.put("") # self.esaf_id.put("") # user controls this diff --git a/apsbss/server_interface.py b/apsbss/server_interface.py index eaab423..637748f 100644 --- a/apsbss/server_interface.py +++ b/apsbss/server_interface.py @@ -223,7 +223,7 @@ def current_esafs_and_proposals(self, beamline, nruns=3) -> dict: beamline : str Canonical name of beam line. nruns : int - Number of APS runs (cycles) to include, optional (default: 3, a one year + Number of APS runs to include, optional (default: 3, a one year period) RETURNS @@ -272,7 +272,7 @@ def current_proposals(self, beamline): @property def current_run(self) -> str: - """Return the name of the current APS run (cycle).""" + """Return the name of the current APS run.""" return self.bss_api.current_run["name"] def esaf(self, esaf_id): @@ -377,8 +377,7 @@ def recent_runs(self, nruns=6) -> list: PARAMETERS nruns : int - Number of APS runs (cycles) to include, optional (default: 6, a two year - period) + Number of APS run to include, optional (default: 6, a two year period) """ runs = self.runs return sorted(runs[: 1 + runs.index(self.current_run)], reverse=True)[:nruns] diff --git a/apsbss/tests/test_apsbss.py b/apsbss/tests/test_apsbss.py index 406fbe7..7e15809 100644 --- a/apsbss/tests/test_apsbss.py +++ b/apsbss/tests/test_apsbss.py @@ -52,9 +52,9 @@ def using_APS_workstation(): @pytest.fixture(scope="function") def bss_PV(): # try connecting with one of the PVs in the database - cycle = epics.PV(f"{BSS_TEST_IOC_PREFIX}esaf:cycle") - cycle.wait_for_connection(timeout=2) - return cycle + run = epics.PV(f"{BSS_TEST_IOC_PREFIX}esaf:run") + run.wait_for_connection(timeout=2) + return run def test_general(): @@ -141,7 +141,7 @@ def test_ioc(ioc, bss_PV): assert ioc.bss.connected assert ioc.bss.esaf.title.get() == "" assert ioc.bss.esaf.description.get() == "" - # assert ioc.bss.esaf.aps_cycle.get() == "" + # assert ioc.bss.esaf.aps_run.get() == "" def test_EPICS(ioc, bss_PV): @@ -150,7 +150,7 @@ def test_EPICS(ioc, bss_PV): return beamline = "9-ID-B,C" - cycle = "2019-3" + run = "2019-3" ioc.bss = apsbss.connect_epics(BSS_TEST_IOC_PREFIX) assert ioc.bss.connected @@ -162,11 +162,11 @@ def test_EPICS(ioc, bss_PV): return # setup - apsbss.epicsSetup(BSS_TEST_IOC_PREFIX, beamline, cycle) + apsbss.epicsSetup(BSS_TEST_IOC_PREFIX, beamline, run) assert ioc.bss.proposal.beamline_name.get() != "harpo" assert ioc.bss.proposal.beamline_name.get() == beamline - assert ioc.bss.esaf.aps_run.get() == cycle + assert ioc.bss.esaf.aps_run.get() == run assert ioc.bss.esaf.sector.get() == beamline.split("-")[0] # epicsUpdate @@ -179,7 +179,7 @@ def test_EPICS(ioc, bss_PV): # ====== ======== ========== ========== ==================== ================================= # ===== ====== =================== ==================== ======================================== - # id cycle date user(s) title + # id run date user(s) title # ===== ====== =================== ==================== ======================================== # 64629 2019-2 2019-03-01 18:35:02 Ilavsky,Okasinski 2019 National School on Neutron & X-r... # ===== ====== =================== ==================== ======================================== diff --git a/apsbss/tests/test_bss_is.py b/apsbss/tests/test_bss_is.py index 14a2b6c..fe04e03 100644 --- a/apsbss/tests/test_bss_is.py +++ b/apsbss/tests/test_bss_is.py @@ -148,7 +148,7 @@ def test_SchedulingServer(): return # Can't test anything here. ss.auth_from_file(CREDS_FILE) - assert len(ss.runs) > 40 # more than 40 run cycles in the database + assert len(ss.runs) > 40 # more than 40 runs in the database run = ss.current_run assert isinstance(run, dict) @@ -189,7 +189,7 @@ def test_beamlines(beamline, run, expected): return # Can't test anything here. ss.auth_from_file(CREDS_FILE) - assert len(ss.runs) > 40 # more than 40 run cycles in the database + assert len(ss.runs) > 40 # more than 40 runs in the database assert beamline in ss.beamlines diff --git a/docs/source/_static/apsbss_report.txt b/docs/source/_static/apsbss_report.txt index e47d7ef..9e7e640 100644 --- a/docs/source/_static/apsbss_report.txt +++ b/docs/source/_static/apsbss_report.txt @@ -2,7 +2,7 @@ connected in 0.108s ============================= ================================== =========================================================================================================================================================================================================================================================================================================== name PV reference value ============================= ================================== =========================================================================================================================================================================================================================================================================================================== -esaf.aps_cycle 9id:bss:esaf:cycle 2019-2 +esaf.aps_run 9id:bss:esaf:run 2019-2 esaf.description 9id:bss:esaf:description We will commission beamline and USAXS instrument. We will perform experiments with safe beamline standards and test samples (all located at beamline and used for this purpose routinely) to evaluate performance of beamline and instrument. We will perform hardware and software development as needed. esaf.end_date 9id:bss:esaf:endDate 2020-09-28 08:00:00 esaf.esaf_id 9id:bss:esaf:id 226319 diff --git a/docs/source/apsbss.rst b/docs/source/apsbss.rst index 0eafb1a..5c0b60d 100644 --- a/docs/source/apsbss.rst +++ b/docs/source/apsbss.rst @@ -29,7 +29,7 @@ databases from this software.* Given: * a beam line name (such as ``9-ID-B,C``) -* APS run cycle name (such as ``2019-2``) to locate a specific proposal ID +* APS run name (such as ``2019-2``) to locate a specific proposal ID * proposal ID number (such as ``66083``) * ESAF ID number (such as ``226319``) @@ -55,25 +55,25 @@ We'll demonstrate ``apsbss`` with information for APS beam line 9-ID, using PV prefix ``9id:bss:``. #. Create the PVs in an EPICS IOC (see section :ref:`apsbss_ioc`) -#. Initialize PVs with beam line name and APS run cycle number +#. Initialize PVs with beam line name and APS run number #. Set PVs with the Proposal and ESAF ID numbers #. Retrieve (& update PVs) information from APS databases -**Enter beam line and APS run (cycle) info** +**Enter beam line and APS run info** .. figure:: ./_static//ui_initialized.png :width: 95% Image of ``apsbss.ui`` screen GUI in caQtDM showing PV prefix - (``9id:bss:``), APS run cycle ``2019-2`` and beam line ``9-ID-B,C``. + (``9id:bss:``), APS run ``2019-2`` and beam line ``9-ID-B,C``. * beam line name PV: ``9id:bss:proposal:beamline`` - * APS run cycle PV: ``9id:bss:esaf:cycle`` + * APS run PV: ``9id:bss:esaf:run`` **Enter Proposal and ESAF ID numbers** -Note we had to use the APS run cycle of `2019-2` +Note we had to use the APS run of `2019-2` to match what is in the proposal's information. .. figure:: ./_static//ui_id_entered.png @@ -106,12 +106,12 @@ To clear the PVs, in the GUI, press the button labeled ``clear PVs``. This button executes the command line: ``apsbss clear 9id:bss:`` -Initialize PVs for beam line and APC run cycle +Initialize PVs for beam line and APC run ++++++++++++++++++++++++++++++++++++++++++++++ After creating the PVs in an IOC, the next step is to initialize them with the beam line name and the APS -run cycle name. Both of these must match exactly +run name. Both of these must match exactly with values known in the data management (``dm``) system. For any of these commands, you must know the EPICS @@ -149,13 +149,13 @@ To learn the beam line names accepted by the system, use this command For either station at 9-ID, use ``9-ID-B,C``. -What APS run cycle to use? +What APS run to use? ^^^^^^^^^^^^^^^^^^^^^^^^^^ -To learn the APS run cycle names accepted by the system, use this command -(showing APS run cycle names as defined on 2020-07-10):: +To learn the APS run names accepted by the system, use this command +(showing APS run names as defined on 2020-07-10):: - $ apsbss cycles + $ apsbss runs 2008-3 2011-2 2014-1 2016-3 2019-2 2009-1 2011-3 2014-2 2017-1 2019-3 2009-2 2012-1 2014-3 2017-2 2020-1 @@ -165,13 +165,13 @@ To learn the APS run cycle names accepted by the system, use this command 2010-3 2013-2 2016-1 2018-3 2011-1 2013-3 2016-2 2019-1 -Pick the cycle of interest. Here, we pick ``2020-2``. +Pick the run of interest. Here, we pick ``2020-2``. -To print the full report (including start and end of each cycle):: +To print the full report (including start and end of each run):: - $ apsbss cycles --full + $ apsbss runs --full ====== =================== =================== - cycle start end + run start end ====== =================== =================== 2020-2 2020-06-09 07:00:00 2020-10-01 07:00:00 2020-1 2020-01-28 08:00:00 2020-06-09 07:00:00 @@ -212,16 +212,16 @@ To print the full report (including start and end of each cycle):: ====== =================== =================== -Write the beam line name and cycle to the PVs +Write the beam line name and run to the PVs ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ To configure ``9id:bss:`` PVs for beam line -``9-ID-B,C`` and cycle ``2020-2``, +``9-ID-B,C`` and run ``2020-2``, use this command:: $ apsbss setup 9id:bss: 9-ID-B,C 2020-2 connected in 0.143s - setup EPICS 9id:bss: 9-ID-B,C cycle=2020-2 sector=9 + setup EPICS 9id:bss: 9-ID-B,C run=2020-2 sector=9 Or you could enter them into the appropriate boxes on the GUI. @@ -233,13 +233,13 @@ Proposals are usually valid for two years. To learn what proposals are valid for your beam line, use this command with your own beam line's name. The report will provide two tables, one for Proposals and the other for ESAFs, -both with entries in the current APS run cycle:: +both with entries in the current APS run:: $ apsbss list 9-ID-B,C - Proposal(s): beam line 9-ID-B,C, cycle(s) now + Proposal(s): beam line 9-ID-B,C, run(s) now ===== ====== =================== =================== ==================== ======================================== - id cycle start end user(s) title + id run start end user(s) title ===== ====== =================== =================== ==================== ======================================== 70118 2020-3 2020-12-05 08:00:00 2020-12-05 16:00:00 Beaucage,Gogia,Ku... In situ structural modification and d... 63765 2020-3 2020-11-19 08:00:00 2020-11-23 08:00:00 Swantek,Powell,Ka... USAXS Measurements of Fuel Injection ... @@ -253,7 +253,7 @@ both with entries in the current APS run cycle:: 71891 2020-3 2020-10-05 07:00:00 2020-10-09 07:00:00 Ralle,Chen Copper Distribution in Cyrptococcus N... ===== ====== =================== =================== ==================== ======================================== - ESAF(s): sector 9, cycle(s) now + ESAF(s): sector 9, run(s) now ====== ======== ========== ========== ==================== ======================================== id status start end user(s) title @@ -292,7 +292,7 @@ View Proposal Information To view information about a specific proposal, you must be able to provide the proposal's ID number and -the APS run cycle name. +the APS run name. :: @@ -377,7 +377,7 @@ Update EPICS PVs with Proposal and ESAF To update the PVs with Proposal and Information from the APS database, first enter the proposal and ESAF ID numbers into the GUI (or set the ``9id:bss:proposal:id``, and respectively). -Note that for this ESAF ID, we had to change the cycle to `2019-2`. +Note that for this ESAF ID, we had to change the run to `2019-2`. Then, use this command to retrieve the information and update the PVs:: @@ -427,7 +427,7 @@ the *apsbss* application expects:: $ apsbss -h usage: apsbss [-h] [-v] - {beamlines,current,cycles,esaf,list,proposal,clear,setup,update,report} + {beamlines,current,runs,esaf,list,proposal,clear,setup,update,report} ... Retrieve specific records from the APS Proposal and ESAF databases. @@ -437,12 +437,12 @@ the *apsbss* application expects:: -v, --version print version number and exit subcommand: - {beamlines,current,cycles,esaf,proposal,clear,setup,update,report} + {beamlines,current,runs,esaf,proposal,clear,setup,update,report} beamlines print list of beamlines current print current ESAF(s) and proposal(s), DEPRECATED: use 'list' instead - cycles print APS run cycle names + runs print APS run names esaf print specific ESAF - list list by cycle + list list by run proposal print specific proposal clear EPICS PVs: clear setup EPICS PVs: setup diff --git a/docs/source/ioc.rst b/docs/source/ioc.rst index 6058ff0..751a517 100644 --- a/docs/source/ioc.rst +++ b/docs/source/ioc.rst @@ -22,7 +22,7 @@ Overview -------- #. Create the PVs in an EPICS IOC -#. Initialize PVs with beam line name and APS run cycle number +#. Initialize PVs with beam line name and APS run number #. Set PV with the Proposal ID number #. Set PV with the ESAF ID number #. Retrieve (& update PVs) information from APS databases