def auto_select_ipus(opts, num_ipus):
  """Configure the IPUs to be used by the session.

  The configuration describes a system consisting of multiple Tensorflow
  devices, each with control of one of more IPUs. The devices will be labeled
  ``/device:IPU:0``, ``/device:IPU:1`` and so on.

  Each device can control a specific number of IPUs, given by the ``num_ipus``
  parameter. The system will automatically select IPU configurations from the
  available IPUs, where they match the desired number of IPUs.

  Examples:


  .. code-block:: python

    # Create a single device, with one IPU
    opts = create_ipu_config()
    opts = auto_select_ipus(opts, num_ipus=1)
    ipu.utils.configure_ipu_system(opts)
    with tf.Session() as s:
      ...

  .. code-block:: python

    # Create two devices, with 2 IPUs per device.
    opts = create_ipu_config()
    opts = auto_select_ipus(opts, num_ipus=[2,2])
    ipu.utils.configure_ipu_system(opts)
    with tf.Session() as s:
      ...

  .. code-block:: python

    # Create two devices, with 1 IPU in the first device and 2 IPUs
    # in the second device.
    opts = create_ipu_config()
    opts = auto_select_ipus(opts, num_ipus=[1,2])
    ipu.utils.configure_ipu_system(opts)
    with tf.Session() as s:
      ...

  Args:
    opts: An IpuOptions session control protobuf.
    num_ipus: List of IPUs per Tensorflow device

  Returns:
    The IpuOptions configuration protobuf, configured for auto-selecting a set
    of IPU devices.
  """
  if opts.device_config:
    raise Exception("IPU devices have already been configured.")

  if not isinstance(num_ipus, (int, list, tuple)):
    raise Exception("`num_ipus` must be an integer, list or tuple.")

  if isinstance(num_ipus, int):
    dev = opts.device_config.add()
    dev.auto_count = num_ipus
  else:
    for n in num_ipus:
      dev = opts.device_config.add()
      dev.auto_count = n

  return opts