added code preference

doc/source/csst_common/example_interface.py

@@ -98,7 +98,7 @@ def process_single_image(
 
 # process multiple images in an exposure (RECOMMENDED, at least for MBI or SLS)
 # define a single job
-def one_job(dm, detector):
+def one_job(dm: CsstMsDataManager, detector: int):
     """ Process a single image, defined for parallel processing. """
     filepath_input = dm.l0_detector(detector=detector)
     filepath_output = dm.l1_detector(detector=detector, post="L1_processed.fits")
@@ -108,7 +108,7 @@ def one_job(dm, detector):
     return
 
 
-# parallel processing jobs
+# process in serial / parallel
 def process_multiple_images(
         dm: CsstMsDataManager,
         logger: Union[None, logging.Logger] = None,

doc/source/index.rst

@@ -62,7 +62,7 @@ The guide for LSST developers
    vcs.rst
    packaging.rst
    codestyle.rst
-   packages/packages.rst
+   preference/preference.rst
    unittest.rst
    simulation.rst
    csst_common/csst_common.rst

doc/source/packages/packages.rst → doc/source/preference/preference.rst

-Package preference
-==================
+Code Preference
+===============
 
 Initially we want our developers to following the
 `coding guidelines for astropy-affiliated packages <https://docs.astropy.org/en/latest/development/codeguide.html>`_
 as much as possible.
 A few important conventions and special cases should be outlined here.
 
-Basic preference
-----------------
+Package preference
+------------------
 
 Several packages are favored over others if they can be used to solve the problem under study.
 Developers should use them as much as possible.
@@ -66,3 +66,50 @@ The output is
 
 For parallel computing with inter-communication or distributed computing,
 we recommend developers to consider using ``mpi4py``: https://github.com/mpi4py/mpi4py.
+
+
+Global variables
+----------------
+
+Usage of ``global`` should be prohibited.
+In most cases, variables should be kept in their default scopes.
+
+Using ``subprocess``
+--------------------
+
+``subprocess.run()`` is favored over ``subprocess.Popen()`` and ``os.system()`` as suggested in Python documentation:
+
+- The ``subprocess`` module allows you to spawn new processes, connect to their input/output/error pipes,
+  and obtain their return codes. This module intends to replace several older modules and functions:
+
+  .. code-block:: python
+
+     os.system
+     os.spawn*
+
+- The recommended approach to invoking ``subprocesses`` is to use the ``run()`` function for all use cases
+  it can handle. For more advanced use cases, the underlying ``Popen`` interface can be used directly.
+
+
+Numpy multithreading
+--------------------
+
+Numpy sometime automatically uses multithreading. To see if you are actually using OpenBLAS or MKL, use
+
+.. code-block:: python
+
+    numpy.__config__.show()
+
+To set shut down this feature, use
+
+.. code-block:: python
+
+    export MKL_NUM_THREADS=1
+    export NUMEXPR_NUM_THREADS=1
+    export OMP_NUM_THREADS=1
+    export VECLIB_MAXIMUM_THREADS=1
+
+.. note::
+    In most cases, this automatic multithreading does not enhance the performance in practice.
+    Therefore, the above setting will be used in CSST pipeline globally.
+