Merge branch 'namespace-experiment'

closes #189

* namespace-experiment:
  artiq_dir: move out of tools to unlink dependencies
  refactor Analyzer constants to unlink dependencies
  CoreException: store at 'py_exn.artiq_core_exception'
  doc: update Underflow catching example
  coredevice: remove some print()s
  language...ARTIQException -> coredevice...CoreException
  artiq.experiment: update examples
  artiq.experiment: merge language and coredevice namespaces
  artiq: move namespace artiq.* -> artiq.language.*

artiq/__init__.py

@@ -1,13 +1,7 @@
-from artiq import language
-from artiq.language import *
-from artiq.coredevice.dds import (PHASE_MODE_CONTINUOUS, PHASE_MODE_ABSOLUTE,
-                                  PHASE_MODE_TRACKING)
-
-__all__ = []
-__all__.extend(language.__all__)
-__all__ += ["PHASE_MODE_CONTINUOUS", "PHASE_MODE_ABSOLUTE",
-            "PHASE_MODE_TRACKING"]
-
 from ._version import get_versions
 __version__ = get_versions()['version']
 del get_versions
+
+import os
+__artiq_dir__ = os.path.dirname(os.path.abspath(__file__))
+del os

artiq/coredevice/__init__.py

@@ -0,0 +1,10 @@
+from artiq.coredevice import exceptions, dds
+from artiq.coredevice.exceptions import (RTIOUnderflow, RTIOSequenceError,
+                                         RTIOCollisionError)
+from artiq.coredevice.dds import (PHASE_MODE_CONTINUOUS, PHASE_MODE_ABSOLUTE,
+                                  PHASE_MODE_TRACKING)
+
+__all__ = []
+__all__ += ["RTIOUnderflow", "RTIOSequenceError", "RTIOCollisionError"]
+__all__ += ["PHASE_MODE_CONTINUOUS", "PHASE_MODE_ABSOLUTE",
+            "PHASE_MODE_TRACKING"]

artiq/coredevice/analyzer.py

@@ -1,33 +1,15 @@
 from operator import itemgetter
 from collections import namedtuple
 from itertools import count
-from enum import Enum
 import struct
 import logging
 
+from artiq.gateware.rtio.analyzer_common import MessageType, ExceptionType
+
 
 logger = logging.getLogger(__name__)
 
 
-class MessageType(Enum):
-    output = 0b00
-    input = 0b01
-    exception = 0b10
-
-
-class ExceptionType(Enum):
-    reset_rising = 0b000000
-    reset_falling = 0b000001
-    reset_phy_rising = 0b000010
-    reset_phy_falling = 0b000011
-
-    o_underflow_reset = 0b010000
-    o_sequence_error_reset = 0b010001
-    o_collision_error_reset = 0b010010
-
-    i_overflow_reset = 0b100000
-
-
 OutputMessage = namedtuple(
     "OutputMessage", "channel timestamp rtio_counter address data")
 

artiq/coredevice/comm_generic.py

@@ -4,7 +4,6 @@ import traceback
 from enum import Enum
 from fractions import Fraction
 
-from artiq.language import core as core_language
 from artiq.coredevice import exceptions
 from artiq import __version__ as software_version
 
@@ -458,8 +457,8 @@ class CommGeneric:
 
             self._write_header(_H2DMsgType.RPC_EXCEPTION)
 
-            if hasattr(exn, 'artiq_exception'):
-                exn = exn.artiq_exception
+            if hasattr(exn, 'artiq_core_exception'):
+                exn = exn.artiq_core_exception
                 self._write_string(exn.name)
                 self._write_string(exn.message)
                 for index in range(3):
@@ -505,16 +504,15 @@ class CommGeneric:
 
         traceback = list(reversed(symbolizer(backtrace))) + \
                     [(filename, line, column, function, None)]
-        exception = core_language.ARTIQException(name, message, params, traceback)
+        core_exn = exceptions.CoreException(name, message, params, traceback)
 
