MNT #14 "cycle" -> "run"

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

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
 			}

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")

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")

apsbss/apsbss.ui

@@ -170,7 +170,7 @@ QPushButton::menu-indicator {image: url(none.png); width: 0}
                     </color>
                 </property>
                 <property name="text">
-                    <string>APS run cycle</string>
+                    <string>APS run</string>
                 </property>
                 <property name="fontScaleMode">
                     <enum>ESimpleLabel::WidthAndHeight</enum>
@@ -200,7 +200,7 @@ QPushButton::menu-indicator {image: url(none.png); width: 0}
                     <enum>caLineEdit::WidthAndHeight</enum>
                 </property>
                 <property name="channel">
-                    <string>$(P)esaf:cycle</string>
+                    <string>$(P)esaf:run</string>
                 </property>
                 <property name="foreground">
                     <color alpha="255">

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

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

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]

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...
     # ===== ====== =================== ==================== ========================================

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
 

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