New API

[jacobfeder]

Hey everyone, Jacob and Michael here. We've been discussing the redesign of the nspyre API and thinking about what an ideal interface would look like. Below we've provided a toy example to demonstrate what we have envisioned and would like everyone's feedback, especially because this is the part of nspyre that you - the user - will be interacting with daily for experiments. If you have any ideas, questions, or comments you can just post them below. (TLDR at the bottom.)

Spyrelets

Let's say we need to write a script to take ODMR measurements and we would like to use its functionality in a Jupyter notebook, a standalone GUI, or part of the larger integrated NSpyre GUI combining a number of different measurements and hardware control. Our file to do this, odmr.py, looks like this:

# odmr.py
import json
import nspyre
import numpy as np

from PySide6.QtWidgets import QWidget, QPushButton, QVBoxLayout


class ODMR:
    def __init__(self, sg, daq):
        """For running an ODMR PL scan"""
        # signal generator
        self.sg = sg
        # data acquisition system
        self.daq = daq

    def sweep(self, start: float, stop: float, num_points: int) -> np.ndarray:
        """Run an ODMR sweep over a set of frequencies.
        Args:
            start (float): start frequency
            stop (float): stop frequency
            num_points (int): number of points between start-stop (inclusive)

        Returns:
            An array of PL counts over the ODMR spectrum.
        """

        # frequencies that will be swept over in the ODMR measurement, which is 
        # created as a numpy ndarray using shared memory for efficiently
        # sharing data between processes; note the fixed size
        self.frequencies = nspyre.datatype('ndarray', 'frequencies', dtype=np.int32, shape=(num_points),
                                           usage='complete', dataset='ODMR')
        self.frequencies[:] = np.linspace(start, stop, num_points)

        # photon counts corresponding to each frequency; note the fixed size
        self.counts = nspyre.datatype('ndarray', 'counts', dtype=np.int32, shape=(len(self.frequencies)),
                                      usage='complete', dataset='ODMR')

        # implement counts as a normal list, of variable length and
        # tell nspyre to keep track of it as part of the 'ODMR' dataset
        # (do not get the performance improvements of shared memory)
        self.custom_counts = []
        nspyre.datatype('custom', 'counts2', self.custom_counts, dataset='ODMR')

        for i, freq in enumerate(self.frequencies):
            # access the signal generator driver on the instrument server and set its frequency
            self.sg.set_freq(freq)
            # read the number of photon counts received by the DAQ
            self.counts[i] = self.daq.read()
            self.custom_counts.append(self.daq.read())  # alternative if a custom datatype is desired
            # tell the data server to publish any new data in the 'ODMR' dataset (since the last call) to
            # all subscribed clients, such as any View Managers connected
            nspyre.data_pub('ODMR')
        return counts

    def save(self, *args, **kwargs):
        """Wrapper for nspyre save functionality"""
        nspyre.save(dataset='ODMR', file_name='NV_sample_ODMR', path='C:/user/data', overwrite=True)

    def custom_save(self, file):
        """Retrieve data from the underlying DataServer manually and save it as a JSON file"""
        data = nspyre.data_pull('ODMR')
        json.dump({'f' : data.frequencies, 'c' : data.counts}, file)

    @nspyre.plotting('2D')
    def plot_function(self, *args, **kwargs):
        """Defines the plotting function to use for displaying the ODMR data."""
        return (self.frequencies, self.counts)


