docs: def run(case, routine=None, profile=False, dump_raw=False, pid=-1, show_data=None, exit=False,
          **kwargs):
      """
      Entry function to run a single case study. This function executes the
      following workflow:
  
       * Turn on cProfile if requested
       * Populate a ``PowerSystem`` object
       * Parse the input files using filters
       * Dump the case file is requested
       * Set up the system
       * Run the specified routine(s)
  
      Parameters
      ----------
      case : str
          Path to the case file
  
      profile : bool, optional
          Enable cProfile if ``True``.
  
      dump_raw : ``False`` or str, optional
          Path to the file to dump the system parameters in the dm format
  
      routine : Iterable, optional
          A list of routines to run in sequence (``('pflow')`` as default)
  
      pid : idx, optional
          Process idx of the current run
  
      kwargs : dict, optional
          Other keyword arguments
  
      Returns
      -------
      PowerSystem
          Andes PowerSystem object
  
      """
      t0, _ = elapsed()
  
      # enable profiler if requested
      pr = cProfile.Profile()
      if profile is True:
          pr.enable()
  
      system = PowerSystem(case, **kwargs)
  
      if not filters.guess(system):
          return
  
      if not filters.parse(system):
          return
  
      # dump system as raw file if requested
      if dump_raw:
          filters.dump_raw(system)
  
      system.setup()
  
      # show data
      if show_data is not None:
          if len(show_data) == 0:
              show_data = sorted(system.devman.devices)
  
          for mdl in show_data:
              logger.info('Model <{}> data in system base'.format(mdl))
              logger.info(system.__dict__[mdl].data_to_df(sysbase=True).to_string())
          logger.info('')
  
      if routine is None or exit is True:
          pass
      else:
          # run power flow first
          if 'pflow' in routine:
              routine.remove('pflow')
  
          system.pflow.run()
          system.tds.init()
          system.report.write(content='powerflow')
  
          # run the rest of the routines
          for r in routine:
              system.__dict__[r.lower()].run()
  
      # Disable profiler and output results
      if profile:
          pr.disable()
  
          if system.files.no_output:
              s = io.StringIO()
              nlines = 40
              ps = pstats.Stats(pr, stream=sys.stdout).sort_stats('cumtime')
              ps.print_stats(nlines)
              logger.info(s.getvalue())
              s.close()
          else:
              s = open(system.files.prof, 'w')
              nlines = 999
              ps = pstats.Stats(pr, stream=s).sort_stats('cumtime')
              ps.print_stats(nlines)
              s.close()
              logger.info('cProfile results for job{:s} written.'.format(
                  ' ' + str(pid) if pid >= 0 else ''))
  
      if pid >= 0:
          _, s = elapsed(t0)
          msg_finish = 'Process {:d} finished in {:s}.'.format(pid, s)
          logger.info(msg_finish)
          print(msg_finish)
  
      return system