Coverage for python/src/dolfinx_mpc/_kind.py: 95%

1# Copyright (C) 2026 Jørgen S. Dokken 

2# 

3# This file is part of DOLFINX_MPC 

4# 

5# SPDX-License-Identifier: MIT 

6"""Interpretation of the ``kind`` argument of the assemblers, as in :mod:`dolfinx.fem.petsc`.""" 

7 

8from __future__ import annotations 

9 

10import warnings 

11from collections.abc import Sequence 

12from typing import Optional, Union 

13 

14# A PETSc matrix type, "nest", "mpi" or a nested sequence of matrix types for a nest matrix 

15Kind = Union[str, Sequence[Sequence[Optional[str]]], None] 

16 

17 

18def blocked_layout(kind: Kind) -> tuple[str, Union[str, Sequence[Sequence[Optional[str]]], None]]: 

19 """Layout of a system of several blocks selected by ``kind``. 

20 

21 Args: 

22 kind: ``"nest"`` or a nested sequence of matrix types selects a nest matrix, the types being 

23 those of its blocks. ``None``, ``"mpi"`` or a PETSc matrix type selects a single 

24 monolithic matrix. 

25 

26 Returns: 

27 ``("nest", types)``, with `types` ``None`` for the default type of every block, or 

28 ``("block", type)``, with `type` ``None`` for the default type. 

29 """ 

30 if isinstance(kind, str): 

31 if kind == "nest": 

32 return "nest", None 

33 return "block", None if kind == "mpi" else kind 

34 if kind is None: 

35 return "block", None 

36 return "nest", kind 

37 

38 

39def single_type(kind: Kind) -> Optional[str]: 

40 """PETSc matrix type of a single, non-blocked matrix selected by ``kind``, `None` for the default.""" 

41 if kind is None or kind == "mpi": 

42 return None 

43 if not isinstance(kind, str) or kind == "nest": 

44 raise ValueError(f"A single form needs a PETSc matrix type as kind, got {kind!r}") 

45 return kind 

46 

47 

48def deprecated(old: str, new: str) -> None: 

49 """Warn that the function `old` is deprecated in favour of `new`, attributed to the caller of `old`.""" 

50 warnings.warn(f"{old} is deprecated, use {new}", DeprecationWarning, stacklevel=3)