class WidgetODMR(QWidget):
    """Qt window class that contains a set of boxes for the user to enter the experimental
    parameters, and a button that runs an ODMR scan.
    """

    def __init__(self, primary_gateway, secondary_gateway=None, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self.setWindowTitle('ODMR GUI')
        # connection to the instrument servers
        self.isg = primary_gateway
        self.daq = self.isg.daq
        # sometimes the signal generator is on a different server
        if secondary_gateway:
            self.secondary_isg = secondary_gateway
            self.sg = self.secondary_isg.sg
        else:
            self.sg = self.isg.sg

        # create an instance of the ODMR class that will run our experiment
        self.odmr = ODMR(self.sg, self.daq)

        # we just want a generic spyrelet UI, so tell nspyre the parameters needed
        # to create the Qt widgets as a dictionary
        self.params = {'start': float, 'stop': float, 'num_points': int}
        self.params_widget = nspyre.generate_generic_UI(self.params)

        # Qt button widget that takes an ODMR scan when clicked
        button = QPushButton('Run ODMR Sweep')
        button.clicked.connect(lambda: self.odmr.sweep(
                                               self.params_widget.start,
                                               self.params_widget.stop,
                                               self.params_widget.num_points))

        # Qt layout that arranges the params and button vertically
        layout = QVBoxLayout()
        layout.addWidget(self.params_widget)
        layout.addWidget(button)
        self.setLayout(layout)


if __name__ ==  '__main__':
    import logging
    import sys

    import nspyre
    from nspyre.gui import NSpyreApp, NSpyreSDI, set_qapp_defaults
    from nspyre.logging import nspyre_init_logger

    from .setup.inserv import start_server_check

    nspyre_init_logger(logging.INFO)
    logger.info('starting MySpyrelet GUI...')

    set_qapp_defaults()
    app = NSpyreApp([sys.argv])
    # check if server needs to be started and open a gateway connection
    # (see Instrument Server section below for more details)
    start_server_check()
    with open_gateway('my_server', launch_inserv_mgr=True) as isg:
        ODMR_widget = WidgetODMR(isg)
        spyrelet_window = NSpyreSDI(central_widget=ODMR_widget)
        app.exec()
    sys.exit()

Structuring our code in this way provides a number of benefits and the maximum flexibility in how measurements are run. We found a lot of people were confused by the format of the previous Spyrelet class, which severely limits how experiments are structured. The new format does not place any restrictions on how experiments are written or run and our simple file above provides multiple modes of operation.

Simply executing the script as python odmr.py will launch an NSpyre GUI application with our WidgetODMR class displayed. It checks if the Instrument Server is running and start the server if necessary. Additionally, the Instrument Manager GUI can be launched automatically if it is not running. This is the easiest way to take a measurement quickly. No more opening three consoles just to get everything started; this is all taken care of for you. You may have also noticed that a client configuration file is no longer needed to run a spyrelet. The ODMR data is directly available for you to manipulate and save how you please (if you don't want to use nspyre's built-in methods, although they are being revamped). If you want to use this ODMR functionality in a Jupyter notebook, you can do so directly, all you need is a gateway connection and you can use it directly as before:

import nspyre
from .measurements.odmr import ODMR

isg = nspyre.open_gateway()  # passing no connect settings assumes localhost and defaults
odmr = ODMR(isg.sg, isg.daq)
...
isg.close()

Finally, if you have multiple 'pieces' of code to which it is necessary to have simultaneous access and/or would like to combine custom and generic UIs, this is possible by passing nspyre the WidgetODMR class. For example, say you have two spyrelets you need to have access to for measurements. In addition, you would like a live camera feed for imaging and a set of custom UI controls you've written for moving your objective and sample stages. As long as each of these pieces is a QWidget class (notice the WidgetODMR class is such an example), you can add each of these to your local nspyre directory of available spyrelets and on startup of the NSpyre GUI select the desired pieces to load a custom UI. Each spyrelet is resizable, minimizable, and independent of the others. You can even save these configurations as a template to load from the startup menu for future ease of use. (You'll just have to trust us on this claim, no fancy example images here.)

Visualizing Data

One feature that is wrapped up in all these changes but is not apparent from the above code if how nspyre handles data. Gone is MongoDB and in its place is a lightweight data server for providing real-time data to any connected clients. The lightweight implementation means NSpyre handles connections in the background, which is why in the code above, the only lines related to this are the calls to nspyre.datatype and nspyre.data_pub. For localhost clients, this means the data is passed directly to the client, such as a View Manager. For remote clients, this means the data is as real to time as it gets. Multiple people can easily view the same data in real-time on different machines on different networks; no more screen sharing a zoom call to work on things together. This will be particularly useful for the eventual long distance entanglement experiments between labs. Finally, the View Manager UI is being revamped to allow for the visualization of multiple datasets at once.

Instrument Server

