Diff for "days7/coercion"

• __init__

  • Any initialization for the object

  • Must call superclass's __init__ method with the following data:

    • a list of categories that this object type belongs to. Superclasses are automatically added, but the ORDER MATTERS for the order functions are detected in.

• __init__

  • Should do what initialization for the parent

  • Must call superclass's __init__ method with the following data:

    • your element class (required)

    • whether element_class.__init__ takes Parent as the first argument (default True)

    • a list of leaf categories (see Object __init__ description)

  • Note that __init__ may be called more than once. If you do things (like C memory allocation) that should only happen once, use can use __cinit__ for Cython. If you're writing a Python class and you care that you might get called twice, you'll have to manually track whether you've been called.

  • If you write a _populate_coercion_lists_ function (see below), you must call it in your __init__ method (and nowhere else).

• _has_coercion_from_ (cpdef) (called by has_coercion_from)

  • Takes a parent as an argument and returns True iff there is a canonical map from that parent to self.
  • You may override make_coercion_from instead of this function. If you override both they should be consistent.
  • The existence or non-existence of a coercion map is cached both in self and elsewhere. Because parents must be immutable, the return value of this function is constant over time.

  • If you call the default implementation Parent._has_coercion_from_(self, P) from your implemention (which you probably don't want to do), you MUST have overridden _coercion_from_ (because the two default implementations call each other).

• _coercion_from_ (cpdef) (called by coercion_from)

  • Overriding this function provides the ability to specify canonical morphisms to fit into the coercion model.
  • It takes one argument P, the parent you're coercing from.
  • It should return a morphism from P to self. This morphism should be canonical, though deterministic arbitrary choices may be allowed. One example of this is the "natural" embedding of symmetric groups. For a more detailed discussion of what makes a map canonical in this sense, see elsewhere.
  • You MUST return an object of type Morphism, or None.

  • The default functionality that you're replacing is: use has_ceorcion_from to see if a coercion exists and if so create a morphism that calls self._element_class's __init__ method.

  • If you override this method, you need to handle all possibilities for P.

  • If you call the default implementation Parent._coercion_from_(self, P) from your implemention, you MUST have overridden _has_coercion_from_ (because the two default implementations call each other).

  • ALL COERCION MORPHISMS SHOULD COMMUTE WITH EACH OTHER. We don't check this assumption currently, since in many cases morphisms cannot be compared for equality. But it is an important assumption for the model, and you should keep it in mind when deciding how canonical a morphism you want to use actually is.

• _conversion_from_ (cpdef) (called by conversion_from)

  • Overriding this function provides the ability to specify conversion morphisms. These are the morphisms that convert elements from one parent to another, possibly non-canonically.
  • It takes one argument P, the parent you're converting from.
  • It should return a morphism from P to self. This morphism need not be canonical.
  • You MUST return an object of type Morphism, or None.

  • The default functionality that you're replacing is: create and return a morphism that calls self._element_class's __init__ method.

  • If you override this method, you need to handle all possibilities for P (though you can handle a few and then call Parent._conversion_from_(self, P)).

• _get_action_ (cpdef) (called by get_action)

  • This gives you the ability to register actions with the coercion system (so that you can use g * x for your favorite action).

  • This function takes the following arguments:

    • other. This will usually be a parent (but could be a type, like in the case of integers acting on Python lists). Self will be acting on other.

    • op. This should be one of the binary operations *, ^, +, / in the Python operator module.

    • self_on_left (boolean, default True): whether self acts on other on the left. For example if self_on_left is true, and g is an element of self, x of other, * is the operation, then g * x would call this action but x * g would not.

  • One can also implement actions using the function _rmul_, _lmul_, _r_action and _l_action_ on elements. If an action is not returned by the _get_action_ method of either parent then the coercion model tries calling these four functions (see explanation in element), which by default raise NotImplementedErrors.

• _populate_coercion_lists_ (cpdef) (should only be called in YOUR __init__ method)

  • This function allows you to add coercion maps, conversion maps and actions to the coercion model.
  • This is a good place to put the defining coercions for your object. For example, a morphism from the base to self, or an embedding of a number field into the complex field.
  • This function takes the following arguments:

    • coerce_list (default []): A list of objects, each of which is either a Morphism with codomain self, or another parent (in which case a default morphism using element_class.__init__ is created). These are the coercions to self that are inserted into the cache. The should be canonical in the sense of coercion morphisms.

    • action_list (default []): A list of Actions, on and by self. These actions are registered with the coercion model and inserted into the cache.

    • convert_list (default []): A list of Morphisms with codomain self, used to convert from other parents to self. These morphisms are inserted into the cache.

    • embedding (default None): A single Morphism with self as the domain to be inserted into the coercion model. Only one embedding of each parent is allowed. Since your embedding is considered a coercion map, remember that it must commute with all other coercion maps in the model.

    • convert_method_name (default {{{None): A string that gives the name of a method on elements used to generate elements of this parent. For example, "_integer_" is the convert_method_name for the Integer class, "_real_double_" for the RealDoubleField class.

  • This function will overwrite anything in the cache that already exists with the same signature (eg a coercion map from A to B if you insert a coercion map from A to B). If two things with the same signature are given, the latter will be used.
  • If both a left and right action are defined (ie another object registers an action on self on the other side as self's action on that other object), the action of the object on the left takes precedence.

  • The advantage is that it's one place to insert common morphisms and seeds the discovery process. For example, if you specify a coercion map from the RationalField to self, then it will automatically create a coercion map from the integers to self.

• __call__

  • This is the function called when you type R(a) where R is the parent you're implementing. There is a default implementation in Parent.pyx that you should be wary of overriding because it uses the coercion model to try doing sensible things first (check if a is an Element, see if there's a coercion from the parent of a to self, see if there's a coercion from self to the parent of a with a section, etc).

  • You may want to override call if you have multiple primary arguments that you use to create an element (eg a complex field takes a real part and an imaginary part). Optional arguments are not a problem: the default creates a parameterized morphism. This will work even for multiple primary arguments, but might be less efficient or less aesthetically clean.

• __iter__

  • You may want to have the capacity to iterate over the elements of self. Writing this function will allow code such as for a in R:

Arithmetic (raise NotImplementedError)

• _add_ (cpdef)
• _mul_ (cpdef)
• _neg_ (cpdef)
• _invert_ (cpdef)

• _sub_ (cpdef)
• _div_ (cpdef)
• _powlong_
• _pow_

• _polynomial_
• _rmul_
• _lmul_
• _r_action_
• _l_action_