389 lines
11 KiB
Python
389 lines
11 KiB
Python
|
"""
|
||
|
|
Module to efficiently partition SymPy objects.
|
||
|
|
|
||
|
|
This system is introduced because class of SymPy object does not always
|
||
|
|
represent the mathematical classification of the entity. For example,
|
||
|
|
``Integral(1, x)`` and ``Integral(Matrix([1,2]), x)`` are both instance
|
||
|
|
of ``Integral`` class. However the former is number and the latter is
|
||
|
|
matrix.
|
||
|
|
|
||
|
|
One way to resolve this is defining subclass for each mathematical type,
|
||
|
|
such as ``MatAdd`` for the addition between matrices. Basic algebraic
|
||
|
|
operation such as addition or multiplication take this approach, but
|
||
|
|
defining every class for every mathematical object is not scalable.
|
||
|
|
|
||
|
|
Therefore, we define the "kind" of the object and let the expression
|
||
|
|
infer the kind of itself from its arguments. Function and class can
|
||
|
|
filter the arguments by their kind, and behave differently according to
|
||
|
|
the type of itself.
|
||
|
|
|
||
|
|
This module defines basic kinds for core objects. Other kinds such as
|
||
|
|
``ArrayKind`` or ``MatrixKind`` can be found in corresponding modules.
|
||
|
|
|
||
|
|
.. notes::
|
||
|
|
This approach is experimental, and can be replaced or deleted in the future.
|
||
|
|
See https://github.com/sympy/sympy/pull/20549.
|
||
|
|
"""
|
||
|
|
|
||
|
|
from collections import defaultdict
|
||
|
|
|
||
|
|
from .cache import cacheit
|
||
|
|
from sympy.multipledispatch.dispatcher import (Dispatcher,
|
||
|
|
ambiguity_warn, ambiguity_register_error_ignore_dup,
|
||
|
|
str_signature, RaiseNotImplementedError)
|
||
|
|
|
||
|
|
|
||
|
|
class KindMeta(type):
|
||
|
|
"""
|
||
|
|
Metaclass for ``Kind``.
|
||
|
|
|
||
|
|
Assigns empty ``dict`` as class attribute ``_inst`` for every class,
|
||
|
|
in order to endow singleton-like behavior.
|
||
|
|
"""
|
||
|
|
def __new__(cls, clsname, bases, dct):
|
||
|
|
dct['_inst'] = {}
|
||
|
|
return super().__new__(cls, clsname, bases, dct)
|
||
|
|
|
||
|
|
|
||
|
|
class Kind(object, metaclass=KindMeta):
|
||
|
|
"""
|
||
|
|
Base class for kinds.
|
||
|
|
|
||
|
|
Kind of the object represents the mathematical classification that
|
||
|
|
the entity falls into. It is expected that functions and classes
|
||
|
|
recognize and filter the argument by its kind.
|
||
|
|
|
||
|
|
Kind of every object must be carefully selected so that it shows the
|
||
|
|
intention of design. Expressions may have different kind according
|
||
|
|
to the kind of its arguments. For example, arguments of ``Add``
|
||
|
|
must have common kind since addition is group operator, and the
|
||
|
|
resulting ``Add()`` has the same kind.
|
||
|
|
|
||
|
|
For the performance, each kind is as broad as possible and is not
|
||
|
|
based on set theory. For example, ``NumberKind`` includes not only
|
||
|
|
complex number but expression containing ``S.Infinity`` or ``S.NaN``
|
||
|
|
which are not strictly number.
|
||
|
|
|
||
|
|
Kind may have arguments as parameter. For example, ``MatrixKind()``
|
||
|
|
may be constructed with one element which represents the kind of its
|
||
|
|
elements.
|
||
|
|
|
||
|
|
``Kind`` behaves in singleton-like fashion. Same signature will
|
||
|
|
return the same object.
|
||
|
|
|
||
|
|
"""
|
||
|
|
def __new__(cls, *args):
|
||
|
|
if args in cls._inst:
|
||
|
|
inst = cls._inst[args]
|
||
|
|
else:
|
||
|
|
inst = super().__new__(cls)
|
||
|
|
cls._inst[args] = inst
|
||
|
|
return inst
|
||
|
|
|
||
|
|
|
||
|
|
class _UndefinedKind(Kind):
|
||
|
|
"""
|
||
|
|
Default kind for all SymPy object. If the kind is not defined for
|
||
|
|
the object, or if the object cannot infer the kind from its
|
||
|
|
arguments, this will be returned.
|
||
|
|
|
||
|
|
Examples
|
||
|
|
========
|
||
|
|
|
||
|
|
>>> from sympy import Expr
|
||
|
|
>>> Expr().kind
|
||
|
|
UndefinedKind
|
||
|
|
"""
|
||
|
|
def __new__(cls):
|
||
|
|
return super().__new__(cls)
|
||
|
|
|
||
|
|
def __repr__(self):
|
||
|
|
return "UndefinedKind"
|
||
|
|
|
||
|
|
UndefinedKind = _UndefinedKind()
|
||
|
|
|
||
|
|
|
||
|
|
class _NumberKind(Kind):
|
||
|
|
"""
|
||
|
|
Kind for all numeric object.
|
||
|
|
|
||
|
|
This kind represents every number, including complex numbers,
|
||
|
|
infinity and ``S.NaN``. Other objects such as quaternions do not
|
||
|
|
have this kind.
|
||
|
|
|
||
|
|
Most ``Expr`` are initially designed to represent the number, so
|
||
|
|
this will be the most common kind in SymPy core. For example
|
||
|
|
``Symbol()``, which represents a scalar, has this kind as long as it
|
||
|
|
is commutative.
|
||
|
|
|
||
|
|
Numbers form a field. Any operation between number-kind objects will
|
||
|
|
result this kind as well.
|
||
|
|
|
||
|
|
Examples
|
||
|
|
========
|
||
|
|
|
||
|
|
>>> from sympy import S, oo, Symbol
|
||
|
|
>>> S.One.kind
|
||
|
|
NumberKind
|
||
|
|
>>> (-oo).kind
|
||
|
|
NumberKind
|
||
|
|
>>> S.NaN.kind
|
||
|
|
NumberKind
|
||
|
|
|
||
|
|
Commutative symbol are treated as number.
|
||
|
|
|
||
|
|
>>> x = Symbol('x')
|
||
|
|
>>> x.kind
|
||
|
|
NumberKind
|
||
|
|
>>> Symbol('y', commutative=False).kind
|
||
|
|
UndefinedKind
|
||
|
|
|
||
|
|
Operation between numbers results number.
|
||
|
|
|
||
|
|
>>> (x+1).kind
|
||
|
|
NumberKind
|
||
|
|
|
||
|
|
See Also
|
||
|
|
========
|
||
|
|
|
||
|
|
sympy.core.expr.Expr.is_Number : check if the object is strictly
|
||
|
|
subclass of ``Number`` class.
|
||
|
|
|
||
|
|
sympy.core.expr.Expr.is_number : check if the object is number
|
||
|
|
without any free symbol.
|
||
|
|
|
||
|
|
"""
|
||
|
|
def __new__(cls):
|
||
|
|
return super().__new__(cls)
|
||
|
|
|
||
|
|
def __repr__(self):
|
||
|
|
return "NumberKind"
|
||
|
|
|
||
|
|
NumberKind = _NumberKind()
|
||
|
|
|
||
|
|
|
||
|
|
class _BooleanKind(Kind):
|
||
|
|
"""
|
||
|
|
Kind for boolean objects.
|
||
|
|
|
||
|
|
SymPy's ``S.true``, ``S.false``, and built-in ``True`` and ``False``
|
||
|
|
have this kind. Boolean number ``1`` and ``0`` are not relevant.
|
||
|
|
|
||
|
|
Examples
|
||
|
|
========
|
||
|
|
|
||
|
|
>>> from sympy import S, Q
|
||
|
|
>>> S.true.kind
|
||
|
|
BooleanKind
|
||
|
|
>>> Q.even(3).kind
|
||
|
|
BooleanKind
|
||
|
|
"""
|
||
|
|
def __new__(cls):
|
||
|
|
return super().__new__(cls)
|
||
|
|
|
||
|
|
def __repr__(self):
|
||
|
|
return "BooleanKind"
|
||
|
|
|
||
|
|
BooleanKind = _BooleanKind()
|
||
|
|
|
||
|
|
|
||
|
|
class KindDispatcher:
|
||
|
|
"""
|
||
|
|
Dispatcher to select a kind from multiple kinds by binary dispatching.
|
||
|
|
|
||
|
|
.. notes::
|
||
|
|
This approach is experimental, and can be replaced or deleted in
|
||
|
|
the future.
|
||
|
|
|
||
|
|
Explanation
|
||
|
|
===========
|
||
|
|
|
||
|
|
SymPy object's :obj:`sympy.core.kind.Kind()` vaguely represents the
|
||
|
|
algebraic structure where the object belongs to. Therefore, with
|
||
|
|
given operation, we can always find a dominating kind among the
|
||
|
|
different kinds. This class selects the kind by recursive binary
|
||
|
|
dispatching. If the result cannot be determined, ``UndefinedKind``
|
||
|
|
is returned.
|
||
|
|
|
||
|
|
Examples
|
||
|
|
========
|
||
|
|
|
||
|
|
Multiplication between numbers return number.
|
||
|
|
|
||
|
|
>>> from sympy import NumberKind, Mul
|
||
|
|
>>> Mul._kind_dispatcher(NumberKind, NumberKind)
|
||
|
|
NumberKind
|
||
|
|
|
||
|
|
Multiplication between number and unknown-kind object returns unknown kind.
|
||
|
|
|
||
|
|
>>> from sympy import UndefinedKind
|
||
|
|
>>> Mul._kind_dispatcher(NumberKind, UndefinedKind)
|
||
|
|
UndefinedKind
|
||
|
|
|
||
|
|
Any number and order of kinds is allowed.
|
||
|
|
|
||
|
|
>>> Mul._kind_dispatcher(UndefinedKind, NumberKind)
|
||
|
|
UndefinedKind
|
||
|
|
>>> Mul._kind_dispatcher(NumberKind, UndefinedKind, NumberKind)
|
||
|
|
UndefinedKind
|
||
|
|
|
||
|
|
Since matrix forms a vector space over scalar field, multiplication
|
||
|
|
between matrix with numeric element and number returns matrix with
|
||
|
|
numeric element.
|
||
|
|
|
||
|
|
>>> from sympy.matrices import MatrixKind
|
||
|
|
>>> Mul._kind_dispatcher(MatrixKind(NumberKind), NumberKind)
|
||
|
|
MatrixKind(NumberKind)
|
||
|
|
|
||
|
|
If a matrix with number element and another matrix with unknown-kind
|
||
|
|
element are multiplied, we know that the result is matrix but the
|
||
|
|
kind of its elements is unknown.
|
||
|
|
|
||
|
|
>>> Mul._kind_dispatcher(MatrixKind(NumberKind), MatrixKind(UndefinedKind))
|
||
|
|
MatrixKind(UndefinedKind)
|
||
|
|
|
||
|
|
Parameters
|
||
|
|
==========
|
||
|
|
|
||
|
|
name : str
|
||
|
|
|
||
|
|
commutative : bool, optional
|
||
|
|
If True, binary dispatch will be automatically registered in
|
||
|
|
reversed order as well.
|
||
|
|
|
||
|
|
doc : str, optional
|
||
|
|
|
||
|
|
"""
|
||
|
|
def __init__(self, name, commutative=False, doc=None):
|
||
|
|
self.name = name
|
||
|
|
self.doc = doc
|
||
|
|
self.commutative = commutative
|
||
|
|
self._dispatcher = Dispatcher(name)
|
||
|
|
|
||
|
|
def __repr__(self):
|
||
|
|
return "<dispatched %s>" % self.name
|
||
|
|
|
||
|
|
def register(self, *types, **kwargs):
|
||
|
|
"""
|
||
|
|
Register the binary dispatcher for two kind classes.
|
||
|
|
|
||
|
|
If *self.commutative* is ``True``, signature in reversed order is
|
||
|
|
automatically registered as well.
|
||
|
|
"""
|
||
|
|
on_ambiguity = kwargs.pop("on_ambiguity", None)
|
||
|
|
if not on_ambiguity:
|
||
|
|
if self.commutative:
|
||
|
|
on_ambiguity = ambiguity_register_error_ignore_dup
|
||
|
|
else:
|
||
|
|
on_ambiguity = ambiguity_warn
|
||
|
|
kwargs.update(on_ambiguity=on_ambiguity)
|
||
|
|
|
||
|
|
if not len(types) == 2:
|
||
|
|
raise RuntimeError(
|
||
|
|
"Only binary dispatch is supported, but got %s types: <%s>." % (
|
||
|
|
len(types), str_signature(types)
|
||
|
|
))
|
||
|
|
|
||
|
|
def _(func):
|
||
|
|
self._dispatcher.add(types, func, **kwargs)
|
||
|
|
if self.commutative:
|
||
|
|
self._dispatcher.add(tuple(reversed(types)), func, **kwargs)
|
||
|
|
return _
|
||
|
|
|
||
|
|
def __call__(self, *args, **kwargs):
|
||
|
|
if self.commutative:
|
||
|
|
kinds = frozenset(args)
|
||
|
|
else:
|
||
|
|
kinds = []
|
||
|
|
prev = None
|
||
|
|
for a in args:
|
||
|
|
if prev is not a:
|
||
|
|
kinds.append(a)
|
||
|
|
prev = a
|
||
|
|
return self.dispatch_kinds(kinds, **kwargs)
|
||
|
|
|
||
|
|
@cacheit
|
||
|
|
def dispatch_kinds(self, kinds, **kwargs):
|
||
|
|
# Quick exit for the case where all kinds are same
|
||
|
|
if len(kinds) == 1:
|
||
|
|
result, = kinds
|
||
|
|
if not isinstance(result, Kind):
|
||
|
|
raise RuntimeError("%s is not a kind." % result)
|
||
|
|
return result
|
||
|
|
|
||
|
|
for i,kind in enumerate(kinds):
|
||
|
|
if not isinstance(kind, Kind):
|
||
|
|
raise RuntimeError("%s is not a kind." % kind)
|
||
|
|
|
||
|
|
if i == 0:
|
||
|
|
result = kind
|
||
|
|
else:
|
||
|
|
prev_kind = result
|
||
|
|
|
||
|
|
t1, t2 = type(prev_kind), type(kind)
|
||
|
|
k1, k2 = prev_kind, kind
|
||
|
|
func = self._dispatcher.dispatch(t1, t2)
|
||
|
|
if func is None and self.commutative:
|
||
|
|
# try reversed order
|
||
|
|
func = self._dispatcher.dispatch(t2, t1)
|
||
|
|
k1, k2 = k2, k1
|
||
|
|
if func is None:
|
||
|
|
# unregistered kind relation
|
||
|
|
result = UndefinedKind
|
||
|
|
else:
|
||
|
|
result = func(k1, k2)
|
||
|
|
if not isinstance(result, Kind):
|
||
|
|
raise RuntimeError(
|
||
|
|
"Dispatcher for {!r} and {!r} must return a Kind, but got {!r}".format(
|
||
|
|
prev_kind, kind, result
|
||
|
|
))
|
||
|
|
|
||
|
|
return result
|
||
|
|
|
||
|
|
@property
|
||
|
|
def __doc__(self):
|
||
|
|
docs = [
|
||
|
|
"Kind dispatcher : %s" % self.name,
|
||
|
|
"Note that support for this is experimental. See the docs for :class:`KindDispatcher` for details"
|
||
|
|
]
|
||
|
|
|
||
|
|
if self.doc:
|
||
|
|
docs.append(self.doc)
|
||
|
|
|
||
|
|
s = "Registered kind classes\n"
|
||
|
|
s += '=' * len(s)
|
||
|
|
docs.append(s)
|
||
|
|
|
||
|
|
amb_sigs = []
|
||
|
|
|
||
|
|
typ_sigs = defaultdict(list)
|
||
|
|
for sigs in self._dispatcher.ordering[::-1]:
|
||
|
|
key = self._dispatcher.funcs[sigs]
|
||
|
|
typ_sigs[key].append(sigs)
|
||
|
|
|
||
|
|
for func, sigs in typ_sigs.items():
|
||
|
|
|
||
|
|
sigs_str = ', '.join('<%s>' % str_signature(sig) for sig in sigs)
|
||
|
|
|
||
|
|
if isinstance(func, RaiseNotImplementedError):
|
||
|
|
amb_sigs.append(sigs_str)
|
||
|
|
continue
|
||
|
|
|
||
|
|
s = 'Inputs: %s\n' % sigs_str
|
||
|
|
s += '-' * len(s) + '\n'
|
||
|
|
if func.__doc__:
|
||
|
|
s += func.__doc__.strip()
|
||
|
|
else:
|
||
|
|
s += func.__name__
|
||
|
|
docs.append(s)
|
||
|
|
|
||
|
|
if amb_sigs:
|
||
|
|
s = "Ambiguous kind classes\n"
|
||
|
|
s += '=' * len(s)
|
||
|
|
docs.append(s)
|
||
|
|
|
||
|
|
s = '\n'.join(amb_sigs)
|
||
|
|
docs.append(s)
|
||
|
|
|
||
|
|
return '\n\n'.join(docs)
|