Hardware ODE solver with HPS control

ECE 5760, Spring 2022, Adams/Land

In [31]:
HTML('''<script>
code_show=true; 
function code_toggle() {
 if (code_show){
 $('div.input').hide();
 } else {
 $('div.input').show();
 }
 code_show = !code_show
} 
$( document ).ready(code_toggle);
</script>
<form action="javascript:code_toggle()"><input type="submit" value="Click here to toggle on/off the raw code."></form>''')
Out[31]:
In [30]:
import matplotlib.pyplot as plt
from IPython.display import HTML
plt.rcParams["figure.figsize"] = (20,3)
import numpy

Introduction

For this laboratory exercise, you will be asked to build a Digital Differential Analyzer (DDA) in Verilog that integrates the Lorenz system. The Lorenz system generates (arguably) one of the most famous and beautiful structures in mathematics: the "butterfly curve" (from which the "butterfly effect" gets its name). For certain parameter values and initial conditions, the solutions for the Lorenz system are chaotic. That is to say, they are deterministic yet unpredictable. The solutions are so sensitive to initial conditions that, after sufficient time, it is no longer possible to determine the path that the system will take without running a simulation. Meditate on the notion of "deterministic yet unpredictable" for long enough and you may end up questioning things like your own free will. But I digress.

The DDA circuit that you build will be controlled by the HPS. Controlling the DDA involves clocking it and setting initial conditions/parameter values. You will build a system that allows for you to play with the Lorenz system. The VGA screen will display all three projections of the 3D curve, and your user interface will support speeding up/slowing down animation, pausing/resuming animation, clearing the screen, dynamically changing parameters, and resetting with a new set of user-specified initial conditions. This is all demonstrated in the video below.

Mathematical Background

Equations

The Lorenz system is described by a set of three coupled ordinary differential equations, given below:

\begin{align} \frac{dx}{dt} &= \sigma (y-x)\\ \frac{dy}{dt} &= x(\rho-z) - y\\ \frac{dz}{dt} &= xy - \beta z \end{align}

You will numerically integrate these differential equations using the Euler method, the simplest of all numerical integration techniques. The Euler method linearizes about the values of the state variables $x$, $y$, and $z$ at the current timestep to approximate the values of the state variables at the next timestep. That is:

\begin{align} x(k+1) &= x(k) + dt \cdot \left(\frac{dx}{dt}\right)\bigg|_{x=x(k)}\\ y(k+1) &= y(k) + dt \cdot \left(\frac{dy}{dt}\right)\bigg|_{y=y(k)}\\ z(k+1) &= z(k) + dt \cdot \left(\frac{dz}{dt}\right)\bigg|_{z=z(k)} \end{align}

Starting this iteration requires initial values for $x$, $y$, and $z$ and parameter values for $\sigma$, $\beta$, $\rho$, and $dt$. Ultimately, your system will accept arbitrary initial conditions and parameter values. However, use the following as the default settings:

\begin{align} \sigma &= 10 && x(0) = -1\\ \beta &= \frac{8}{3} && y(0) = 0.1\\ \rho &= 28 && z(0) = 25 \\ dt &= \frac{1}{256} \end{align}

Example Python code

The Python code below provides a reference solution to which you may compare your solutions. But remember that your solutions will not match exactly because the system is chaotic. One of the first steps for this lab is to simulate the solver in hardware in ModelSim to produce something like the following curves. For your amusement, here is an interactive 3D plot of the Lorenz system.

dt = (1./256)
x = [-1.]
y = [0.1]
z = [25.]
sigma = 10.0
beta = 8./3.
rho = 28.0

def dx(sigma, x, y):
    return sigma*(y-x)

def dy(rho, x, y, z):
    return x*(rho-z)-y

def dz(beta, x, y, z):
    return x*y - beta*z

for i in range(10000):
    x.extend([x[i] + dt*dx(sigma, x[i], y[i])])
    y.extend([y[i] + dt*dy(rho, x[i], y[i], z[i])])
    z.extend([z[i] + dt*dz(beta, x[i], y[i], z[i])])
In [38]:
dt = (1./256)
x = [-1.]
y = [0.1]
z = [25.]
sigma = 10.0
beta = 8./3.
rho = 28.0

def dx(sigma, x, y):
    return sigma*(y-x)

def dy(rho, x, y, z):
    return x*(rho-z)-y

def dz(beta, x, y, z):
    return x*y - beta*z

for i in range(10000):
    x.extend([x[i] + dt*dx(sigma, x[i], y[i])])
    y.extend([y[i] + dt*dy(rho, x[i], y[i], z[i])])
    z.extend([z[i] + dt*dz(beta, x[i], y[i], z[i])])
    
plt.plot(x)
plt.ylabel('X', fontsize=18)
plt.show()
plt.plot(y)
plt.ylabel('Y', fontsize=18)
plt.show()
plt.plot(z)
plt.ylabel('Z', fontsize=18)
plt.ylim([-10, 50])
plt.show()