For the Instrument Server, the current methods for configuring, starting, and interfacing will persist, with two exceptions. First, the server will be spawned as a daemon process detached from any shell/process from which it is started. The benefit of running the server as a background process is that simply exiting out of the startup console or command line interface will not stop the server. Secondly, new convenience functions will be added to allow for the creation and modification of servers within a script. The server can now be configured entirely from a python script. Finally, drivers no longer have to be written in Lantz and can be arbitrary class objects. The proposed interface looks as such:

# ~/setup/inserv.py
import nspyre

IP = 127.0.0.1
PORT = 5556

def start_server_check():  # the convenience function used above
    # check if 'my_server' is started
    try:
        return open_gateway(IP, PORT)
    except InstrumentServerError:
        # spawn an instrument server on the localhost using any of the overloads
        # will raise an exception if a server at the specified ip already exists
        isg = nspyre.create_server(config_file)  # start server using provided configuration file
        device_dict = {
            'sg': ['LantzSignalGenerator', 'TCPIP::localhost::5678::SOCKET'],
            'daq': ['~/drivers/my_daq_driver', 'MyDAQ', 'COM1', 5],
        }
        port = 5556
        isg = nspyre.create_server(port, devices_dict)  # start server manually passing in configuration parameters
        return isg

if __name__ ==  '__main__':
    isg = start_server_check()
    # run a (blocking) CLI (command-line interface) that allows the user to enter commands to control the server
    isg.start_CLI()

To connect to and modify an existing server, the following capabilities are exposed:

# open connection to a running instrument server
# will raise an exception if it cannot connect to a server
isg = nspyre.open_gateway()  # assumes server on localhost with default port
isg = nspyre.open_gateway(ip, port)  # connect to server at given ip and port
isg = nspyre.open_gateway(server_name)  # connect to server with given alias

available_servers = nspyre.get_servers()  # first check the directory of known servers to see what is available
isg = nspyre.open_gateway(available_servers[1])  # then connect to the first one in the list

# use the new connection to modify the server configuration
isg.restart_device(device_name)  # also takes a list of device_names
isg.stop_device(device_name)  # also takes a list of device_names
isg.add_device(config_file)  # add devices from provided inserv config file, ignore other settings
                             # from file; if any device name is already used, that device is ignored

# any lantz driver class is automatically detected so the module does not need to be specified
isg.add_device('sg', 'LantzSignalGenerator', 'TCPIP::localhost::5678::SOCKET', 'sg_class_parameter_2', port=42069)
# the daq driver is a local class, so the file_path where the class is located must be given
isg.add_device('daq', '~/drivers/my_daq_driver', 'MyDAQ', 'COM1', 5)
isg.add_devices(device_dict) # adding multiple devices is easy

We think the above examples provide a clear view of the new API design, which we hope addresses most of the current concerns, frustrations, and failures of the current implementation. Thanks for taking the time to read this lengthy post. We would greatly appreciate your suggestions as we start work on this redesign (some of which is already complete). Thanks!

-- @jacobfeder and @mtsolmn

TLDR

• Experimental 'spyrelet' code no longer inherits from the Spyrelet parent class and can be written as desired. All nspyre functionality is called explicitly. This change allows for much greater flexibility. The user can create their own arbitrarily complex Qt application if they desire. Or there can be no GUI at all and it can all be run on the command line, Jupyter notebook, etc. It is up to the user how they want to implement things, but there will be several nspyre 'convenience functions' that implement commonly-used functionality so that it is easy to get up and running quickly.
• Move from PyQt to PySide6 - officially supported python implementation of Qt by the developers.
• There are no experimental configuration files and configuration files for the instrument server are now handled programmatically as python code.
• On the instrument server side, everything is already being handled with RPyC (remote procedure calls) so drivers can be accessed directly in a pythonic way. Drivers no longer have to be written with Lantz.
• MongoDB is no longer used. Instead of storing data on MongoDB, it is now handled by a low-level nspyre server called the 'DataServer', although the user need not interact with it to use it. Additionally, using the data server is optional.

[AlexBourassa]

Hey Jacob and Michael,

Sounds like a great plan to upgrade NSpyre! I'm excited to see how it evolves!

