From ec645d35896fcd0098f96d72f7cfca1ffd9435db Mon Sep 17 00:00:00 2001
From: whitequark <whitequark@whitequark.org>
Date: Sun, 20 Nov 2016 09:48:49 +0000
Subject: [PATCH] coredevice.dds: work around the round(numpy.float64()) snafu.

---
 artiq/coredevice/dds.py |  6 +++---
 doc/manual/compiler.rst | 31 +++++++++++++++++++++++++++++--
 2 files changed, 32 insertions(+), 5 deletions(-)

diff --git a/artiq/coredevice/dds.py b/artiq/coredevice/dds.py
index 63a147742..1437ff2df 100644
--- a/artiq/coredevice/dds.py
+++ b/artiq/coredevice/dds.py
@@ -112,7 +112,7 @@ class _DDSGeneric:
         """Returns the frequency tuning word corresponding to the given
         frequency.
         """
-        return round(int64(2)**32*frequency/self.core_dds.sysclk)
+        return round(float(int64(2)**32*frequency/self.core_dds.sysclk))
 
     @portable(flags=["fast-math"])
     def ftw_to_frequency(self, ftw):
@@ -125,7 +125,7 @@ class _DDSGeneric:
     def turns_to_pow(self, turns):
         """Returns the phase offset word corresponding to the given phase
         in turns."""
-        return round(turns*2**self.pow_width)
+        return round(float(turns*2**self.pow_width))
 
     @portable(flags=["fast-math"])
     def pow_to_turns(self, pow):
@@ -136,7 +136,7 @@ class _DDSGeneric:
     @portable(flags=["fast-math"])
     def amplitude_to_asf(self, amplitude):
         """Returns amplitude scale factor corresponding to given amplitude."""
-        return round(amplitude*0x0fff)
+        return round(float(amplitude*0x0fff))
 
     @portable(flags=["fast-math"])
     def asf_to_amplitude(self, asf):
diff --git a/doc/manual/compiler.rst b/doc/manual/compiler.rst
index 6a8271a5f..9d9cc95eb 100644
--- a/doc/manual/compiler.rst
+++ b/doc/manual/compiler.rst
@@ -10,7 +10,7 @@ A number of Python features can be used inside a kernel for compilation and exec
 
 * Booleans
 * 32-bit signed integers (default size)
-* 64-bit signed integers (use ``int(n, width=64)`` to convert)
+* 64-bit signed integers (use ``numpy.int64`` to convert)
 * Double-precision floating point numbers
 * Lists of any supported types
 * User-defined classes, with attributes of any supported types (attributes that are not used anywhere in the kernel are ignored)
@@ -36,7 +36,7 @@ The Python types correspond to ARTIQ type annotations as follows:
 +-------------+-------------------------+
 | bool        | TBool                   |
 +-------------+-------------------------+
-| int         | TInt32, TInt64          |
+| int         | TInt32 or TInt64        |
 +-------------+-------------------------+
 | float       | TFloat                  |
 +-------------+-------------------------+
@@ -46,6 +46,33 @@ The Python types correspond to ARTIQ type annotations as follows:
 +-------------+-------------------------+
 | range       | TRange32, TRange64      |
 +-------------+-------------------------+
+| numpy.int32 | TInt32                  |
++-------------+-------------------------+
+| numpy.int64 | TInt64                  |
++-------------+-------------------------+
+| numpy.float64 | TFloat                |
++-------------+-------------------------+
+
+Pitfalls
+--------
+
+The ARTIQ compiler accepts *nearly* a strict subset of Python 3. However, by necessity there
+is a number of differences that can lead to bugs.
+
+Arbitrary-length integers are not supported at all on the core device; all integers are
+either 32-bit or 64-bit. This especially affects calculations that result in a 32-bit signed
+overflow; if the compiler detects a constant that doesn't fit into 32 bits, the entire expression
+will be upgraded to 64-bit arithmetics, however if all constants are small, 32-bit arithmetics
+will be used even if the result will overflow. Overflows are not detected.
+
+The result of calling the builtin ``round`` function is different when used with
+the builtin ``float`` type and the ``numpy.float64`` type on the host interpreter; ``round(1.0)``
+returns an integer value 1, whereas ``round(numpy.float64(1.0))`` returns a floating point value
+``numpy.float64(1.0)``. Since both ``float`` and ``numpy.float64`` are mapped to
+the builtin ``float`` type on the core device, this can lead to problems in functions marked
+``@portable``; the workaround is to explicitly cast the argument of ``round`` to ``float``:
+``round(float(numpy.float64(1.0)))`` returns an integer on the core device as well as on the host
+interpreter.
 
 Additional optimizations
 ------------------------