quantum_info.operator mixin interface refactor

[chriseclectic]

Summary

Internal API changes to BaseOperator class to simplify making operator subclasses, and reduce copy paste of API docs.

Details and comments

Refactors the quantum_info BaseOperator and subclasses to use mixins for defining the operator inferface. This allows operator subclasses to only include the mixin for interfaces they support. For example Operator and QuantumChannel operators support linear operations (addition, subtraction), but Clifford and Pauli operators do not.

Current mixins are:

• GroupMixin: this defines the basic API to be compatible with QuantumCircuits. It includes compose, dot, tensor, expand
• AdjointMixin: defines conjugate, transpose, adjoint methods.
• MultiplyMixin: this is not part of the BaseOperator and can be used by special operators which support scalar multiplication. It defines __mul__ and __truediv__ for scalars.
• LinearMixin: this defines linear operators which support addition, subtraction, and scalar multiplication. It includes the MultiplyMixin, plus defines __add__ and __sub__ methods.
• ToleranceMixin: this defines the atol and rtol properties for the operator for use in numeric comparisons

BaseOperator only uses GroupMixin for its API. Other mixins can be included by subclasses which support their interface or require their functionality. A LinearOp abstract class was also added that includes LinearMixin, AdjointMixin and TolerancesMixin with BaseOperator.

This PR also refactors a lot of doc strings in the operator classes to avoid unnecessary duplication in derived classes. This is handled by the generate_apidocs function that must be called on a class after its definition (Due to however python handles abstractmethod doc strings I couldn't seem to get this function to work as a decorator when defining the class).

[molar-volume]

Maybe

def _evolve(self, state, qargs=None):
        return SuperOp(self)._evolve(state, qargs)

could be moved to QuantumChannel, since it is same for all subclasses (except SuperOp).

[chriseclectic]

Maybe

def _evolve(self, state, qargs=None):
        return SuperOp(self)._evolve(state, qargs)

could be moved to QuantumChannel, since it is same for all subclasses (except SuperOp).

That is True, however it has cyclic import issues which is why it isn't in the base class.

[kdk]

Looks good overall, few small comments.

[ikkoham]

Why do private and public methods coexist? (e.g. _compose, compose)
_compose is an abstract method, so it has to be defined by the user. But at the same time, if user also overrides compose, then __matmul__ will become the compose (not _compose). Is this the desired behavior?

[chriseclectic]

Why do private and public methods coexist? (e.g. _compose, compose)
_compose is an abstract method, so it has to be defined by the user. But at the same time, if user also overrides compose, then __matmul__ will become the compose (not _compose). Is this the desired behavior?

The idea was user never overrides compose only _compose. Honestly this was mostly to prevent having to have the bit of code:

        if qargs is None:
            qargs = getattr(other, 'qargs', None)

in every subclasses compose method. But maybe thats not a good enough reason.

[chriseclectic]

I updated to remove the _tensor and _compose methods and go back to the original way of have compose, expand, tensor all abstract methods. Thanks to review feedback I think the added complexity wasn't worth the small code reduction.