# import plotly.graph_objects as go

# fig = go.Figure(data=go.Scatter3d(x=x,
#                                   y=y,
#                                   z=z,
#                                   mode='markers',
#                                   marker=dict(
#                                       size=2)))
# fig.write_html("./test.html")
# fig.show()

Hardware implementation of solver

You will be asked to implement the above Euler integrator in hardware using Verilog. The circuit that you will build is illustrated below.

missing

Setup and resources

For most exercises there will be 5 or six connections to the board: serial, ethernet, VGA, audio (for lab 2), USB blaster, power. See the image below.

missing

You may find the following resources useful:

Procedure and Weekly Checkpoints


Week 1

  1. Use this guide and the Linux on HPS page to get the DE1-SoC setup.
  2. Review Verilog basics
  3. Read the DDA webpage. After reading the page down through Second order system, stop. The integrator code that you want to start from is in this snippet.
  4. Read about fixed point arithmetic. We suggest a fixed point format of something like 7.20, with a range of +/-63 and a delta of $10^{-6}$. You will need to use a signed, fixed-point multiplier module and an integrator module similar to those in this code snippet. The arithmetic system will use 27-bit multiplies, which on our FPGAs take one hardware multiplier (DSP module). You could use floating point (and Floating DDA) instead, if you want to be slightly adventurous.
  5. Start by simulating in Matlab or Python! On the FPGA you are going to be using a simple Euler integration. The Python program above is coded to use Euler integration so that you can directly compare the FPGA solution. Make sure that for the constants and initial conditions that you choose no state variable (or intermediate result) goes outside the range +/-63.
  6. Next, simulate your synthesizable verilog in Modelsim until you get the same result as you did in Matlab or Python. You will need to write a testbench which sets the same constants and initial conditions as the Python code. One way to check the solver is to export the Modelsim solution vectors to Matlab or Python and create a 3D plot similar to this one. Your Modelsim traces will look something like those shown below.
    missing
  7. Once you've verified your compute module in Modelsim (not before!), you're ready to read the solutions back to the HPS for visualization on the VGA display.

Week 2

  1. Test 2D drawing from the HPS to the VGA display by drawing a sine wave data plot. A good place to start for the HPS to VGA interface is to search for Video VGA 640x480 displayed from SDRAM, in 16-bit color on the DE1-SoC: University Computer page. In particular, start from the final example in that section (the graphics primitives in 16-bit color example).
  2. Connect your solver output to the HPS using parallel i/o port bus-slaves. In Qsys, remember to export the connections to the FPGA solver. Also remember that you have to assign unique addresses in Qsys to each PIO port and use those addresses in the C-code running on the HPS. A small example defines two PIO ports in Qsys, displays counts on LEDs in Verilog, and controls the counts in C. Remember that you will have to sign-extend the 7.20 numbers into full 32-bit notation. The easiest way to do this is to use hardware to concantenate 5 sign bits onto the 27 bit fixed point numbers.
  3. Demonstrate SignalTap, an onboard logic analyzer, connected to your solver. Prove that the output of your solver on the FPGA matches the output of your solver on Modelsim. Later labs will assume you know how to use SignalTap.
    missing
    Solver output from Modelsim
    missing
    Solver output from SignalTap
  4. With hard-coded parameter values, demonstrate the hardware solver communicating solutions to the HPS and plotting those solutions to the VGA display. At reset, the system should start drawing all three projections of the Lorenz curve. At this point, you need not have any command-line interface implemented for interacting with this system.

Week 3

  1. When a hard-coded version plots correctly, build the PIO bus-slaves necessary to control reset function and set constants from the HPS, then start on the command software for console control. I suggest a simple command interpreter to enter the three constants, three initial conditions, start/stop, and reset. You will probably also signal a solution time step request from the HPS to synchronize the solver and the graphics.
  2. Remember that a parallel I/O port (PIO) which provides data from the HPS to the FPGA is an output! To get the PIO datasheet in Qsys, right-click the module name and in the pop-up menu, select details>datasheet. Some other modules require that you follow the path details>open_component_folderto get the datasheet.
  3. In your demonstration, you will be asked to set initial conditions/parameter values and then start the integration animation. As the system is animating, we will ask you to speed up/slow down that animation and to pause/resume animation. We will also ask for you to clear the screen while the animation is running. You will be asked to change values for the parameters $\sigma$, $\beta$, and $\rho$ while the animation is running, and you will be asked to reset the system with a new set of initial conditions. The VGA screen should also display the values for the parameters $\sigma$, $\beta$, and $\rho$. The video demonstration at the top of this webpage demonstrates all of the functionality that you will be asked to demonstrate.

Lab reports

Your lab reports should include:

  • Everything from the policy page
  • Mathematical considerations (type of integrator, error expected/measured, approximations)
  • a 3D plot of the solution vectors exported from the Verilog simulator
  • Photos of the VGA
  • How you implemented the DDA circuits
  • A heavily commented listing of your Verilog design and GCC code.