Improve NI-DAQmx docs a little.

Author: dihm

docs/source/devices/ni_daqs.rst

@@ -17,16 +17,19 @@ The python bindings are provided by the PyDAQmx package, available through pip.
 Adding a Device
 ~~~~~~~~~~~~~~~
 
-While the `NI_DAQmx` device can be used directly by manually specifying the many necessary parameters, it is preferable to add the device via an appropriate subclass. This process is greatly simplified by using the `get_capabilities.py` script.
+While the `NI_DAQmx` device can be used directly by manually specifying the many necessary parameters, 
+it is preferable to add the device via an appropriate subclass. 
+This process is greatly simplified by using the :mod:`get_capabilities.py <labscript_devices.NI_DAQmx.models.get_capabilities>` script
+followed by the :mod:`generate_subclasses.py <labscript_devices.NI_DAQmx.models.generate_subclasses>` script.
 
 To add support for a DAQmx device that is not yet supported, run `get_capabilities.py` on
 a computer with the device in question connected (or with a simulated device of the
 correct model configured in NI-MAX). This will introspect the capabilities of the device
-and add those details to capabilities.json. To generate labscript device classes for all
-devices whose capabilities are known, run `generate_classes.py`. Subclasses of NI_DAQmx
+and add those details to `capabilities.json`. To generate labscript device classes for all
+devices whose capabilities are known, run `generate_subclasses.py`. Subclasses of NI_DAQmx
 will be made in the `models` subfolder, and they can then be imported into labscript code with:
 
-..code-block:: python
+.. code-block:: python
 
 	from labscript_devices.NI_DAQmx.labscript_devices import NI_PCIe_6363
 

labscript_devices/NI_DAQmx/labscript_devices.py

@@ -106,7 +106,52 @@ def __init__(
         supports_semiperiod_measurement=False,
         **kwargs
     ):
-        """Generic class for NI_DAQmx devices."""
+        """Generic class for NI_DAQmx devices.
+
+        Generally over-ridden by device-specific subclasses that contain
+        the introspected default values.
+
+        Args:
+            name (str): name to assign to the created labscript device
+            parent_device (clockline): Parent clockline device that will
+                clock the outputs of this device
+            clock_terminal (str): What input on the DAQ is used for the clockline
+            MAX_name (str): NI-MAX device name
+            static_AO (int, optional): Number of static analog output channels.
+            static_DO (int, optional): Number of static digital output channels.
+            clock_mirror_terminal (str, optional): Channel string of digital output
+                that mirrors the input clock. Useful for daisy-chaning DAQs on the same
+                clockline.
+            acquisiton_rate (float, optional): Default sample rate of inputs.
+            AI_range (iterable, optional): A `[Vmin, Vmax]` pair that sets the analog
+                input voltage range for all analog inputs.
+            AI_start_delay (float, optional): Time in seconds between start of an
+                analog input task starting and the first sample.
+            AO_range (iterable, optional): A `[Vmin, Vmax]` pair that sets the analog
+                output voltage range for all analog outputs.
+            max_AI_multi_chan_rate (float, optional): Max supported analog input 
+                sampling rate when using multiple channels.
+            max_AI_single_chan_rate (float, optional): Max supported analog input
+                sampling rate when only using a single channel.
+            max_AO_sample_rate (float, optional): Max supported analog output
+                sample rate.
+            max_DO_sample_rate (float, optional): Max supported digital output
+                sample rate.
+            min_sermiperiod_measurement (float, optional): Minimum measurable time
+                for a semiperiod measurement.
+            num_AI (int, optional): Number of analog inputs channels.
+            num_AO (int, optional): Number of analog output channels.
+            num_CI (int, optional): Number of counter input channels.
+            ports (dict, optional): Dictionarly of DIO ports, which number of lines
+                and whether port supports buffered output.
+            supports_buffered_AO (bool, optional): True if analog outputs support
+                buffered output
+            supports_buffered_DO (bool, optional): True if digital outputs support
+                buffered output
+            supports_semiperiod_measurement (bool, optional): True if deviec supports
+                semi-period measurements
+
+        """
 
         # Default static output setting based on whether the device supports buffered
         # output:
@@ -169,8 +214,8 @@ def __init__(
 
         self.wait_monitor_minimum_pulse_width = self.min_semiperiod_measurement
 
-        # Set allowed children based on capabilities:
         self.allowed_children = []
+        '''Sets the allowed children types based on the capabilites.'''
         if self.num_AI > 0:
             self.allowed_children += [AnalogIn]
         if self.num_AO > 0 and static_AO:
@@ -198,7 +243,13 @@ def __init__(
         IntermediateDevice.__init__(self, name, parent_device, **kwargs)
 
     def add_device(self, device):
-        """Error checking for adding a child device"""
+        """Error checking for adding a child device.
+
+        Args:
+            device (labscript device): Child labscript device to
+                attach to this device. Only types of devices in :obj:`allowed_children`
+                can be attached.
+        """
         # Verify static/dynamic outputs compatible with configuration:
         if isinstance(device, StaticAnalogOut) and not self.static_AO:
             msg = """Cannot add StaticAnalogOut to NI_DAQmx device configured for
@@ -293,6 +344,7 @@ def _check_bounds(self, analogs):
             np.clip(output.raw_output, vmin, vmax, out=output.raw_output)
 
     def _check_AI_not_too_fast(self, AI_table):
+        """Check that analog input acquisition rates do not exceed maximums."""
         if AI_table is None:
             return
         n = len(set(AI_table['connection']))
@@ -442,6 +494,14 @@ def _check_wait_monitor_timeout_device_config(self):
             raise RuntimeError(dedent(msg))
 
     def generate_code(self, hdf5_file):
+        """Generates the hardware code from the script and saves it to the
+        shot h5 file.
+
+        This is called automatically when a shot is compiled.
+
+        Args:
+            hdf5_file (str): Path to shot's hdf5 file to save the instructions to.
+        """
         IntermediateDevice.generate_code(self, hdf5_file)
         analogs = {}
         digitals = {}

labscript_devices/NI_DAQmx/models/generate_subclasses.py

@@ -10,6 +10,16 @@
 # file in the root of the project for the full license.             #
 #                                                                   #
 #####################################################################
+"""Reads the capabilities file and generates labscript devices
+for each known model of DAQ.
+
+Called from the command line via
+
+.. code-block:: shell
+
+    python generate_subclasses.py
+
+"""
 import os
 import warnings
 import json
@@ -23,7 +33,12 @@
 
 
 def reformat_files(filepaths):
-    """Apply black formatter to a list of source files"""
+    """Apply `black <https://black.readthedocs.io/en/stable/>`_ 
+    formatter to a list of source files.
+    
+    Args:
+        filepaths (list): List of python source files to format.
+    """
     try:
         import black
     except ImportError:
@@ -42,6 +57,11 @@ def reformat_files(filepaths):
 
 
 def main():
+    """Called when the script is run.
+
+    Will attempt to reformat the generated files using
+    :func:`reformat_files`.
+    """
     capabilities = {}
     if os.path.exists(CAPABILITIES_FILE):
         with open(CAPABILITIES_FILE) as f:

labscript_devices/NI_DAQmx/models/get_capabilities.py

@@ -10,6 +10,20 @@
 # file in the root of the project for the full license.             #
 #                                                                   #
 #####################################################################
+"""This is a script to update `model_capabilities.json` with the capabilities of all
+NI-DAQmx devices currently connected to this computer. 
+
+Run this script to add support for a new model of NI-DAQmx device. 
+Note that this will work with a simulated device configured through NI-MAX as well, 
+so support can be added without actually having the physical device.
+
+Called from the command line via
+
+.. code-block:: shell
+
+    python get_capabilities.py
+
+"""
 
 import numpy as np
 import os
@@ -24,14 +38,15 @@
 CAPABILITIES_FILE = os.path.join(THIS_FOLDER, 'capabilities.json')
 
 
-"""This is a script to update model_capabilities.json with the capabilities of all
-NI-DAQmx devices currently connected to this computer. Run this script to add support
-for a new model of NI-DAQmx device. Note that this will work with a simulated device
-configured through NI-MAX as well, so support can be added without actually having the
-physical device"""
+def string_prop(func):
+    """String property wrapper.
 
+    Args:
+        func (function): PyDAQmx library function that returns a string.
 
-def string_prop(func):
+    Returns:
+        function: The wrapped function. 
+    """
     def wrapped(name=None):
         BUFSIZE = 4096
         result = ctypes.create_string_buffer(BUFSIZE)
@@ -45,6 +60,14 @@ def wrapped(name=None):
 
 
 def bool_prop(func):
+    """Bool property wrapper.
+
+    Args:
+        func (function): PyDAQmx library function that returns a boolean.
+
+    Returns:
+        function: The wrapped function. 
+    """
     def wrapped(name):
         result = bool32()
         func(name, byref(result))
@@ -54,6 +77,14 @@ def wrapped(name):
 
 
 def int32_prop(func):
+    """Int32 property wrapper.
+
+    Args:
+        func (function): PyDAQmx library function that returns a int32.
+
+    Returns:
+        function: The wrapped function. 
+    """
     def wrapped(name):
         result = int32()
         func(name, byref(result))
@@ -63,6 +94,14 @@ def wrapped(name):
 
 
 def float64_prop(func):
+    """Float property wrapper.
+
+    Args:
+        func (function): PyDAQmx library function that returns a float64.
+
+    Returns:
+        function: The wrapped function. 
+    """
     def wrapped(name):
         result = float64()
         func(name, byref(result))
@@ -72,6 +111,15 @@ def wrapped(name):
 
 
 def float64_array_prop(func):
+    """Array of floats property wrapper.
+
+    Args:
+        func (function): PyDAQmx library function that returns an array of
+            float64s.
+
+    Returns:
+        function: The wrapped function. 
+    """
     def wrapped(name):
         import warnings
 
@@ -91,8 +139,15 @@ def wrapped(name):
 
 
 def chans(func):
-    """string_prop but splitting the return value into separate channels and stripping
-    the device name from them"""
+    """string_prop but splitting the return value into separate channels 
+    and stripping the device name from them
+
+    Args:
+        func (function): PyDAQmx library function that returns channel string.
+
+    Returns:
+        function: The wrapped function.
+    """
     wrapped1 = string_prop(func)
 
     def wrapped2(name):
@@ -126,6 +181,16 @@ def wrapped2(name):
 
 
 def port_supports_buffered(device_name, port, clock_terminal=None):
+    """Empirically determines if the digital port supports buffered output.
+
+    Args:
+        device_name (str): NI-MAX device name
+        port (int): Which port to intro-spect
+        clock_terminal (str, optional): String that specifies the clock terminal.
+
+    Returns:
+        bool: True if `port` supports buffered output.
+    """
     all_terminals = DAQmxGetDevTerminals(device_name)
     if clock_terminal is None:
         clock_terminal = all_terminals[0]
@@ -170,6 +235,15 @@ def port_supports_buffered(device_name, port, clock_terminal=None):
 
 
 def AI_start_delay(device_name):
+    """Empirically determines the analog inputs' start delay.
+
+    Args:
+        device_name (str): NI-MAX device name
+
+    Returns:
+        float: Analog input start delay in seconds. `None` if
+        analog inputs not supported.
+    """
     if 'PFI0' not in DAQmxGetDevTerminals(device_name):
         return None
     task = Task()
@@ -202,9 +276,19 @@ def AI_start_delay(device_name):
 
 
 def supported_AI_ranges_for_non_differential_input(device_name, AI_ranges):
-    """Try AI ranges to see which are actually allowed for non-differential input, since
+    """Empirically determine the analog input voltage ranges for non-differential inputs.
+
+    Tries AI ranges to see which are actually allowed for non-differential input, since
     the largest range may only be available for differential input, which we don't
-    attempt to support (though we could with a little effort)"""
+    attempt to support (though we could with a little effort).
+
+    Args:
+        device_name (str): NI-MAX device name
+        AI_ranges (list): list of `[Vmin, Vmax]` pairs to check compatibility.
+
+    Returns:
+        list: List of lists with the supported voltage ranges.        
+    """
     chan = device_name + '/ai0'
     supported_ranges = []
     for Vmin, Vmax in AI_ranges:
@@ -227,6 +311,14 @@ def supported_AI_ranges_for_non_differential_input(device_name, AI_ranges):
 
 
 def supports_semiperiod_measurement(device_name):
+    """Empirically determines if the DAQ supports semiperiod measurement.
+
+    Args:
+        device_name (str): NI-MAX device name.
+
+    Returns:
+        bool: True if semi-period measurements are supported by the device.
+    """
     import warnings
 
     with warnings.catch_warnings():
@@ -242,7 +334,9 @@ def supports_semiperiod_measurement(device_name):
 
 
 def get_min_semiperiod_measurement(device_name):
-    """Depending on the timebase used, counter inputs can measure time intervals of
+    """Determines the minimum semi-period measurement time supported by the device.
+
+    Depending on the timebase used, counter inputs can measure time intervals of
     various ranges. As a default, we pick a largish range - the one with the fastest
     timebase still capable of measuring 100 seconds, or the largest time interval if it
     is less than 100 seconds, and we save the smallest interval measurable with this
@@ -258,7 +352,14 @@ def get_min_semiperiod_measurement(device_name):
     possibility of timing out. For now (in the wait monitor worker class) we
     pessimistically add one second to the expected longest measurement to account for
     software delays. These decisions can be revisited if there is a need, do not
-    hesitate to file an issue on bitbucket regarding this if it affects you."""
+    hesitate to file an issue on bitbucket regarding this if it affects you.
+
+    Args:
+        device_name (str): NI-MAX device name
+
+    Returns:
+        float: Minimum measurement time.
+    """
     CI_chans = DAQmxGetDevCIPhysicalChans(device_name)
     CI_chan = device_name + '/' + CI_chans[0]
     # Make a task with a semiperiod measurement