atomiq.helper
=============

.. py:module:: atomiq.helper


Functions
---------

.. autoapisummary::

   atomiq.helper.normalize_component_name
   atomiq.helper.get_module
   atomiq.helper.get_class_by_name
   atomiq.helper.rec_getattr
   atomiq.helper.random_ascii_string
   atomiq.helper.file_from_url
   atomiq.helper.component_dict
   atomiq.helper.component_data
   atomiq.helper.block_dict
   atomiq.helper.replace_member
   atomiq.helper.identity_float
   atomiq.helper.identity_int32
   atomiq.helper.identity_float_int32
   atomiq.helper.isnan
   atomiq.helper.less_than_uint32
   atomiq.helper.unsigned_bitshift32
   atomiq.helper.master_ipc_call
   atomiq.helper.dummy_decorator


Module Contents
---------------

.. py:function:: normalize_component_name(name)

.. py:function:: get_module(path, relative_path=None)

.. py:function:: get_class_by_name(name, relative_path=None)

   Resolve class by name

   :param name: (str) "%s.%s" % (module.name, class.name)
   :return: (class)


.. py:function:: rec_getattr(obj, attr)

   Get object's attribute. May use dot notation.

   >>> class C(object): pass
   >>> a = C()
   >>> a.b = C()
   >>> a.b.c = 4
   >>> rec_getattr(a, 'b.c')
   4


.. py:function:: random_ascii_string(length)

.. py:function:: file_from_url(url)

   Load content from a file specified by a URL.

   This can be every type of URL supported by pythons urllib
   (e.g. http://, file://, etc ). Giving the basic auth credentials in the URL in the form
   http://user:password@hostname:port/path is supported.

   :returns: file handle on the file


.. py:function:: component_dict(component)

   Extract the required information (id, type) from the entries of a component list defined
   in an AtomiqBlock/AtomiqExperiment

   We allow entries in a components list of AtomiqExperiment/AtomiqBlock to be either just strings
   specifying the id of the component or tuples of the form (id, type) to require a specific
   type of the component with the given id. The type can also be a superclass of the specified
   component.

   :param component: entry of the component list

   :returns: dictionary with keys "id" and and "type"
   :rtype: dict


.. py:function:: component_data(component_dict)

.. py:function:: block_dict(blockdef)

   Extract the required information (class, map) from the entries of a block list defined
   in an AtomiqBlock/AtomiqExperiment

   We allow entries in a blocks list of AtomiqExperiment/AtomiqBlock to be either just strings
   specifying the class of the AtomiqBlock to be imported or tuples of the form (class, ,map)
   to specify a mapping of the components in the experiment to the components in the block.

   :param blockdef: entry of the blocks list

   :returns: dictionary with keys "class", "map", and "alias"
   :rtype: dict


.. py:function:: replace_member(obj, target, replacement)

   Replace a member (target) of an object (obj) with a different member (replacement). This is useful to change
   member functions of components at construction of the object depending on the configuration.

   when running the legacy artiq compiler, every object has its own class and we can/have to modify the class.
   Otherwise, we just alter the object itself.


.. py:function:: identity_float(x)

.. py:function:: identity_int32(x)

.. py:function:: identity_float_int32(x)

.. py:function:: isnan(x)

   Check whether a float is NaN.

   We cannot use `math.isnan` or `numpy.isnan` in the core, so we use IEEE 754 and do it by hand.


.. py:function:: less_than_uint32(x, y)

   Helper function to compare two unsigned int32 bit register `x` and `y` values which are a int32 (x<y).
   This is a necessary workaround as the ARTIQ kernel does not support unsigned integers.


.. py:function:: unsigned_bitshift32(x, bits)

   Implemets a right bitshift operation on an signed `int32` (as supported by the artiq kernel) which encodes an
   unsigned `uint32` value.


.. py:function:: master_ipc_call(experiment, action)

   Return a method to call the artiq master through internal IPC communication

   :param experiment: The artiq/atomiq experiment object
   :param action: action in the master process to call with this function

   :returns: Method that calles the requested RPC endpoint in the master


.. py:function:: dummy_decorator(func)