code: def read_forward_solution(
      fname, include=(), exclude=(), *, ordered=None, verbose=None
  ):
      """Read a forward solution a.k.a. lead field.
  
      Parameters
      ----------
      fname : path-like
          The file name, which should end with ``-fwd.fif``, ``-fwd.fif.gz``,
          ``_fwd.fif``, ``_fwd.fif.gz``, ``-fwd.h5``, or ``_fwd.h5``.
      include : list, optional
          List of names of channels to include. If empty all channels
          are included.
      exclude : list, optional
          List of names of channels to exclude. If empty include all channels.
      %(ordered)s
      %(verbose)s
  
      Returns
      -------
      fwd : instance of Forward
          The forward solution.
  
      See Also
      --------
      write_forward_solution, make_forward_solution
  
      Notes
      -----
      Forward solutions, which are derived from an original forward solution with
      free orientation, are always stored on disk as forward solution with free
      orientation in X/Y/Z RAS coordinates. To apply any transformation to the
      forward operator (surface orientation, fixed orientation) please apply
      :func:`convert_forward_solution` after reading the forward solution with
      :func:`read_forward_solution`.
  
      Forward solutions, which are derived from an original forward solution with
      fixed orientation, are stored on disk as forward solution with fixed
      surface-based orientations. Please note that the transformation to
      surface-based, fixed orientation cannot be reverted after loading the
      forward solution with :func:`read_forward_solution`.
      """
      check_fname(
          fname,
          "forward",
          (
              "-fwd.fif",
              "-fwd.fif.gz",
              "_fwd.fif",
              "_fwd.fif.gz",
              "-fwd.h5",
              "_fwd.h5",
          ),
      )
      fname = _check_fname(
          fname=fname, must_exist=True, overwrite="read"
      )
      #   Open the file, create directory
      logger.info("Reading forward solution from %s..." % fname)
      if fname.suffix == ".h5":
          return _read_forward_hdf5(fname)
      f, tree, _ = fiff_open(fname)
      with f as fid:
          #   Find all forward solutions
          fwds = dir_tree_find(tree, FIFF.FIFFB_MNE_FORWARD_SOLUTION)
          if len(fwds) == 0:
              raise ValueError("No forward solutions in %s" % fname)
  
          #   Parent MRI data
          parent_mri = dir_tree_find(
              tree, FIFF.FIFFB_MNE_PARENT_MRI_FILE
          )
          if len(parent_mri) == 0:
              raise ValueError(
                  "No parent MRI information in %s" % fname
              )
          parent_mri = parent_mri[0]
  
          src = _read_source_spaces_from_tree(
              fid, tree, patch_stats=False
          )
          for s in src:
              s["id"] = find_source_space_hemi(s)
  
          fwd = None
  
          #   Locate and read the forward solutions
          megnode = None
          eegnode = None
          for k in range(len(fwds)):
              tag = find_tag(
                  fid, fwds[k], FIFF.FIFF_MNE_INCLUDED_METHODS
              )
              if tag is None:
                  raise ValueError(
                      "Methods not listed for one of the forward "
                      "solutions"
                  )
  
              if tag.data == FIFF.FIFFV_MNE_MEG:
                  megnode = fwds[k]
              elif tag.data == FIFF.FIFFV_MNE_EEG:
                  eegnode = fwds[k]
  
          fwds = dict()
          megfwd = _read_one(fid, megnode)
          if megfwd is not None:
              fwds["meg"] = megfwd
              if is_fixed_orient(megfwd):
                  ori = "fixed"
              else:
                  ori = "free"
              logger.info(
                  "    Read MEG forward solution (%d sources, "
                  "%d channels, %s orientations)"
                  % (megfwd["nsource"], megfwd["nchan"], ori)
              )
          del megfwd
  
          eegfwd = _read_one(fid, eegnode)
          if eegfwd is not None:
              fwds["eeg"] = eegfwd
              if is_fixed_orient(eegfwd):
                  ori = "fixed"
              else:
                  ori = "free"
              logger.info(
                  "    Read EEG forward solution (%d sources, "
                  "%d channels, %s orientations)"
                  % (eegfwd["nsource"], eegfwd["nchan"], ori)
              )
          del eegfwd
  
          fwd = _merge_fwds(fwds)
          del fwds
  
          #   Get the MRI <-> head coordinate transformation
          tag = find_tag(fid, parent_mri, FIFF.FIFF_COORD_TRANS)
          if tag is None:
              raise ValueError(
                  "MRI/head coordinate transformation not found"
              )
          mri_head_t = tag.data
          if (
              mri_head_t["from"] != FIFF.FIFFV_COORD_MRI
              or mri_head_t["to"] != FIFF.FIFFV_COORD_HEAD
          ):
              mri_head_t = invert_transform(mri_head_t)
              if (
                  mri_head_t["from"] != FIFF.FIFFV_COORD_MRI
                  or mri_head_t["to"] != FIFF.FIFFV_COORD_HEAD
              ):
                  fid.close()
                  raise ValueError(
                      "MRI/head coordinate transformation not " "found"
                  )
          fwd["mri_head_t"] = mri_head_t
  
          #
          # get parent MEG info
          #
          fwd["info"] = _read_forward_meas_info(tree, fid)
  
          # MNE environment
          parent_env = dir_tree_find(tree, FIFF.FIFFB_MNE_ENV)
          if len(parent_env) > 0:
              parent_env = parent_env[0]
              tag = find_tag(
                  fid, parent_env, FIFF.FIFF_MNE_ENV_WORKING_DIR
              )
              if tag is not None:
                  with fwd["info"]._unlock():
                      fwd["info"]["working_dir"] = tag.data
              tag = find_tag(
                  fid, parent_env, FIFF.FIFF_MNE_ENV_COMMAND_LINE
              )
              if tag is not None:
                  with fwd["info"]._unlock():
                      fwd["info"]["command_line"] = tag.data
  
      #   Transform the source spaces to the correct coordinate frame
      #   if necessary
  
      # Make sure forward solution is in either the MRI or HEAD coordinate frame
      if fwd["coord_frame"] not in (
          FIFF.FIFFV_COORD_MRI,
          FIFF.FIFFV_COORD_HEAD,
      ):
          raise ValueError(
              "Only forward solutions computed in MRI or head "
              "coordinates are acceptable"
          )
  
      # Transform each source space to the HEAD or MRI coordinate frame,
      # depending on the coordinate frame of the forward solution
      # NOTE: the function transform_surface_to will also work on discrete and
      # volume sources
      nuse = 0
      for s in src:
          try:
              s = transform_surface_to(
                  s, fwd["coord_frame"], mri_head_t
              )
          except Exception as inst:
              raise ValueError(
                  "Could not transform source space (%s)" % inst
              )
  
          nuse += s["nuse"]
  
      # Make sure the number of sources match after transformation
      if nuse != fwd["nsource"]:
          raise ValueError(
              "Source spaces do not match the forward solution."
          )
  
      logger.info(
          "    Source spaces transformed to the forward solution "
          "coordinate frame"
      )
      fwd["src"] = src
  
      #   Handle the source locations and orientations
      fwd["source_rr"] = np.concatenate(
          [ss["rr"][ss["vertno"], :] for ss in src], axis=0
      )
  
      #   Store original source orientations
      fwd["_orig_source_ori"] = fwd["source_ori"]
  
      #   Deal with include and exclude
      pick_channels_forward(
          fwd, include=include, exclude=exclude, copy=False
      )
  
      if is_fixed_orient(fwd, orig=True):
          fwd["source_nn"] = np.concatenate(
              [_src["nn"][_src["vertno"], :] for _src in fwd["src"]],
              axis=0,
          )
          fwd["source_ori"] = FIFF.FIFFV_MNE_FIXED_ORI
          fwd["surf_ori"] = True
      else:
          fwd["source_nn"] = np.kron(
              np.ones((fwd["nsource"], 1)), np.eye(3)
          )
          fwd["source_ori"] = FIFF.FIFFV_MNE_FREE_ORI
          fwd["surf_ori"] = False
      return Forward(fwd)
  
