# dolfinx.common

General tools for timing and configuration.

Functions

`list_timings`(comm[, reduction]) | Print out a summary of all Timer measurements.
`timed`(task) | Decorator for timing functions.
`timing`(task) | Return the logged elapsed time.

Classes

`IndexMap`(, order=, writable=False], ...) |
`Reduction`(*values) |
`Timer`([name]) | A timer for timing section of code.

class dolfinx.common.IndexMap(self, comm: MPICommWrapper, local_size: int)
class dolfinx.common.IndexMap(self, comm: MPICommWrapper, local_size: int, ghosts: ndarray[dtype=int64, shape=(*), order='C', writable=False], ghost_owners: ndarray[dtype=int32, shape=(*), order='C', writable=False], tag: int)
class dolfinx.common.IndexMap(self, comm: MPICommWrapper, local_size: int, dest_src: collections.abc.Sequence[ndarray[dtype=int32, shape=(*), order='C', writable=False]], ghosts: ndarray[dtype=int64, shape=(*), order='C', writable=False], ghost_owners: ndarray[dtype=int32, shape=(*), order='C', writable=False])

  Bases: `object`

  property comm

    (self) -> MPICommWrapper

  property ghosts

    Return list of ghost indices

  global_to_local
  index_to_dest_ranks
  property local_range

    Range of indices owned by this map

  local_to_global
  property num_ghosts

    (self) -> int

  property owners

    (self) -> numpy.ndarray[dtype=int32, shape=(*), writable=False]

  property size_global

    (self) -> int

  property size_local

    (self) -> int

class dolfinx.common.Reduction(*values)

  Bases: `Enum`

  average = 0
  max = 1
  min = 2

class dolfinx.common.Timer(name: str | None = None)

  Bases: `object`

  A timer for timing section of code.

  The recommended usage is with a context manager.

  Example

  With a context manager, the timer is started when entering and stopped at exit. With a named `Timer`:

      with Timer("Some costly operation"):
          costly_call_1()
          costly_call_2()

      delta = timing("Some costly operation")
      print(delta)

  or with an un-named `Timer`:

      with Timer() as t:
          costly_call_1()
          costly_call_2()
          print(f"Elapsed time: {t.elapsed()}")

  Example

  It is possible to start and stop a timer explicitly:

      t = Timer("Some costly operation")
      costly_call()
      delta = t.stop()

  and retrieve timing data using:

      delta = t.elapsed()

  To flush the timing data for a named `Timer` to the logger, the timer should be stopped and flushed:

      t.stop()
      t.flush()

  Timings are stored globally (if task name is given) and once flushed (if used without a context manager) may be printed using functions `timing()` and `list_timings()`, e.g.:

      list_timings(comm)

  Create timer.

  Parameters:

    name – Identifier to use when storing elapsed time in logger.

  elapsed() → timedelta

    Return elapsed time.

    Returns:

      Elapsed time.

  flush() → None

    Flush timer duration to the logger.

    Note

    Timer must have been stopped before flushing.

    Timer can be flushed only once. Subsequent calls will have no effect.

  resume() → None

    Resume timer.

  start() → None

    Reset elapsed time and (re-)start timer.

  stop() → timedelta

    Stop timer and return elapsed time.

    Returns:

      Elapsed time.

dolfinx.common.list_timings(comm, reduction=Reduction.max)

  Print out a summary of all Timer measurements.

  When used in parallel, a reduction is applied across all processes. By default, the maximum time is shown.

dolfinx.common.timed(task: str)

  Decorator for timing functions.

dolfinx.common.timing(task: str) → tuple[int, timedelta]

  Return the logged elapsed time.

  Timing data is for the calling process.

  Parameters:

    task – The task name using when logging the time.

  Returns:

    (number of times logged, total wall time)