](http://lneuhaus.github.io/pyrpl/)
+[![](\"IQmodule.png\")
"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "Lock-in detection / PDH / synchronous detection"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "#reload to make sure settings are default ones\n",
+ "#from pyrpl import Pyrpl\n",
+ "#r = Pyrpl(hostname=HOSTNAME, config='tutorial').rp\n",
+ "\n",
+ "#shortcut\n",
+ "iq = r.iq0\n",
+ "\n",
+ "# modulation/demodulation frequency 25 MHz\n",
+ "# two lowpass filters with 10 and 20 kHz bandwidth\n",
+ "# input signal is analog input 1\n",
+ "# input AC-coupled with cutoff frequency near 50 kHz\n",
+ "# modulation amplitude 0.1 V\n",
+ "# modulation goes to out1\n",
+ "# output_signal is the demodulated quadrature 1\n",
+ "# quadrature_1 is amplified by 10\n",
+ "iq.setup(frequency=25e6, bandwidth=[10e3,20e3], gain=0.0, \n",
+ " phase=0, acbandwidth=50000, amplitude=0.5, \n",
+ " input='in1', output_direct='out1', \n",
+ " output_signal='quadrature', quadrature_factor=10)"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "After this setup, the demodulated quadrature is available as the output_signal of iq0, and can serve for example as the input of a PID module to stabilize the frequency of a laser to a reference cavity. The module was tested and is in daily use in our lab. Frequencies as low as 20 Hz and as high as 50 MHz have been used for this technique. At the present time, the functionality of a PDH-like detection as the one set up above cannot be conveniently tested internally. We plan to upgrade the IQ-module to VCO functionality in the near future, which will also enable testing the PDH functionality. "
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "#### Network analyzer"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "When implementing complex functionality in the RedPitaya, the network analyzer module is by far the most useful tool for diagnostics. The network analyzer is able to probe the transfer function of any other module or external device by exciting the device with a sine of variable frequency and analyzing the resulting output from that device. This is done by demodulating the device output (=network analyzer input) with the same sine that was used for the excitation and a corresponding cosine, lowpass-filtering, and averaging the two quadratures for a well-defined number of cycles. From the two quadratures, one can extract the magnitude and phase shift of the device's transfer function at the probed frequencies. Let's illustrate the behaviour. For this example, you should connect output 1 to input 1 of your RedPitaya, such that we can compare the analog transfer function to a reference. Make sure you put a 50 Ohm terminator in parallel with input 1. "
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "# shortcut for na\n",
+ "na = p.networkanalyzer\n",
+ "na.iq_name = 'iq1'\n",
+ "\n",
+ "#take transfer functions. first: iq1 -> iq1, second iq1->out1->(your cable)->adc1\n",
+ "na.setup(start=1e3,stop=62.5e6,points=1001,rbw=1000,amplitude=0.2,input='iq1',output_direct='off', acbandwidth=0, trace_average=1)\n",
+ "iq1 = na.single()\n",
+ "na.setup(start=1e3,stop=62.5e6,points=1001,rbw=1000,amplitude=0.2,input='in1',output_direct='out1', acbandwidth=0, trace_average=1)\n",
+ "adc1 = na.single()\n",
+ "f = na.data_x\n",
+ "#plot\n",
+ "from pyrpl.hardware_modules.iir.iir_theory import bodeplot\n",
+ "%matplotlib inline\n",
+ "bodeplot([(f, iq1, \"iq1->iq1\"), (f, adc1, \"iq1->out1->in1->iq1\")], xlog=True)"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "If your cable is properly connected, you will see that both magnitudes are near 0 dB over most of the frequency range. Near the Nyquist frequency (62.5 MHz), one can see that the internal signal remains flat while the analog signal is strongly attenuated, as it should be to avoid aliasing. One can also see that the delay (phase lag) of the internal signal is much less than the one through the analog signal path. \n",
+ "\n",
+ "If you have executed the last example (PDH detection) in this python session, iq0 should still send a modulation to out1, which is added to the signal of the network analyzer, and sampled by input1. In this case, you should see a little peak near the PDH modulation frequency, which was 25 MHz in the example above. "
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "#### Lorentzian bandpass filter"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "The iq module can also be used as a bandpass filter with continuously tunable phase. Let's measure the transfer function of such a bandpass with the network analyzer:"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "# shortcut for na and bpf (bandpass filter)\n",
+ "na = p.networkanalyzer\n",
+ "na.iq_name = 'iq1'\n",
+ "bpf = r.iq2\n",
+ "\n",
+ "# setup bandpass\n",
+ "bpf.setup(frequency = 2.5e6, #center frequency\n",
+ " Q=10.0, # the filter quality factor\n",
+ " acbandwidth = 10e5, # ac filter to remove pot. input offsets\n",
+ " phase=0, # nominal phase at center frequency (propagation phase lags not accounted for)\n",
+ " gain=2.0, # peak gain = +6 dB \n",
+ " output_direct='off', \n",
+ " output_signal='output_direct', \n",
+ " input='iq1')\n",
+ "\n",
+ "# take transfer function\n",
+ "na.setup(start=1e5, stop=4e6, points=201, rbw=100, avg=3, \n",
+ " amplitude=0.2, input='iq2',output_direct='off', trace_average=1)\n",
+ "tf1 = na.single()\n",
+ "\n",
+ "# add a phase advance of 82.3 degrees and measure transfer function\n",
+ "bpf.phase = 82.3\n",
+ "na.setup(start=1e5, stop=4e6, points=201, rbw=100, avg=3, \n",
+ " amplitude=0.2, input='iq2',output_direct='off', trace_average=1)\n",
+ "tf2 = na.single()\n",
+ "f = na.data_x\n",
+ "\n",
+ "#plot\n",
+ "from pyrpl.hardware_modules.iir.iir_theory import bodeplot\n",
+ "%matplotlib inline\n",
+ "bodeplot([(f, tf1, \"phase = 0.0\"), (f, tf2, \"phase = %.1f\"%bpf.phase)])"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "#### Frequency comparator module"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "To lock the frequency of a VCO (Voltage controlled oscillator) to a frequency reference defined by the RedPitaya, the IQ module contains the frequency comparator block. This is how you set it up. You have to feed the output of this module through a PID block to send it to the analog output. As you will see, if your feedback is not already enabled when you turn on the module, its integrator will rapidly saturate (-585 is the maximum value here, while a value of the order of 1e-3 indicates a reasonable frequency lock). "
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "iq = r.iq0\n",
+ "\n",
+ "# turn off pfd module for settings\n",
+ "iq.pfd_on = False\n",
+ "\n",
+ "# local oscillator frequency\n",
+ "iq.frequency = 33.7e6\n",
+ "\n",
+ "# local oscillator phase\n",
+ "iq.phase = 0\n",
+ "iq.input = 'in1' \n",
+ "iq.output_direct = 'off'\n",
+ "iq.output_signal = 'pfd'\n",
+ "\n",
+ "print(\"Before turning on:\")\n",
+ "print(\"Frequency difference error integral\", iq.pfd_integral)\n",
+ "\n",
+ "print(\"After turning on:\")\n",
+ "iq.pfd_on = True\n",
+ "for i in range(10):\n",
+ " print(\"Frequency difference error integral\", iq.pfd_integral)"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "### IIR module"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "Sometimes it is interesting to realize even more complicated filters. This is the case, for example, when a piezo resonance limits the maximum gain of a feedback loop. For these situations, the IIR module can implement filters with 'Infinite Impulse Response' (https://en.wikipedia.org/wiki/Infinite_impulse_response). It is the your task to choose the filter to be implemented by specifying the complex values of the poles and zeros of the filter. In the current version of pyrpl, the IIR module can implement IIR filters with the following properties:\n",
+ "- strictly proper transfer function (number of poles > number of zeros)\n",
+ "- poles (zeros) either real or complex-conjugate pairs\n",
+ "- no three or more identical real poles (zeros)\n",
+ "- no two or more identical pairs of complex conjugate poles (zeros)\n",
+ "- pole and zero frequencies should be larger than $\\frac{f_\\rm{nyquist}}{1000}$ (but you can optimize the nyquist frequency of your filter by tuning the 'loops' parameter)\n",
+ "- the DC-gain of the filter must be 1.0. Despite the FPGA implemention being more flexible, we found this constraint rather practical. If you need different behavior, pass the IIR signal through a PID module and use its input filter and proportional gain. If you still need different behaviour, the file iir.py is a good starting point. \n",
+ "- total filter order <= 16 (realizable with 8 parallel biquads)\n",
+ "- a remaining bug limits the dynamic range to about 30 dB before internal saturation interferes with filter performance\n",
+ "\n",
+ "Filters whose poles have a positive real part are unstable by design. Zeros with positive real part lead to non-minimum phase lag. Nevertheless, the IIR module will let you implement these filters. \n",
+ "\n",
+ "In general the IIR module is still fragile in the sense that you should verify the correct implementation of each filter you design. Usually you can trust the simulated transfer function. It is nevertheless a good idea to use the internal network analyzer module to actually measure the IIR transfer function with an amplitude comparable to the signal you expect to go through the filter, as to verify that no saturation of internal filter signals limits its performance. "
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "#shortcut\n",
+ "iir = r.iir\n",
+ "\n",
+ "#print docstring of the setup function\n",
+ "print(iir.setup.__doc__)"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "#prepare plot parameters\n",
+ "%matplotlib inline\n",
+ "import matplotlib\n",
+ "matplotlib.rcParams['figure.figsize'] = (10, 6)\n",
+ "\n",
+ "#setup a complicated transfer function\n",
+ "zeros = [ +4e4j-300,-2e5j-1000]\n",
+ "#[ -4e4j-300, +4e4j-300,-2e5j-1000, +2e5j-1000, -2e6j-3000, +2e6j-3000]\n",
+ "poles = [ -1e6, +5e4j-300]\n",
+ "#[ -1e6, -5e4j-300, +5e4j-300, -1e5j-3000, +1e5j-3000, -1e6j-30000, +1e6j-30000]\n",
+ "designdata = iir.setup(zeros=zeros, poles=poles, loops=None, plot=True);\n",
+ "print(\"Filter sampling frequency: \", 125./iir.loops,\"MHz\")"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "If you try changing a few coefficients, you will see that your design filter is not always properly realized. The bottleneck here is the conversion from the analytical expression (poles and zeros) to the filter coefficients, not the FPGA performance. This conversion is (among other things) limited by floating point precision. We hope to provide a more robust algorithm in future versions. If you can obtain filter coefficients by another, preferrably analytical method, this might lead to better results than our generic algorithm. \n",
+ "\n",
+ "Let's check if the filter is really working as it is supposed:"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "# first thing to check if the filter is not ok\n",
+ "print(\"IIR overflows before:\", bool(iir.overflow))\n",
+ "\n",
+ "# measure tf of iir filter\n",
+ "p.rp.iir.input = 'iq1'\n",
+ "p.networkanalyzer.setup(iq_name='iq1', start=1e4, stop=3e6, points = 301, rbw=100, trace_average=1, \n",
+ " amplitude=0.1, input='iir', output_direct='off', logscale=True)\n",
+ "tf = p.networkanalyzer.single()\n",
+ "f = p.networkanalyzer.data_x\n",
+ "\n",
+ "# first thing to check if the filter is not ok\n",
+ "print(\"IIR overflows after:\", bool(iir.overflow))\n",
+ "\n",
+ "#plot with design data\n",
+ "%matplotlib inline\n",
+ "import matplotlib\n",
+ "matplotlib.rcParams['figure.figsize'] = (10, 6)\n",
+ "from pyrpl.hardware_modules.iir.iir_theory import bodeplot\n",
+ "bodeplot([(f, iir.transfer_function(f),\"designed system\")] + [(f,tf,\"measured system\")],xlog=True)"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "As you can see, the filter has trouble to realize large dynamic ranges. With the current standard design software, it takes some 'practice' to design transfer functions which are properly implemented by the code. While most zeros are properly realized by the filter, you see that the first two poles suffer from some kind of saturation. We are working on an automatic rescaling of the coefficients to allow for optimum dynamic range. From the overflow register printed above the plot, you can also see that the network analyzer scan caused an internal overflow in the filter. All these are signs that different parameters should be tried. \n",
+ "\n",
+ "A straightforward way to impove filter performance is to adjust the DC-gain and compensate it later with the gain of a subsequent PID module. See for yourself what the parameter g=0.1 (instead of the default value g=1.0) does here:"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "#rescale the filter by 20fold reduction of DC gain\n",
+ "iir.setup(zeros=zeros, poles=poles, g=0.1,loops=None,plot=False);\n",
+ "\n",
+ "# first thing to check if the filter is not ok\n",
+ "print(\"IIR overflows before:\", bool(iir.overflow))\n",
+ "\n",
+ "# measure tf of iir filter\n",
+ "p.rp.iir.input = 'networkanalyzer'\n",
+ "p.networkanalyzer.setup(start=1e4, stop=3e6, points= 301, rbw=100, trace_average=1, \n",
+ " amplitude=0.1, input='iir', output_direct='off', logscale=True)\n",
+ "tf = p.networkanalyzer.single()\n",
+ "f = p.networkanalyzer.data_x\n",
+ "# first thing to check if the filter is not ok\n",
+ "print(\"IIR overflows after:\", bool(iir.overflow))\n",
+ "\n",
+ "#plot with design data\n",
+ "%matplotlib inline\n",
+ "import pylab\n",
+ "pylab.rcParams['figure.figsize'] = (10, 6)\n",
+ "from pyrpl.hardware_modules.iir.iir_theory import bodeplot\n",
+ "bodeplot([(f, p.rp.iir.transfer_function(f), \"design\")]+[(f,tf,\"measured system\")],xlog=True)"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "You see that we have improved the second peak (and avoided internal overflows) at the cost of increased nosie in other regions. Of course this noise can be reduced by increasing the NA averaging time. But maybe it will be detrimental to your application? After all, IIR filter design is far from trivial, but this tutorial should have given you enough information to get started and maybe to improve the way we have implemented the filter in pyrpl (e.g. by implementing automated filter coefficient scaling).\n",
+ "\n",
+ "If you plan to play more with the filter, these are the remaining internal iir registers:"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "iir = p.rp.iir\n",
+ "\n",
+ "# useful diagnostic functions\n",
+ "print(\"IIR on:\", iir.on)\n",
+ "#print(\"IIR bypassed:\", iir.shortcut)\n",
+ "#print(\"IIR copydata:\", iir.copydata)\n",
+ "print(\"IIR loops:\", iir.loops)\n",
+ "print(\"IIR overflows:\", iir.overflow)\n",
+ "print(\"\\nCoefficients (6 per biquad):\")\n",
+ "print(iir.coefficients)\n",
+ "\n",
+ "# set the unity transfer function to the filter\n",
+ "iir._setup_unity()"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "## 6) The Pyrpl class"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "The RedPitayas in our lab are mostly used to stabilize one item or another in quantum optics experiments. To do so, the experimenter usually does not want to bother with the detailed implementation on the RedPitaya while trying to understand the physics going on in her/his experiment. For this situation, we have developed the Pyrpl class, which provides an API with high-level functions such as:\n",
+ " \n",
+ " # optimial pdh-lock with setpoint 0.1 cavity bandwidth away from resonance\n",
+ " cavity.lock(method='pdh',detuning=0.1)\n",
+ " \n",
+ " # unlock the cavity\n",
+ " cavity.unlock()\n",
+ " \n",
+ " # calibrate the fringe height of an interferometer, and lock it at local oscillator phase 45 degrees\n",
+ " interferometer.lock(phase=45.0) "
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "### First attempts at locking"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "SECTION NOT READY YET, BECAUSE CODE NOT CLEANED YET"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "Now lets go for a first attempt to lock something. Say you connect the error signal (transmission or reflection) of your setup to input 1. Make sure that the peak-to-peak of the error signal coincides with the maximum voltages the RedPitaya can handle (-1 to +1 V if the jumpers are set to LV). This is important for getting optimal noise performance. If your signal is too low, amplify it. If it is too high, you should build a voltage divider with 2 resistors of the order of a few kOhm (that way, the input impedance of the RedPitaya of 1 MOhm does not interfere). \n",
+ "\n",
+ "Next, connect output 1 to the standard actuator at your hand, e.g. a piezo. Again, you should try to exploit the full -1 to +1 V output range. If the voltage at the actuator must be kept below 0.5V for example, you should make another voltage divider for this. Make sure that you take the input impedance of your actuator into consideration here. If you output needs to be amplified, it is best practice to put the voltage divider after the amplifier as to also attenuate the noise added by the amplifier. Hovever, when this poses a problem (limited bandwidth because of capacity of the actuator), you have to put the voltage divider before the amplifier. Also, this is the moment when you should think about low-pass filtering the actuator voltage. Because of DAC noise, analog low-pass filters are usually more effective than digital ones. A 3dB bandwidth of the order of 100 Hz is a good starting point for most piezos. \n",
+ "\n",
+ "You often need two actuators to control your cavity. This is because the output resolution of 14 bits can only realize 16384 different values. This would mean that with a finesse of 15000, you would only be able to set it to resonance or a linewidth away from it, but nothing in between. To solve this, use a coarse actuator to cover at least one free spectral range which brings you near the resonance, and a fine one whose range is 1000 or 10000 times smaller and who gives you lots of graduation around the resonance. The coarse actuator should be strongly low-pass filtered (typical bandwidth of 1Hz or even less), the fine actuator can have 100 Hz or even higher bandwidth. Do not get confused here: the unity-gain frequency of your final lock can be 10- or even 100-fold above the 3dB bandwidth of the analog filter at the output - it suffices to increase the proportional gain of the RedPitaya Lockbox. \n",
+ "\n",
+ "Once everything is connected, let's grab a PID module, make a shortcut to it and print its helpstring. All modules have a metho help() which prints all available registers and their description:"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "pid = p.rp.pid0\n",
+ "print(pid.help())\n",
+ "pid.ival #bug: help forgets about pid.ival: current integrator value [volts]"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "We need to inform our RedPitaya about which connections we want to make. The cabling discussed above translates into:"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "pid.input = 'in1'\n",
+ "pid.output_direct = 'out1'\n",
+ "\n",
+ "#see other available options just for curiosity:\n",
+ "print(pid.inputs)\n",
+ "print(pid.output_directs)"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "Finally, we need to define a setpoint. Lets first measure the offset when the laser is away from the resonance, and then measure or estimate how much light gets through on resonance. "
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "# turn on the laser\n",
+ "offresonant = p.rp.scope.voltage_in1 #volts at analog input 1 with the unlocked cavity"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {
+ "collapsed": true
+ },
+ "outputs": [],
+ "source": [
+ "# make a guess of what voltage you will measure at an optical resonance\n",
+ "resonant = 0.5 #Volts at analog input 1"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {
+ "collapsed": true
+ },
+ "outputs": [],
+ "source": [
+ "# set the setpoint at relative reflection of 0.75 / rel. transmission of 0.25\n",
+ "pid.setpoint = 0.75*offresonant + 0.25*resonant"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "Now lets start to approach the resonance. We need to figure out from which side we are coming. The choice is made such that a simple integrator will naturally drift into the resonance and stay there:"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {
+ "collapsed": true
+ },
+ "outputs": [],
+ "source": [
+ "pid.i = 0 # make sure gain is off\n",
+ "pid.p = 0\n",
+ "#errorsignal = adc1 - setpoint \n",
+ "if resonant > offresonant: # when we are away from resonance, error is negative. \n",
+ " slopesign = 1.0 # therefore, near resonance, the slope is positive as the error crosses zero. \n",
+ "else:\n",
+ " slopesign = -1.0\n",
+ "gainsign = -slopesign #the gain must be the opposite to stabilize\n",
+ "# the effectove gain will in any case slopesign*gainsign = -1. \n",
+ "\n",
+ "#Therefore we must start at the maximum positive voltage, so the negative effective gain leads to a decreasing output\n",
+ "pid.ival = 1.0 #sets the integrator value = output voltage to maximum\n",
+ "\n",
+ "from time import sleep\n",
+ "sleep(1.0) #wait for the voltage to stabilize (adjust for a few times the lowpass filter bandwidth)\n",
+ "\n",
+ "#finally, turn on the integrator\n",
+ "pid.i = gainsign * 0.1"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "#no-test\n",
+ "#with a bit of luck, this should work\n",
+ "from time import time\n",
+ "t0 = time()\n",
+ "while True:\n",
+ " relative_error = abs((p.rp.scope.voltage_in1-pid.setpoint)/(offresonant-resonant))\n",
+ " if time()-t0 > 2: #diagnostics every 2 seconds\n",
+ " print(\"relative error:\",relative_error)\n",
+ " t0 = time()\n",
+ " if relative_error < 0.1:\n",
+ " break\n",
+ " sleep(0.01)\n",
+ " if pid.ival <= -1:\n",
+ " print(\"Resonance missed. Trying again slower..\")\n",
+ " pid.ival = 1.2 #overshoot a little\n",
+ " pid.i /= 2\n",
+ "print(\"Resonance approch successful\")"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ " Questions to users: what parameters do you know?\n",
+ " finesse of the cavity? 1000\n",
+ " length? 1.57m\n",
+ " what error signals are available? transmission direct, reflection AC -> directement pdh analogique\n",
+ " \n",
+ " are modulators available n/a\n",
+ " \n",
+ " what cavity length / laser frequency actuators are available? PZT mephisto DC - 10kHz, 48MHz opt./V, V_rp apmplifie x20\n",
+ " temperature du laser <1 Hz 2.5~GHz/V, apres AOM\n",
+ " \n",
+ " what is known about them (displacement, bandwidth, amplifiers)?\n",
+ " \n",
+ " what analog filters are present? YAG PZT a 10kHz\n",
+ " \n",
+ " imposer le design des sorties\n",
+ " \n",
+ " \n",
+ " "
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "More to come"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "\n",
+ "\n",
+ "#shortcut\n",
+ "iq = p.rp.iq0\n",
+ "\n",
+ "iq.setup(frequency=1000e3, bandwidth=[10e3,20e3], gain=0.0, \n",
+ " phase=0, acbandwidth=50000, amplitude=0.4, \n",
+ " input='in1', output_direct='out1', \n",
+ " output_signal='output_direct', quadrature_factor=0)\n",
+ "iq.frequency=10\n",
+ "p.rp.scope.input1='in1'\n",
+ "\n",
+ "# shortcut for na\n",
+ "na = p.networkanalyzer\n",
+ "na.iq_name = \"iq1\"\n",
+ "\n",
+ "# pid1 will be our device under test\n",
+ "pid = p.rp.pid0\n",
+ "pid.input = 'iq1'\n",
+ "pid.i = 0\n",
+ "pid.ival = 0\n",
+ "pid.p = 1.0\n",
+ "pid.setpoint = 0\n",
+ "pid.inputfilter = []#[-1e3, 5e3, 20e3, 80e3]\n",
+ "\n",
+ "# take the transfer function through pid1, this will take a few seconds...\n",
+ "na.setup(start=0,stop=200e3,points=101,rbw=100,avg=1,amplitude=0.5,input='iq1',output_direct='off', acbandwidth=0)\n",
+ "y = na.single()\n",
+ "x = na.data_x\n",
+ "#plot\n",
+ "import matplotlib.pyplot as plt\n",
+ "%matplotlib inline\n",
+ "import numpy as np\n",
+ "plt.plot(x*1e-3,np.abs(y)**2);\n",
+ "plt.xlabel(\"Frequency [kHz]\");\n",
+ "plt.ylabel(\"|S21|\");"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "## 7) The Graphical User Interface"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "Most of the modules described in section 5 can be controlled via a graphical user interface. The graphical window can be displayed with the following:"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "WARNING: For the GUI to work fine within an ipython session, the option --gui=qt has to be given to the command launching ipython. This makes sure that an event loop is running."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "#no-test\n",
+ "from pyrpl import Pyrpl\n",
+ "p = Pyrpl(hostname=HOSTNAME, config='tutorial')"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "The following window should open itself. Feel free to play with the button and tabs to start and stop the scope acquisition...\n",
+ "\n",
+ "![](\"gui.bmp\")
"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "The window is composed of several tabs, each corresponding to a particular module. Since they generate a graphical output, the scope, network analyzer, and spectrum analyzer modules are very pleasant to use in GUI mode. For instance, the scope tab can be used to display in real-time the waveforms acquired by the redpitaya scope. Since the refresh rate is quite good, the scope tab can be used to perform optical alignements or to monitor transient signals as one would do it with a standalone scope."
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": []
+ },
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "Pyrpl uses the Qt eventloop to perform asynchronous tasks, but it has been set as the default loop of `asyncio`, such that you only need to learn how to use the standard python module [`asyncio`](https://docs.python.org/3/library/asyncio.html), and you don't need to know anything about Qt. To give you a quick overview of what can be done, we present in the following block an exemple of 2 tasks running in parrallele. The first one mimicks a temperature control loop, measuring periodically a signal every 1 s, and changing the offset of an `asg` based on the measured value (we realize this way a slow and rudimentary software pid). In parrallele, another task consists in repeatedly shifting the frequency of an asg, and measuring an averaged spectrum on the spectrum analyzer.\n",
+ "\n",
+ "Both tasks are defined by coroutines (a python function that is preceded by the keyword `async`, and that can contain the keyword `await`). Basically, the execution of each coroutine is interrupted whenever the keyword `await` is encountered, giving the chance to other tasks to be executed. It will only be resumed once the underlying coroutine's value becomes ready.\n",
+ "\n",
+ "Finally to execute the cocroutines, it is not enough to call `my_coroutine()`, since we need to send the task to the event loop. For that, we use the function `ensure_future` from the asyncio module. This function immediately returns an object that is not the result of the task (not the object that is behind `return` inside the coroutine), but rather a Future object, that can be used to retrieve the actual result once it is ready (this is done by calling `future.result()` latter on).\n",
+ "\n",
+ "If you are executing the code inside the ipython notebook, then, this is all you have to do, since an event loop is already running in the back (a qt eventloop if you are using the option %pylab qt). Otherwise, you have to use one of the functions (`LOOP.run_forever()`, `LOOP.run_until_complete()`, or `LOOP.run_in_executor()`) to launch the eventloop."
+ ]
+ }
+ ],
+ "metadata": {
+ "kernelspec": {
+ "display_name": "Python 3",
+ "language": "python",
+ "name": "python3"
+ },
+ "language_info": {
+ "codemirror_mode": {
+ "name": "ipython",
+ "version": 3
+ },
+ "file_extension": ".py",
+ "mimetype": "text/x-python",
+ "name": "python",
+ "nbconvert_exporter": "python",
+ "pygments_lexer": "ipython3",
+ "version": "3.6.4"
+ },
+ "name": ""
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}
diff --git a/docs/index.html b/docs/index.html
deleted file mode 100644
index deaf50a3d..000000000
--- a/docs/index.html
+++ /dev/null
@@ -1,14 +0,0 @@
-
-
-
-
-
diff --git a/docs/makefile b/docs/makefile
index de6164dd1..9533688e9 100644
--- a/docs/makefile
+++ b/docs/makefile
@@ -49,41 +49,42 @@ help:
clean:
rm -rf $(BUILDDIR)/*
-# Preliminaries to a real build - convert tutorial to readable format
-ipython nbconvert --to html source/user_guide/tutorial/tutorial.ipynb
+common:
+ # Preliminaries to a real build - convert tutorial to readable format
+ ipython nbconvert --to html source/user_guide/tutorial/tutorial.ipynb
-html:
+html: common
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
-dirhtml:
+dirhtml: common
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
-singlehtml:
+singlehtml: common
$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
@echo
@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
-pickle:
+pickle: common
$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
@echo
@echo "Build finished; now you can process the pickle files."
-json:
+json: common
$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
@echo
@echo "Build finished; now you can process the JSON files."
-htmlhelp:
+htmlhelp: common
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
@echo
@echo "Build finished; now you can run HTML Help Workshop with the" \
".hhp project file in $(BUILDDIR)/htmlhelp."
-qthelp:
+qthelp: common
$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
@echo
@echo "Build finished; now you can run "qcollectiongenerator" with the" \
@@ -92,7 +93,7 @@ qthelp:
@echo "To view the help file:"
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/pyrpl.qhc"
-devhelp:
+devhelp: common
$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
@echo
@echo "Build finished."
@@ -101,80 +102,80 @@ devhelp:
@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/pyrpl"
@echo "# devhelp"
-epub:
+epub: common
$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
@echo
@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
-latex:
+latex: common
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo
@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
@echo "Run \`make' in that directory to run these through (pdf)latex" \
"(use \`make latexpdf' here to do that automatically)."
-latexpdf:
+latexpdf: common
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo "Running LaTeX files through pdflatex..."
$(MAKE) -C $(BUILDDIR)/latex all-pdf
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
-latexpdfja:
+latexpdfja: common
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo "Running LaTeX files through platex and dvipdfmx..."
$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
-text:
+text: common
$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
@echo
@echo "Build finished. The text files are in $(BUILDDIR)/text."
-man:
+man: common
$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
@echo
@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
-texinfo:
+texinfo: common
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
@echo
@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
@echo "Run \`make' in that directory to run these through makeinfo" \
"(use \`make info' here to do that automatically)."
-info:
+info: common
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
@echo "Running Texinfo files through makeinfo..."
make -C $(BUILDDIR)/texinfo info
@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
-gettext:
+gettext: common
$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
@echo
@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
-changes:
+changes: common
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
@echo
@echo "The overview file is in $(BUILDDIR)/changes."
-linkcheck:
+linkcheck: common
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
@echo
@echo "Link check complete; look for any errors in the above output " \
"or in $(BUILDDIR)/linkcheck/output.txt."
-doctest:
+doctest: common
$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
@echo "Testing of doctests in the sources finished, look at the " \
"results in $(BUILDDIR)/doctest/output.txt."
-xml:
+xml: common
$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
@echo
@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
-pseudoxml:
+pseudoxml: common
$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
@echo
@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
\ No newline at end of file
diff --git a/docs/old_files/benchmarks/asyncio_no_correction.png b/docs/old_files/benchmarks/asyncio_no_correction.png
deleted file mode 100644
index 5f2a89318..000000000
Binary files a/docs/old_files/benchmarks/asyncio_no_correction.png and /dev/null differ
diff --git a/docs/old_files/benchmarks/images/with_timer/asyncio.png b/docs/old_files/benchmarks/images/with_timer/asyncio.png
deleted file mode 100644
index b2699f35e..000000000
Binary files a/docs/old_files/benchmarks/images/with_timer/asyncio.png and /dev/null differ
diff --git a/docs/old_files/benchmarks/images/with_timer/asyncio_no_correction.png b/docs/old_files/benchmarks/images/with_timer/asyncio_no_correction.png
deleted file mode 100644
index 5f2a89318..000000000
Binary files a/docs/old_files/benchmarks/images/with_timer/asyncio_no_correction.png and /dev/null differ
diff --git a/docs/old_files/benchmarks/images/with_timer/my_sleep.png b/docs/old_files/benchmarks/images/with_timer/my_sleep.png
deleted file mode 100644
index de4ccb115..000000000
Binary files a/docs/old_files/benchmarks/images/with_timer/my_sleep.png and /dev/null differ
diff --git a/docs/old_files/benchmarks/images/with_timer/processEvents.png b/docs/old_files/benchmarks/images/with_timer/processEvents.png
deleted file mode 100644
index 2f397a803..000000000
Binary files a/docs/old_files/benchmarks/images/with_timer/processEvents.png and /dev/null differ
diff --git a/docs/old_files/benchmarks/images/with_timer/qeventloop.png b/docs/old_files/benchmarks/images/with_timer/qeventloop.png
deleted file mode 100644
index 5bd8eff96..000000000
Binary files a/docs/old_files/benchmarks/images/with_timer/qeventloop.png and /dev/null differ
diff --git a/docs/old_files/benchmarks/images/with_timer/time.sleep.png b/docs/old_files/benchmarks/images/with_timer/time.sleep.png
deleted file mode 100644
index a64cae9d7..000000000
Binary files a/docs/old_files/benchmarks/images/with_timer/time.sleep.png and /dev/null differ
diff --git a/docs/old_files/benchmarks/images/without_timer/asyncio.png b/docs/old_files/benchmarks/images/without_timer/asyncio.png
deleted file mode 100644
index 3eed67466..000000000
Binary files a/docs/old_files/benchmarks/images/without_timer/asyncio.png and /dev/null differ
diff --git a/docs/old_files/benchmarks/images/without_timer/my_sleep.png b/docs/old_files/benchmarks/images/without_timer/my_sleep.png
deleted file mode 100644
index b7596bb58..000000000
Binary files a/docs/old_files/benchmarks/images/without_timer/my_sleep.png and /dev/null differ
diff --git a/docs/old_files/benchmarks/images/without_timer/processEvents.png b/docs/old_files/benchmarks/images/without_timer/processEvents.png
deleted file mode 100644
index 6c58e272e..000000000
Binary files a/docs/old_files/benchmarks/images/without_timer/processEvents.png and /dev/null differ
diff --git a/docs/old_files/benchmarks/images/without_timer/qeventloop.png b/docs/old_files/benchmarks/images/without_timer/qeventloop.png
deleted file mode 100644
index 6424ae825..000000000
Binary files a/docs/old_files/benchmarks/images/without_timer/qeventloop.png and /dev/null differ
diff --git a/docs/old_files/benchmarks/images/without_timer/time.sleep.png b/docs/old_files/benchmarks/images/without_timer/time.sleep.png
deleted file mode 100644
index 621fac05b..000000000
Binary files a/docs/old_files/benchmarks/images/without_timer/time.sleep.png and /dev/null differ
diff --git a/docs/old_files/benchmarks/timers.ipynb b/docs/old_files/benchmarks/timers.ipynb
deleted file mode 100644
index 3679c8089..000000000
--- a/docs/old_files/benchmarks/timers.ipynb
+++ /dev/null
@@ -1,855 +0,0 @@
-{
- "cells": [
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {
- "collapsed": false
- },
- "outputs": [],
- "source": [
- "%pylab qt"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {
- "collapsed": false
- },
- "outputs": [],
- "source": [
- "from PyQt4 import QtCore, QtGui\n",
- "n_calc = [0]\n",
- "def calculate():\n",
- " sin(rand(1000))\n",
- " n_calc[0]+=1\n",
- " timer.start()\n",
- "\n",
- "timer = QtCore.QTimer()\n",
- "timer.setInterval(0)\n",
- "timer.setSingleShot(True)\n",
- "timer.timeout.connect(calculate)"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "metadata": {
- "collapsed": false
- },
- "outputs": [],
- "source": [
- "from PyQt4 import QtCore, QtGui\n",
- "from psutil import cpu_percent\n",
- "from time import sleep\n",
- "from timeit import default_timer\n",
- "APP = QtGui.QApplication.instance()\n",
- "\n",
- "close('all')\n",
- "\n",
- "n_calc[0] = 0\n",
- "\n",
- "from time import time\n",
- "def sleep_loop(delay):\n",
- " loop = QtCore.QEventLoop()\n",
- " timer = QtCore.QTimer()\n",
- " timer.setInterval(delay*1000)\n",
- " timer.setSingleShot(True)\n",
- " timer.timeout.connect(loop.quit)\n",
- " timer.start()\n",
- " loop.exec() # la loop prend en charge elle-même l'évenement du timer qui va la faire mourir après delay.\n",
- "\n",
- "def sleep_pe(delay):\n",
- " tic = default_timer()\n",
- " while(default_timer() element.
+ # For black navbar, do "navbar navbar-inverse"
+ 'navbar_class': "navbar navbar-inverse",
+
+ # Fix navigation bar to top of page?
+ # Values: "true" (default) or "false"
+ 'navbar_fixed_top': "true",
+
+ # Location of link to source.
+ # Options are "nav" (default), "footer" or anything else to exclude.
+ 'source_link_position': "footer",
+
+ # Bootswatch (http://bootswatch.com/) theme.
+ #
+ # Options are nothing (default) or the name of a valid theme
+ # such as "cosmo" or "sandstone". "united",
+ #'bootswatch_theme': "united", #
+
+ # Choose Bootstrap version.
+ # Values: "3" (default) or "2" (in quotes)
+ 'bootstrap_version': "3",
+}
# Add any paths that contain custom themes here, relative to this directory.
-#html_theme_path = []
+html_theme_path = sphinx_bootstrap_theme.get_html_theme_path()
# The name for this set of Sphinx documents. If None, it defaults to
# " v documentation".
@@ -167,7 +239,7 @@
# The name of an image file (within the static path) to use as favicon of the
# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large.
-#html_favicon = None
+html_favicon = 'icon.ico'
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
@@ -189,6 +261,7 @@
# Custom sidebar templates, maps document names to template names.
#html_sidebars = {}
+html_sidebars = {'**': ['localtoc.html']}
# Additional templates that should be rendered to pages, maps page names to
# template names.
@@ -210,7 +283,7 @@
#html_show_sphinx = True
# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
-#html_show_copyright = True
+html_show_copyright = True
# If true, an OpenSearch description file will be output, and all pages will
# contain a tag referring to it. The value of this option must be the
diff --git a/docs/source/contents.rst b/docs/source/contents.rst
new file mode 100644
index 000000000..3f732b8d5
--- /dev/null
+++ b/docs/source/contents.rst
@@ -0,0 +1,13 @@
+
+Full documentation structure
+******************************
+
+.. toctree::
+ :maxdepth: -1
+ :numbered:
+
+ installation
+ gui
+ api
+ basics
+ developer_guide/index
diff --git a/docs/source/developer_guide/api/spectrum.rst b/docs/source/developer_guide/api/spectrum.rst
index 54072c111..90d2f780d 100644
--- a/docs/source/developer_guide/api/spectrum.rst
+++ b/docs/source/developer_guide/api/spectrum.rst
@@ -14,7 +14,9 @@ which consists in the following steps:
1. Each segment is multiplied by a symmetric window function of the same
size.
-2. the DFT of individual segments is performed.
+2. The DFT of individual segments is performed. The segment is padded
+ before the FFT by a number of 0s to provide more points in the estimated
+ spectrum than in the original time segment.
3. The square modulus of the resulting periodograms are averaged to give
the estimate of the spectrum, with the same size as the initial
time-segments.
@@ -45,105 +47,111 @@ In the following, we discuss the normalization of windowing functions,
and then, the basic principle of operation of the two modes "iq" and
"baseband".
-Normalization of windowing functions
-------------------------------------
-The Fourier transform of the series a\_n is defined by
-A\_m = 1/N sum(a\_k exp(-2 i pi m k/N)) [1]
+Definitions
+-----------
-With this convention, we need to pay attention that the DC-component is
-for m=0, and the "negative frequencies" are actually located in the
-second half of the interval [N/2, N]. Indeed, we can show that because
-of the discretization, A\_{N - m} = A\_{-m}
++----------------------------------------+----------------------------------------------------+
+|name | definition |
++========================================+====================================================+
+| Original time series | x[k], 0<=k = delta(k-k').
-rbw = sum(f\_n^2)/sum(f\_n) [9]
+We would like the total spectrum in units of Vrms^2/Hz, integrated from 0 to Nyquist frequency
+to yield the same variance of 1. This is ensured by the Equivalent noise bandwidth of the filter window.
+To convert from V_pk^2 to V_rms^2/Hz, the spectrum is divided by the residual bandwidth of the filter window.
-With this choice, the correct results are retrieved if we make all
-calculations in Vpk^2, and divide the results by the rbw to convert them
-in Vpk^2/Hz.
+Let's calculate:
-For this reason, the rbw is not exactly the width at 3 dB of the filter
-spectrum, but actually depends on the precise shape of the window over
-the whole frequency range via eq [9].
+sum_r <|Y[r]|^2> = (...) = N sum_k w[k]^2 <|x[k]|^2>
+
+If we remind that x[k] is a white noise following <|x[k]|^2> = 1, we get:
+
+sum_r <|Y[r]|^2> = N sum_k w[k]^2
+
+So, since we want:
+
+sum_r <|Z[r]|^2> df = 2, (indeed, we want to work with single-sided spectra, such that integrating over positive frequencies is enough)
+
+with df the frequency step in the FFT, we need to choose:
+
+rbw = N sum_k w[k]^2 df /4
+
+In order to use dimensionless parameters for the filter windows, we can introduce the equivalent noise bandwidth:
+
+ENBW = sum_k w[k]^2/(sum_k w[k])^2 = 1/4 sum_k w[k]^2
+
+Finally, we get the expression of the rbw:
+
+rbw = sample_rate ENBW
IQ mode
-------
diff --git a/docs/source/developer_guide/contributing.rst b/docs/source/developer_guide/contributing.rst
new file mode 100644
index 000000000..e3bbcfbc9
--- /dev/null
+++ b/docs/source/developer_guide/contributing.rst
@@ -0,0 +1,19 @@
+Contributing to PyRPL
+************************
+
+
+Contributions to the PyRPL are welcome. To submit your changes for inclusion, please follow this procedure:
+
+1. Fork this repository to your own github account using the fork button in the upper right corner on ``_.
+
+2. Clone (download) the fork to a local computer using git clone.
+
+3. Modify anything you find useful, from the Python source code to the FPGA design. If you modify the FPGA, make sure to include the bitfile (see :doc:`fpga_compilation`).
+
+4. Modify the documentation in the docs-subfolder if necessary.
+
+5. Use git add-->git commit-->git push to add changes to your fork.
+
+6. Then submit a pull request by clicking the pull request button on your github repo.
+
+Check the `guide to git `_. Flash this image on a >= 4 GB SD card using a tool like `Win32DiskImager `_ `(see full documentation) ` or the `video tutorial on youtube `_.
+
+
+.. admonition:: PyRPL has a convenient Python API.
+
+ See :ref:`high_level_example` or :ref:`low_level_example`, and the :doc:`full API documentation ` .
+
+
+.. admonition:: PyRPL `binary executables `__ for `Windows, `__ `Linux, `__ or `Mac OS X `__
+
+ can be easily :ref:`downloaded ` and run without any installation work.
+
+
+.. admonition:: PyRPL's code is entirely public `on github `_ and can be customized,
+
+ including the `Verilog source code for the FPGA `_ which is based on the official Red Pitaya software version 0.95.
+
+
+.. admonition:: PyRPL is already used in many research groups all over the world.
+
+ See for yourself the :ref:`user_feedback`.
+
+
+.. admonition:: PyRPL is free software and comes with the `GNU General Public License v3.0 `_.
+
+ Read the `license `_ for more details!
+
+
+
+
+.. _manual:
+
+Manual
+*******************
.. toctree::
- :maxdepth: 2
+ :maxdepth: 1
+ :titlesonly:
+ :hidden:
- gallery/index
- user_guide/index
- reference_guide/index
+ installation
+ gui
+ api
+ basics
developer_guide/index
- indices_and_tables/index
+ contents
+
+* :doc:`installation`
+* :doc:`gui`
+* :doc:`api`
+* :doc:`basics`
+* :doc:`developer_guide/index`
+* :doc:`contents`
+
+
+.. _low_level_example:
+
+Low-level API example
+************************
+
+.. code-block:: python
+
+ # import pyrpl library
+ import pyrpl
+
+ # create an interface to the Red Pitaya
+ r = pyrpl.Pyrpl().redpitaya
+
+ r.hk.led = 0b10101010 # change led pattern
+
+ # measure a few signal values
+ print("Voltage at analog input1: %.3f" % r.sampler.in1)
+ print("Voltage at analog output2: %.3f" % r.sampler.out2)
+ print("Voltage at the digital filter's output: %.3f" % r.sampler.iir)
+
+ # output a function U(t) = 0.5 V * sin(2 pi * 10 MHz * t) to output2
+ r.asg0.setup(waveform='sin',
+ amplitude=0.5,
+ frequency=10e6,
+ output_direct='out2')
+
+ # demodulate the output signal from the arbitrary signal generator
+ r.iq0.setup(input='asg0', # demodulate the signal from asg0
+ frequency=10e6, # demodulaltion at 10 MHz
+ bandwidth=1e5) # demodulation bandwidth of 100 kHz
+
+ # set up a PID controller on the demodulated signal and add result to out2
+ r.pid0.setup(input='iq0',
+ output_direct='out2', # add pid signal to output 2
+ setpoint=0.05, # pid setpoint of 50 mV
+ p=0.1, # proportional gain factor of 0.1
+ i=100, # integrator unity-gain-frequency of 100 Hz
+ input_filter = [3e3, 10e3]) # add 2 low-passes (3 and 10 kHz)
+
+ # modify some parameters in real-time
+ r.iq0.frequency += 2.3 # add 2.3 Hz to demodulation frequency
+ r.pid0.i *= 2 # double the integrator unity-gain-frequency
+
+ # take oscilloscope traces of the demodulated and pid signal
+ data = r.scope.curve(input1='iq0', input2='pid0',
+ duration=1.0, trigger_source='immediately')
+
+
+.. _high_level_example:
+
+High-level API example
+*************************
+
+.. code-block:: python
+
+ # import pyrpl library
+ import pyrpl
+
+ # create a Pyrpl object and store the configuration in a file 'filter-cavity.yml'
+ p = pyrpl.Pyrpl(config='filter-cavity')
+
+ # ... connect hardware (a Fabry-Perot cavity in this example) and
+ # configure its paramters with the PyRPL GUI that shows up
+
+ # sweep the cavity length
+ p.lockbox.sweep()
+
+ # calibrate the cavity parameters
+ p.lockbox.calibrate()
+
+ # lock to the resonance with a predefined sequence
+ p.lockbox.lock()
+
+ # launch two different measurements simultaneously
+ transfer_function = p.network_analyzer.single_async(
+ input='lockbox.reflection', output='out2',
+ start=1e3, stop=1e6, points=10000, rbw=1000)
+ spectrum = p.spectrum_analyzer.single_async(
+ input='in2', span=1e5, trace_averages=10)
+
+ # wait for measurements to finish
+ while not transfer_function.done() and not spectrum.done():
+ # check whether lock was lost
+ if not p.lockbox.is_locked():
+ # re-lock the cavity
+ p.lockbox.relock()
+ # re-start measurements
+ transfer_function = p.network_analyzer.single_async()
+ spectrum = p.spectrum_analyzer.single_async()
+
+ # display a measurement result in the curve browser
+ p.curve_viewer.curve = transfer_function.result()
+
+
+.. include:: user_feedback.rst
+
+
+.. include:: publications.rst
+
+
+.. include:: thanks.rst
+
+
+.. |travis status| image:: https://travis-ci.org/lneuhaus/pyrpl.svg?branch=master
+ :target: https://travis-ci.org/lneuhaus/pyrpl
+.. |appveyor status| image:: https://ci.appveyor.com/api/projects/status/wv2acmg869acg5yy?svg=true
+ :target: https://ci.appveyor.com/project/lneuhaus/pyrpl
+.. |code coverage| image:: https://codecov.io/github/lneuhaus/pyrpl/coverage.svg?branch=master
+ :target: https://codecov.io/gh/lneuhaus/pyrpl
+.. |Python versions on PyPI| image:: https://img.shields.io/pypi/pyversions/pyrpl.svg
+ :target: https://pypi.python.org/pypi/pyrpl/
+.. |PyRPL version on PyPI| image:: https://img.shields.io/pypi/v/pyrpl.svg
+ :target: https://pypi.python.org/pypi/pyrpl/
+.. |Download pyrpl| image:: https://img.shields.io/sourceforge/dt/pyrpl.svg
+ :target: https://sourceforge.net/projects/pyrpl/files/
+.. |Documentation Status| image:: https://readthedocs.org/projects/pyrpl/badge/?version=latest
+ :target: http://pyrpl.readthedocs.io/en/latest/
+.. |join chat on gitter| image:: https://badges.gitter.im/JoinChat.svg
+ :target: https://gitter.im/lneuhaus/pyrpl
+.. |License| image:: https://img.shields.io/pypi/l/pyrpl.svg
+ :target: https://github.com/lneuhaus/pyrpl/blob/master/LICENSE
+
+
+Old documentation sections
+**********************************************************
+
+The old documentation is obsolete and will soon be deleted. Please refer to the more recent documentation in the :ref:`manual` section.
+
+* :doc:`gallery/index`
+* :doc:`user_guide/index`
+* :doc:`reference_guide/index`
+* :doc:`developer_guide/index`
+* :doc:`indices_and_tables/index`
+* :doc:`contents`
+
+
+Current build status
+***********************
+
+|travis status| |appveyor status| |code coverage| |Python versions on PyPI| |PyRPL version on PyPI|
+
+|Download pyrpl| |Documentation Status| |join chat on gitter| |License|
+
+.. include:: changelog.rst
\ No newline at end of file
diff --git a/docs/source/indices_and_tables/pyrpl.hardware_modules.iir.rst b/docs/source/indices_and_tables/pyrpl.hardware_modules.iir.rst
index 9d8959f04..c3c3bc020 100644
--- a/docs/source/indices_and_tables/pyrpl.hardware_modules.iir.rst
+++ b/docs/source/indices_and_tables/pyrpl.hardware_modules.iir.rst
@@ -4,13 +4,6 @@ pyrpl\.hardware\_modules\.iir package
Submodules
----------
-pyrpl\.hardware\_modules\.iir\.bodefit module
----------------------------------------------
-
-.. automodule:: pyrpl.hardware_modules.iir.bodefit
- :members:
- :undoc-members:
- :show-inheritance:
pyrpl\.hardware\_modules\.iir\.iir module
-----------------------------------------
diff --git a/docs/source/installation.rst b/docs/source/installation.rst
new file mode 100644
index 000000000..7cf6ae497
--- /dev/null
+++ b/docs/source/installation.rst
@@ -0,0 +1,33 @@
+Installation
+*************
+
+Preparing the hardware
+=========================
+
+For PyRPL to work, you must have a working `Red Pitaya / StemLab `_ (`official documentation `_,
+* flash this image on 4 GB (or larger) micro SD card using `Win32DiskImager `_), and insert the card into your Red Pitaya, and
+* connect the Red Pitaya to your LAN and connect its power supply.
+
+:doc:`user_guide/installation/hardware_installation` gives more detailed instructions in case you are experiencing any trouble.
+
+
+.. _installing_pyrpl:
+
+Installing PyRPL
+=================
+
+The easiest and fastest way to get PyRPL running is to download and execute the latest precompiled executable for
+
+* **windows**: `pyrpl-windows.exe `__,
+* **linux**: `pyrpl-linux `__, or
+* **Mac OS X**: `pyrpl-mac `__.
+
+If you prefer an installation from source code, go to :ref:`installation_from_source`.
+
+
+Compiling the FPGA code (optional)
+===================================
+
+A ready-to-use FPGA bitfile comes with PyRPL. If you want to build your own, possibly customized bitfile, go to :doc:`developer_guide/fpga_compilation`.
\ No newline at end of file
diff --git a/docs/source/iq_widget.gif b/docs/source/iq_widget.gif
new file mode 100644
index 000000000..2cee1ebbb
Binary files /dev/null and b/docs/source/iq_widget.gif differ
diff --git a/docs/source/lockbox_widget.jpg b/docs/source/lockbox_widget.jpg
new file mode 100644
index 000000000..d66a72dfb
Binary files /dev/null and b/docs/source/lockbox_widget.jpg differ
diff --git a/docs/source/logo.png b/docs/source/logo.png
index f91208a11..111628ac0 100644
Binary files a/docs/source/logo.png and b/docs/source/logo.png differ
diff --git a/docs/source/logos/ANR.png b/docs/source/logos/ANR.png
new file mode 100644
index 000000000..332329454
Binary files /dev/null and b/docs/source/logos/ANR.png differ
diff --git a/docs/source/logos/CNRS.png b/docs/source/logos/CNRS.png
new file mode 100644
index 000000000..c11ea0420
Binary files /dev/null and b/docs/source/logos/CNRS.png differ
diff --git a/docs/source/logos/CQOM.png b/docs/source/logos/CQOM.png
new file mode 100644
index 000000000..415623615
Binary files /dev/null and b/docs/source/logos/CQOM.png differ
diff --git a/docs/source/logos/ENS.png b/docs/source/logos/ENS.png
new file mode 100644
index 000000000..59d2db4b3
Binary files /dev/null and b/docs/source/logos/ENS.png differ
diff --git a/docs/source/logos/LKB.png b/docs/source/logos/LKB.png
new file mode 100644
index 000000000..b114cfcd2
Binary files /dev/null and b/docs/source/logos/LKB.png differ
diff --git a/docs/source/logos/OMQ-2.png b/docs/source/logos/OMQ-2.png
new file mode 100755
index 000000000..d43804d04
Binary files /dev/null and b/docs/source/logos/OMQ-2.png differ
diff --git a/docs/source/logos/OMQ.png b/docs/source/logos/OMQ.png
new file mode 100755
index 000000000..18e7f5330
Binary files /dev/null and b/docs/source/logos/OMQ.png differ
diff --git a/docs/source/logos/UPMC.png b/docs/source/logos/UPMC.png
new file mode 100644
index 000000000..6e9adc54d
Binary files /dev/null and b/docs/source/logos/UPMC.png differ
diff --git a/docs/source/network_analyzer_widget.jpg b/docs/source/network_analyzer_widget.jpg
new file mode 100644
index 000000000..782746ca9
Binary files /dev/null and b/docs/source/network_analyzer_widget.jpg differ
diff --git a/docs/source/oldicon.ico b/docs/source/oldicon.ico
new file mode 100644
index 000000000..5d1b097af
Binary files /dev/null and b/docs/source/oldicon.ico differ
diff --git a/docs/source/oldlogo.png b/docs/source/oldlogo.png
new file mode 100644
index 000000000..f91208a11
Binary files /dev/null and b/docs/source/oldlogo.png differ
diff --git a/docs/source/pid_example.jpg b/docs/source/pid_example.jpg
new file mode 100644
index 000000000..791923552
Binary files /dev/null and b/docs/source/pid_example.jpg differ
diff --git a/docs/source/pid_widget.jpg b/docs/source/pid_widget.jpg
new file mode 100644
index 000000000..57f6f3b9d
Binary files /dev/null and b/docs/source/pid_widget.jpg differ
diff --git a/docs/source/publications.rst b/docs/source/publications.rst
new file mode 100644
index 000000000..48cfdf32f
--- /dev/null
+++ b/docs/source/publications.rst
@@ -0,0 +1,7 @@
+Publications about PyRPL
+***************************************
+
+
+1. `L. Neuhaus, R. Metzdorff, S. Chua, T. Jacqmin, T. Briant, A. Heidmann, P.-F. Cohadon, S. Deléglise, "PyRPL (Python Red Pitaya Lockbox) — An open-source software package for FPGA-controlled quantum optics experiments", 2017 Conference on Lasers and Electro-Optics Europe & European Quantum Electronics Conference (CLEO/Europe-EQEC), Munich, Germany, 2017. `_
+and gradually diverged away from it. In 2016, large parts of the graphical
+user interface were added to the project by Samuel Deleglise. PyRPL was finally
+published as an open-source project under the GNU General Public License, Version 3
+and has been online since July 2017.
diff --git a/docs/source/user_feedback.rst b/docs/source/user_feedback.rst
new file mode 100644
index 000000000..801f1f3b8
--- /dev/null
+++ b/docs/source/user_feedback.rst
@@ -0,0 +1,41 @@
+.. _user_feedback:
+
+Feedback by PyRPL users
+*********************************
+
+
+.. admonition:: PyRPL was developed for and is one of the core components of three ongoing experiments in Quantum Cavity Optomechanics
+
+ in the `Optomechanics and Quantum Measurement Group `_ of the `Technical University of Denmark `_,
+ * Development team at `Sacher Lasertechnik `_ at `ILM `_ at the `Quantum Metrology division `_ of the `National Institute of Standards and Technology (NIST) `_ of the `École Polytechnique Fédérale de Lausanne (EPFL) `_.
+
+
+If you are using PyRPL and would like to help to promote the project, please send your feedback to `pyrpl.readthedocs.io@gmail.com `_ and we will include your voice on this page.
diff --git a/docs/source/user_guide/installation/hardware_installation.rst b/docs/source/user_guide/installation/hardware_installation.rst
index bba2d6026..1cd4f3063 100644
--- a/docs/source/user_guide/installation/hardware_installation.rst
+++ b/docs/source/user_guide/installation/hardware_installation.rst
@@ -1,42 +1,32 @@
Hardware installation for PyRPL
*********************************
-The `RedPitaya `_. Flash this image on a >= 4 GB SD card using a tool like `Win32DiskImager `_ connected to the same local area network (LAN) as the computer PyRPL is running on. PyRPL is compatible with all operating system versions of the Red Pitaya and does not require any customization of the Red Pitaya. If you have not already set up your Red Pitaya, you have two options: :ref:`sdcard_092` or :ref:`sdcard_quick`. You should :ref:`sdcard_check` at the end.
+
+
+.. _sdcard_092:
+
+Install a minimum-weight SD card (recommended)
+================================================
+
+Just download and unzip the `Red Pitaya OS Version 0.92 image `_. Flash this image on a >= 4 GB SD card using a tool like `Win32DiskImager `__. This option requires no extra programs to be installed on the computer. If you want the Pyrpl binaries for a Mac, please let us know `by creating a new issue `_ and we will prepare them for you.
+The easiest and fastest way to get PyRPL running is to download and execute the `precompiled executable for windows "pyrpl-windows.exe" `__ or `linux "pyrpl-linux" `__. This option requires no extra programs to be installed on the computer. If you want the Pyrpl binaries for a Mac, please let us know `by creating a new issue `_ and we will prepare them for you.
+
+
+.. _installation_from_source:
-The Hacker's way: Running the Python source code
-================================================
+Running the Python source code
+===================================
If you would like to use and/or modify the source code, make sure you have an installation of Python (2.7, 3.4, 3.5, or 3.6).
@@ -27,11 +29,11 @@ Option 1: Installation from Anaconda
If you are new to Python or unexperienced with fighting installation issues, it is recommended to install the `Anaconda `__ Python distribution, which allows to install all PyRPL dependencies via::
- conda install numpy scipy paramiko pandas nose pip pyqt qtpy pyqtgraph pyyaml
+ conda install numpy scipy paramiko pandas nose pip pyqt qtpy pyqtgraph pyyaml nbconvert
Check :ref:`anaconda_problems` for hints if you cannot execute conda in a terminal. Alternatively, if you prefer creating a virtual environment for pyrpl, do so with the following two commands::
- conda create -y -n pyrpl-env numpy scipy paramiko pandas nose pip pyqt qtpy pyqtgraph pyyaml
+ conda create -y -n pyrpl-env numpy scipy paramiko pandas nose pip pyqt qtpy pyqtgraph pyyaml nbconvert
activate pyrpl-env
@@ -54,8 +56,9 @@ Downloading and installing PyRPL from source
Various channels are available to obtain the PyRPL source code.
+
Option 1: Installation with pip (recommended, for standard users)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~`
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If you have pip correctly installed, executing the following line in a command line should install pyrpl and all missing dependencies::
diff --git a/docs/source/user_guide/tutorial/index.rst b/docs/source/user_guide/tutorial/index.rst
index fd2d9b500..afbb37300 100644
--- a/docs/source/user_guide/tutorial/index.rst
+++ b/docs/source/user_guide/tutorial/index.rst
@@ -1,7 +1,7 @@
Quickstart Tutorial for PyRPL
********************************
-You can download the tutorial in form of a :download:`Jupyter notebook file ` or in :download:`HTML-form `.
+You can download the API tutorial in form of a :download:`Jupyter notebook file ` or in :download:`HTML-form `.
.. raw:: html
diff --git a/docs/source/user_guide/tutorial/tutorial.html b/docs/source/user_guide/tutorial/tutorial.html
index 669354840..aa4608166 100644
--- a/docs/source/user_guide/tutorial/tutorial.html
+++ b/docs/source/user_guide/tutorial/tutorial.html
@@ -11726,7 +11726,9 @@
div#notebook {
overflow: visible;
border-top: none;
-}@media print {
+}
+
+@media print {
div.cell {
display: block;
page-break-inside: avoid;
@@ -11747,7 +11749,7 @@
-
+