imports: import os
  import re
  import shutil
  import tempfile
  from copy import deepcopy
  from os import PathLike
  from os import path
  from pathlib import Path
  from time import time
  import numpy
  from scipy import sparse
  from .._fiff.constants import FIFF
  from .._fiff.matrix import _read_named_matrix, _transpose_named_matrix, write_named_matrix
  from .._fiff.meas_info import Info, _make_ch_names_mapping, _read_bad_channels, _read_extended_ch_info, _write_bad_channels, _write_ch_infos, write_info
  from .._fiff.open import fiff_open
  from .._fiff.pick import pick_channels, pick_channels_forward, pick_info, pick_types
  from .._fiff.tag import find_tag, read_tag
  from .._fiff.tree import dir_tree_find
  from .._fiff.write import end_block, start_and_end_file, start_block, write_coord_trans, write_id, write_int, write_string
  from ..epochs import BaseEpochs
  from ..evoked import Evoked, EvokedArray
  from ..html_templates import _get_html_template
  from ..io import BaseRaw, RawArray
  from ..label import Label
  from ..source_estimate import _BaseSourceEstimate, _BaseVectorSourceEstimate
  from ..source_space._source_space import _get_src_nn, _read_source_spaces_from_tree, _set_source_space_vertices, _src_kind_dict, _write_source_spaces_to_fid, find_source_space_hemi
  from ..surface import _normal_orth
  from ..transforms import invert_transform, transform_surface_to, write_trans
  from ..utils import _check_compensation_grade, _check_fname, _check_option, _check_stc_units, _import_h5io_funcs, _on_missing, _stamp_to_dt, _validate_type, check_fname, fill_doc, get_subjects_dir, has_mne_c, logger, repr_html, run_subprocess, verbose, warn
label_desc: Use image node_id 7 for calling a global function with example usage: read_forward_solution(fname, include, exclude) and returns: Forward, _read_forward_hdf5