To get the discussion started, here are a few thoughts I had (although obviously user feedback will be way more important!):

1. Where possible, I would recommend trying to minimize "boiler plate code". I think having the option of going full custom on this is great, but maybe adding a few defaults would simplify the user scripts.

• For example, I think some of the code in the if __name__ == '__main__': could be reduce to a single line calling a default nspyre function.
• Similarly, I wonder if there would be some way to simplify the coding of the "standard basic Widget" (where it's just some params and a "run" button), so it could be done in a few line by someone who may not be super familiar with Qt.
• Additionally, I could also suggest a very lightweight spyrelet class, that implements a basic standardize format (in the form of abc.abstractmethod), and perhaps some of the standard boiler plate methods (like "save")

2. Regarding this

First, the server will be spawned as a daemon process detached from any shell/process from which it is started.

I think it's a nice idea, but I would recommend you make sure there is still an easy way to completely kill the server, because sometime (when thing goes sideways), you might want the ability to "kill it with fire!". In particular, I would be careful to accommodate the following use case: if the user starts an instrument (that they are currently developing) on the server, can they then make a modification to the instrument drivers and then re-instantiate the instrument with the new code they've just written. This is currently done by shutting down the server and restarting it, so implementing an easily accessible kill switch would do the same. An even better system would be the ability to do this more granularly (on an single instrument basis) so that not all instrument need to be restarted, but that would require some very careful thinking when it comes to reloading python modules (within the same process) in a robust way.

3. Regarding this

Drivers no longer have to be written with Lantz.

I think it's great to include that option, although I would suggest there still be some "recommended" standardized framework (potentially Lantz). This standardization layer enforces some discipline in the drivers implementation and also allows for higher level code to have an expected interface (think of the Instrument Manager GUI for instance, with every instrument being completely arbitrary it will be very hard to implement a GUI that works across the board). I think the "option" of building instrument outside of the standardize framework can be useful on occasion, but I would still try to incentivize the user to stay within the framework 99% of the time.

Overall, I'm excited about this upgrade plan and I can't wait to see a demo when you have it working! And of course, I would also love to hear some thoughts from some of the current NSpyre users.

[mtsolmn]

Hey Alex,

Thanks for all the great feedback. Here are some of my follow-up thoughts, in addition to some clarifying points related to your notes (I need to stop writing essays 🙄):

1. The question of boilerplate code is an interesting one and I don't think @jacobfeder and I currently have a good answer. I can provide some insight of our current thought process given our increasing familiarity with Qt.

   Getting the UIs to be visually pleasing while having various elements play nicely together (I'm thinking pyqtgraph in particular) involves some specific commands/cleanup-code that must be called in a certain order; some of which was excluded from the example above for brevity. For example, some Qt settings for resolution must be called before any QApplication initialization, which is also the first piece of custom nspyre Qt code to be called, while certain cleanup code must be called after initialization but before any QWidget is created. This poses two questions: 1) Can this be wrapped up in an nspyre call in a 'non-hacky' way; 2) As dependencies improve and these fixes need to be modified/are no longer necessary, how does this affect existing user code if we make the change to the potential nspyre call (what versions of dependencies do they have) vs if it's just boilerplate code.

   There is something to be said for using boilerplate code as way of exposure for users to new python features, modules, etc. If we give them the boilerplate code for a basic UI, it becomes trivial for them to add additional capabilities overtime as they learn how to code said UIs. As they become more advanced in python, they can make use of the NSpyreMDI, which is the proposed shell for integrated multiple UIs together (which is actually very easy once you know how to code a QWidget correctly) and only requires the user to specify the relevant QWidget(s) to integrate.

2. The current version of nspyre (0.4.x) actually has this current functionality built-in. Using the inserv CLI you can actually kill individual drivers and restart instruments. From previous suggestions, we modified it to reload the specific driver class on an individual basis which is particularly useful when developing drivers as you mentioned. The challenge is actually maintaining the following existing functionality when moving to a daemon process:

   • Being able to open a console to see the stdout and stderr of the server.
   • Maintaining the current server CLI interface
   • Being able to debug the server (this is semi-possible currently)

   I'm quite confident we can maintain all the existing features - including killing things with fire! - because you can spawn and control daemon processes from python. In developing this proposal, I naively assumed their is a mechanism to re-establish a connection to a daemon python process but have not confirmed this.

3. In a best case scenario, I have untested ideas (e.g. introspection) on how to make an intelligent Instrument Manager GUI, but at worst I think we create a formal but not necessarily required structure to writing drivers (for instance, how you structure the driver class, using property decorators, etc.), which mainly comes down to common standards for writing clean code that should be followed anyway. (The non-Lantz drivers I'm currently writing are a good example of this.)

   In @jacobfeder's words, we are all too familiar with the 'sausage factory' that is the internals of Lantz. We've had to make many Lantz specific modifications to the codebase for compatibility. Although as maintainers of Lantz, we have the ability to change its workings, backwards compatibility would be far too great an issue, aside from the generally huge undertaking it would be to do it properly. Not to mention, Python and its standard library already have all the functionality needed to write clean drivers for the majority of today's hardware with ease. I see Lantz only being useful for MessageBasedDriver(s) that use VISA, etc.

   Finally, because the inserv is using remote procedure calls under the hood it is trivial to let a driver be any arbitrary object. In fact, the only reason this isn't currently possible is because of the Lantz specific modifications we've had to make; but this would require a minor effort to adjust. Whether it is a good thing that the user could abuse this 'feature' is a completely valid concern.

Thanks again for all the feedback, the more eyes we can get on this API redesign while it's still in the early stages the better!

[aidanj5]

Hi Jacob / Michael,

I really appreciate you typing up such a long post to show where you would like to go with the project.
To get to the point quickly, I like how you are adding flexibility, but I am worried about opening up the customizability to do anything because I have grown accustomed to NSpyre's limited functionality. To be a little more clear, I generally know my limits within NSpyre (what I can change) and I know how to change something if I need to. When you guys propose to open this up for user customization, I feel like I am going to lose all that knowledge, and I will be forced to relearn how to write a driver, how to create a QWidget, etc., which will decrease the time I can spend on research.

In general, my biggest worry is that you're building this software for people who have a similar level of coding skills to yourselves. I do not think that is the case. For instance, I only just learned how to zip tuples in python in order to repackage data. This is after consistently coding those tuples for the past five months. So, I see it taking a long time for me to figure out how to code a driver well, code a GUI well, combine instruments together, etc., in such a free form way. The standardization that makes NSpyre so inflexible and causes some problems also takes away a lot of the back end. And while I still kinda had to learn the backend, learning the backend helped me understand what I could do. So, if there's less backend, I'm worried that it will be harder to get my bearings while writing code.

I liked Michael mentioning that he's developing example drivers to look at. I also thought the boiler plate code (I believe I am understanding it correctly but this might be the wrong term) was a great idea, since I think I still have a ways to go on Qt literacy, and I know several people who know even less than me. Not that we can't learn: we just want to spend as little time as possible on the nitty gritty.

That being said, this writeup does look great, especially for those coming to NSpyre for the first time. The spyrelet does look more readable (despite not knowing what your helper functions mean), the instrument server seems even easier to handle, and getting rid of mongo is wonderful (well, I have written my own save function due to the current one not working for us, and I use Mongo to hack it, but it helps with almost everything else.)

As long as there will be some sort of tutorial or documentation about how to use this open-ended version, then I am happy.

[jacobfeder]

Hey Aidain, thanks for the feedback! A big part of the motivation of this change is to avoid the user (you) from having to mess around in the "backend" of the code. E.g. what you have done with 3D slice plots. In an ideal world you should not need to know about the implementation details of nspyre, and certainly not need to change it's internal code in order to achieve what you want. There will be a small learning curve to understand the new structure of things, but IMO it will become much easier to implement new functionality if you want it. To some extent we have to say "trust us, it'll be easier" until it's been implemented and can show you how it works, but feel free to ask questions about the specifics we've outlined if you're curious.

In order to address the issue of the learning curve on a new API, we will be sure to publish many pieces example code, as well as a full description for every nspyre function that defines the API. I think this will minimize the effort of getting over the learning curve as much as possible.