-        print(exception.id, exception.name)
-        if exception.id == 0:
-            python_exn_type = getattr(exceptions, exception.name.split('.')[-1])
+        if core_exn.id == 0:
+            python_exn_type = getattr(exceptions, core_exn.name.split('.')[-1])
         else:
-            python_exn_type = object_map.retrieve(exception.id)
+            python_exn_type = object_map.retrieve(core_exn.id)
 
         python_exn = python_exn_type(message.format(*params))
-        python_exn.artiq_exception = exception
+        python_exn.artiq_core_exception = core_exn
         raise python_exn
 
     def serve(self, object_map, symbolizer):

artiq/coredevice/core.py

@@ -2,6 +2,8 @@ import os, sys
 
 from pythonparser import diagnostic
 
+from artiq import __artiq_dir__ as artiq_dir
+
 from artiq.language.core import *
 from artiq.language.types import *
 from artiq.language.units import *
@@ -16,7 +18,7 @@ from artiq.coredevice import exceptions
 
 def _render_diagnostic(diagnostic, colored):
     def shorten_path(path):
-        return path.replace(os.path.normpath(os.path.join(__file__, "..", "..")), "<artiq>")
+        return path.replace(artiq_dir, "<artiq>")
     lines = [shorten_path(path) for path in diagnostic.render(colored)]
     return "\n".join(lines)
 

artiq/coredevice/exceptions.py

@@ -1,5 +1,10 @@
 import builtins
-from artiq.language.core import ARTIQException
+import linecache
+import re
+import os
+
+from artiq import __artiq_dir__ as artiq_dir
+from artiq.coredevice.runtime import source_loader
 
 
 ZeroDivisionError = builtins.ZeroDivisionError
@@ -7,6 +12,50 @@ ValueError = builtins.ValueError
 IndexError = builtins.IndexError
 
 
+class CoreException:
+    """Information about an exception raised or passed through the core device."""
+
+    def __init__(self, name, message, params, traceback):
+        if ':' in name:
+            exn_id, self.name = name.split(':', 2)
+            self.id = int(exn_id)
+        else:
+            self.id, self.name = 0, name
+        self.message, self.params = message, params
+        self.traceback = list(traceback)
+
+    def __str__(self):
+        lines = []
+        lines.append("Core Device Traceback (most recent call last):")
+        for (filename, line, column, function, address) in self.traceback:
+            stub_globals = {"__name__": filename, "__loader__": source_loader}
+            source_line = linecache.getline(filename, line, stub_globals)
+            indentation = re.search(r"^\s*", source_line).end()
+
+            if address is None:
+                formatted_address = ""
+            else:
+                formatted_address = " (RA=0x{:x})".format(address)
+
+            filename = filename.replace(artiq_dir, "<artiq>")
+            if column == -1:
+                lines.append("  File \"{file}\", line {line}, in {function}{address}".
+                             format(file=filename, line=line, function=function,
+                                    address=formatted_address))
+                lines.append("    {}".format(source_line.strip() if source_line else "<unknown>"))
+            else:
+                lines.append("  File \"{file}\", line {line}, column {column},"
+                             " in {function}{address}".
+                             format(file=filename, line=line, column=column + 1,
+                                    function=function, address=formatted_address))
+                lines.append("    {}".format(source_line.strip() if source_line else "<unknown>"))
+                lines.append("    {}^".format(" " * (column - indentation)))
+
+        lines.append("{}({}): {}".format(self.name, self.id,
+                                         self.message.format(*self.params)))
+        return "\n".join(lines)
+
+
 class InternalError(Exception):
     """Raised when the runtime encounters an internal error condition."""
     artiq_builtin = True

artiq/coredevice/runtime.py

@@ -1,13 +1,14 @@
 import os
 
