Query the Forest 2.0 server for its knowledge of lattices.  Optionally filters by underlying
    device name and lattice qubit count.

    :return: A dictionary keyed on lattice names and valued in dictionaries of the form
             {
               "device_name": device_name,
               "qubits": num_qubits
             }

def list_lattices(device_name: str = None, num_qubits: int = None,
                  connection: ForestConnection = None):
    """
    Query the Forest 2.0 server for its knowledge of lattices.  Optionally filters by underlying
    device name and lattice qubit count.

    :return: A dictionary keyed on lattice names and valued in dictionaries of the form
             {
               "device_name": device_name,
               "qubits": num_qubits
             }
    """
    if connection is None:
        connection = ForestConnection()
    session = connection.session
    url = connection.forest_cloud_endpoint + "/lattices"
    try:
        response = get_json(session, url,
                            params={"device_name": device_name,
                                    "num_qubits": num_qubits})

        return response["lattices"]
    except Exception as e:
        raise ValueError("""
        list_lattices encountered an error when querying the Forest 2.0 endpoint.

        Some common causes for this error include:

        * You don't have valid user authentication information.  Very likely this is because you
          haven't yet been invited to try QCS.  We plan on making our device information publicly
          accessible soon, but in the meanwhile, you'll have to use default QVM configurations and
          to use `list_quantum_computers` with `qpus = False`.

        * You do have user authentication information, but it is missing or modified.  You can find
          this either in the environment variables FOREST_API_KEY and FOREST_USER_ID or in the
          config file (stored by default at ~/.qcs_config, but with location settable through the
          environment variable QCS_CONFIG), which contains the subsection

          [Rigetti Forest]
          user_id = your_user_id
          key = your_api_key

        * You're missing an address for the Forest 2.0 server endpoint, or the address is invalid.
          This too can be set through the environment variable FOREST_URL or by changing the
          following lines in the QCS config file:

          [Rigetti Forest]
          url = https://forest-server.qcs.rigetti.com

        For the record, here's the original exception: {}
        """.format(repr(e)))