+from artiq import __artiq_dir__ as artiq_dir
+
+
 class SourceLoader:
     def __init__(self, runtime_root):
         self.runtime_root = runtime_root
 
     def get_source(self, filename):
-        print(os.path.join(self.runtime_root, filename))
         with open(os.path.join(self.runtime_root, filename)) as f:
             return f.read()
 
-artiq_root = os.path.join(os.path.dirname(__file__), "..", "..")
-source_loader = SourceLoader(os.path.join(artiq_root, "soc", "runtime"))
+source_loader = SourceLoader(os.path.join(artiq_dir, "soc", "runtime"))

artiq/experiment.py

@@ -0,0 +1,7 @@
+from artiq import language, coredevice
+from artiq.language import *
+from artiq.coredevice import *
+
+__all__ = []
+__all__.extend(language.__all__)
+__all__.extend(coredevice.__all__)

artiq/frontend/artiq_flash.py

@@ -7,6 +7,7 @@ import subprocess
 import tempfile
 
 import artiq
+from artiq import __artiq_dir__ as artiq_dir
 from artiq.frontend.bit2bin import bit2bin
 
 
@@ -70,7 +71,7 @@ def main():
     }[opts.target]
 
     if opts.dir is None:
-        opts.dir = os.path.join(os.path.dirname(artiq.__file__), "binaries",
+        opts.dir = os.path.join(artiq_dir, "binaries",
                                 "{}-{}".format(opts.target, opts.adapter))
 
     conv = False

artiq/frontend/artiq_gui.py

@@ -10,6 +10,7 @@ import os
 from quamash import QEventLoop, QtGui, QtCore
 from pyqtgraph import dockarea
 
+from artiq import __artiq_dir__ as artiq_dir
 from artiq.tools import *
 from artiq.protocols.pc_rpc import AsyncioClient
 from artiq.gui.models import ModelSubscriber

artiq/frontend/artiq_run.py

@@ -132,8 +132,8 @@ def run(with_file=False):
     except CompileError as error:
         return
     except Exception as exn:
-        if hasattr(exn, 'artiq_exception'):
-            print(exn.artiq_exception, file=sys.stderr)
+        if hasattr(exn, 'artiq_core_exception'):
+            print(exn.artiq_core_exception, file=sys.stderr)
         raise exn
     finally:
         device_mgr.close_devices()

artiq/gateware/rtio/analyzer.py

@@ -3,7 +3,7 @@ from migen.genlib.record import Record, layout_len
 from misoc.interconnect.csr import *
 from misoc.interconnect import stream
 
-from artiq.coredevice.analyzer import MessageType, ExceptionType
+from artiq.gateware.rtio.analyzer_common import MessageType, ExceptionType
 
 
 __all__ = ["Analyzer"]

artiq/gateware/rtio/analyzer_common.py

@@ -0,0 +1,20 @@
+from enum import Enum
+
+
+class MessageType(Enum):
+    output = 0b00
+    input = 0b01
+    exception = 0b10
+
+
+class ExceptionType(Enum):
+    reset_rising = 0b000000
+    reset_falling = 0b000001
+    reset_phy_rising = 0b000010
+    reset_phy_falling = 0b000011
+
+    o_underflow_reset = 0b010000
+    o_sequence_error_reset = 0b010001
+    o_collision_error_reset = 0b010010
+
+    i_overflow_reset = 0b100000

artiq/gateware/targets/kc705.py

@@ -20,7 +20,7 @@ from misoc.targets.kc705 import MiniSoC, soc_kc705_args, soc_kc705_argdict
 from artiq.gateware.soc import AMPSoC
 from artiq.gateware import rtio, nist_qc1, nist_clock, nist_qc2
 from artiq.gateware.rtio.phy import ttl_simple, ttl_serdes_7series, dds
-from artiq.tools import artiq_dir
+from artiq import __artiq_dir__ as artiq_dir
 from artiq import __version__ as artiq_version
 
 

artiq/gateware/targets/pipistrello.py

@@ -20,7 +20,7 @@ from misoc.targets.pipistrello import *
 from artiq.gateware.soc import AMPSoC
 from artiq.gateware import rtio, nist_qc1
 from artiq.gateware.rtio.phy import ttl_simple, ttl_serdes_spartan6, dds
-from artiq.tools import artiq_dir
+from artiq import __artiq_dir__ as artiq_dir
 from artiq import __version__ as artiq_version
 
 

artiq/language/__init__.py

@@ -1,5 +1,3 @@
-# Copyright (C) 2014, 2015 Robert Jordens <jordens@gmail.com>
-
 from artiq.language import core, types, environment, units, scan
 from artiq.language.core import *
 from artiq.language.types import *
@@ -7,7 +5,6 @@ from artiq.language.environment import *
 from artiq.language.units import *
 from artiq.language.scan import *
 
-
 __all__ = []
 __all__.extend(core.__all__)
 __all__.extend(types.__all__)

artiq/language/core.py

@@ -2,18 +2,13 @@
 Core ARTIQ extensions to the Python language.
 """
 
-import os, linecache, re
 from collections import namedtuple
 from functools import wraps
 
-# for runtime files in backtraces
-from artiq.coredevice.runtime import source_loader
-
 
 __all__ = ["host_int", "int", "host_round", "round",
            "kernel", "portable", "syscall", "host_only",
            "set_time_manager", "set_watchdog_factory",
-           "ARTIQException",
            "TerminationRequested"]
 
 # global namespace for kernels
@@ -375,48 +370,3 @@ def watchdog(timeout):
 class TerminationRequested(Exception):
     """Raised by ``pause`` when the user has requested termination."""
     pass
-
-
-class ARTIQException:
-    """Information about an exception raised or passed through the core device."""
-
-    def __init__(self, name, message, params, traceback):
-        if ':' in name:
-            exn_id, self.name = name.split(':', 2)
-            self.id = host_int(exn_id)
-        else:
-            self.id, self.name = 0, name
-        self.message, self.params = message, params
-        self.traceback = list(traceback)
-
-    def __str__(self):
-        lines = []
-        lines.append("Core Device Traceback (most recent call last):")
-        for (filename, line, column, function, address) in self.traceback:
-            stub_globals = {"__name__": filename, "__loader__": source_loader}
-            source_line = linecache.getline(filename, line, stub_globals)
-            indentation = re.search(r"^\s*", source_line).end()
-
-            if address is None:
-                formatted_address = ""
-            else:
-                formatted_address = " (RA=0x{:x})".format(address)
-
-            filename = filename.replace(os.path.normpath(os.path.join(os.path.dirname(__file__),
-                                                                      "..")), "<artiq>")
-            if column == -1:
-                lines.append("  File \"{file}\", line {line}, in {function}{address}".
-                             format(file=filename, line=line, function=function,
-                                    address=formatted_address))
-                lines.append("    {}".format(source_line.strip() if source_line else "<unknown>"))
-            else:
-                lines.append("  File \"{file}\", line {line}, column {column},"
-                             " in {function}{address}".
-                             format(file=filename, line=line, column=column + 1,
-                                    function=function, address=formatted_address))
-                lines.append("    {}".format(source_line.strip() if source_line else "<unknown>"))
-                lines.append("    {}^".format(" " * (column - indentation)))
-
-        lines.append("{}({}): {}".format(self.name, self.id,
-                                         self.message.format(*self.params)))
-        return "\n".join(lines)

artiq/test/coredevice/analyzer.py

@@ -1,4 +1,4 @@
-from artiq.language import *
+from artiq.experiment import *
 from artiq.coredevice.analyzer import decode_dump, OutputMessage, InputMessage
 from artiq.test.hardware_testbench import ExperimentCase
 

artiq/test/coredevice/cache.py

@@ -1,5 +1,4 @@
-from artiq.language import *
-from artiq.coredevice.exceptions import *
+from artiq.experiment import *
 from artiq.test.hardware_testbench import ExperimentCase
 
 

artiq/test/coredevice/embedding.py

@@ -1,4 +1,4 @@
-from artiq.language import *
+from artiq.experiment import *
 from artiq.test.hardware_testbench import ExperimentCase
 
 

artiq/test/coredevice/portability.py

@@ -1,7 +1,7 @@
 from operator import itemgetter
 from fractions import Fraction
 
-from artiq import *
+from artiq.experiment import *
 from artiq.sim import devices as sim_devices
 from artiq.test.hardware_testbench import ExperimentCase
 

artiq/test/coredevice/rtio.py

@@ -3,10 +3,8 @@
 
 from math import sqrt
 
-from artiq.language import *
+from artiq.experiment import *
 from artiq.test.hardware_testbench import ExperimentCase
-from artiq.coredevice.exceptions import (RTIOUnderflow, RTIOSequenceError,
-                                         RTIOCollisionError)
 
 
 class RTT(EnvExperiment):

artiq/test/hardware_testbench.py

@@ -6,7 +6,7 @@ import sys
 import unittest
 import logging
 
-from artiq.language import *
+from artiq.experiment import *
 from artiq.master.databases import DeviceDB, DatasetDB
 from artiq.master.worker_db import DeviceManager, DatasetManager
 from artiq.coredevice.core import CompileError

artiq/test/scheduler.py

@@ -5,7 +5,7 @@ import sys
 import os
 from time import time, sleep
 
-from artiq import *
+from artiq.experiment import *
 from artiq.master.scheduler import Scheduler
 
 

artiq/test/worker.py

@@ -5,7 +5,7 @@ import sys
 import os
 from time import sleep
 
-from artiq import *
+from artiq.experiment import *
 from artiq.master.worker import *
 
 

artiq/tools.py

@@ -16,7 +16,7 @@ from artiq.language.environment import is_experiment
 from artiq.protocols import pyon
 
 
-__all__ = ["artiq_dir", "parse_arguments", "elide", "short_format", "file_import",
+__all__ = ["parse_arguments", "elide", "short_format", "file_import",
            "get_experiment", "verbosity_args", "simple_network_args", "init_logger",
            "bind_address_from_args", "atexit_register_coroutine",
            "exc_to_warning", "asyncio_wait_or_cancel",
@@ -25,8 +25,6 @@ __all__ = ["artiq_dir", "parse_arguments", "elide", "short_format", "file_import
 
 logger = logging.getLogger(__name__)
 
-artiq_dir = os.path.join(os.path.abspath(os.path.dirname(__file__)))
-
 
 def parse_arguments(arguments):
     d = {}

doc/manual/core_language_reference.rst

@@ -1,7 +1,7 @@
 Core language reference
 =======================
 
-The most commonly used features from those modules can be imported with ``from artiq import *``.
+The most commonly used features from the ARTIQ language modules and from the core device modules are bundled together in ``artiq.experiment`` and can be imported with ``from artiq.experiment import *``.
 
 :mod:`artiq.language.core` module
 ---------------------------------

doc/manual/getting_started_core.rst

@@ -8,7 +8,7 @@ Connecting to the core device
 
 As a very first step, we will turn on a LED on the core device. Create a file ``led.py`` containing the following: ::
 
-    from artiq import *
+    from artiq.experiment import *
 
 
     class LED(EnvExperiment):
@@ -93,7 +93,7 @@ The point of running code on the core device is the ability to meet demanding re
 
 Create a new file ``rtio.py`` containing the following: ::
 
-    from artiq import *
+    from artiq.experiment import *
 
 
     class Tutorial(EnvExperiment):
@@ -114,7 +114,7 @@ Instead, inside the core device, output timing is generated by the gateware and
 
 Try reducing the period of the generated waveform until the CPU cannot keep up with the generation of switching events and the underflow exception is raised. Then try catching it: ::
 
-    from artiq.coredevice.exceptions import RTIOUnderflow
+    from artiq.experiment import *
 
 
     def print_underflow():

doc/manual/getting_started_mgmt.rst

@@ -16,7 +16,7 @@ Then create a ``~/artiq-master/repository`` sub-folder to contain experiments. T
 
 Create a very simple experiment in ``~/artiq-master/repository`` and save it as ``mgmt_tutorial.py``: ::
 
-    from artiq import *
+    from artiq.experiment import *
 
 
     class MgmtTutorial(EnvExperiment):

examples/master/repository/arguments_demo.py

@@ -1,6 +1,6 @@
 import logging
 
-from artiq import *
+from artiq.experiment import *
 
 
 class SubComponent1(HasEnvironment):

examples/master/repository/coredevice_examples/photon_histogram.py

@@ -1,4 +1,4 @@
-from artiq import *
+from artiq.experiment import *
 
 
 class PhotonHistogram(EnvExperiment):

examples/master/repository/coredevice_examples/simple/blink_forever.py

@@ -1,4 +1,4 @@
-from artiq import *
+from artiq.experiment import *
 
 
 class BlinkForever(EnvExperiment):

examples/master/repository/coredevice_examples/simple/dds_test.py

@@ -1,4 +1,4 @@
-from artiq import *
+from artiq.experiment import *
 
 
 class DDSTest(EnvExperiment):

examples/master/repository/coredevice_examples/simple/handover.py

@@ -1,4 +1,4 @@
-from artiq import *
+from artiq.experiment import *
 
 
 class Handover(EnvExperiment):

examples/master/repository/coredevice_examples/simple/mandelbrot.py

@@ -1,6 +1,6 @@
 import sys
 
-from artiq import *
+from artiq.experiment import *
 
 
 class Mandelbrot(EnvExperiment):

examples/master/repository/coredevice_examples/tdr.py

@@ -1,6 +1,6 @@
 # Copyright (C) 2014, 2015 Robert Jordens <jordens@gmail.com>
 
-from artiq import *
+from artiq.experiment import *
 
 
 class PulseNotReceivedError(Exception):

examples/master/repository/coredevice_examples/transport.py

@@ -2,7 +2,7 @@
 
 import numpy as np
 
-from artiq import *
+from artiq.experiment import *
 
 from artiq.wavesynth.coefficients import SplineSource
 

examples/master/repository/flopping_f_simulation.py

@@ -5,7 +5,7 @@ import random
 import numpy as np
 from scipy.optimize import curve_fit
 
-from artiq import *
+from artiq.experiment import *
 
 
 def model(x, F0):

examples/master/repository/run_forever.py

@@ -1,7 +1,7 @@
 from itertools import count
 from time import sleep
 
-from artiq import *
+from artiq.experiment import *
 
 
 class RunForever(EnvExperiment):

examples/master/repository/speed_benchmark.py

@@ -1,6 +1,6 @@
 import time
 
-from artiq import *
+from artiq.experiment import *
 
 
 class _PayloadNOP(EnvExperiment):

examples/master/repository/utilities/dds_setter.py

@@ -1,6 +1,6 @@
 from operator import itemgetter
 
-from artiq import *
+from artiq.experiment import *
 
 
 class DDSSetter(EnvExperiment):

examples/master/repository/utilities/terminate_all.py

@@ -1,4 +1,4 @@
-from artiq import *
+from artiq.experiment import *
 
 
 class TerminateAll(EnvExperiment):

examples/sim/al_spectroscopy.py

@@ -1,4 +1,4 @@
-from artiq import *
+from artiq.experiment import *
 
 
 class AluminumSpectroscopy(EnvExperiment):

examples/sim/simple_simulation.py

@@ -1,4 +1,4 @@
-from artiq import *
+from artiq.experiment import *
 
 
 class SimpleSimulation(EnvExperiment):