      ideal
      Copyright (c)  2005-2016 John Abbott, Anna M. Bigatti
      GNU Free Documentation License, Version 1.2
%!includeconf: ../aux-txt2tags/config.t2t
      TeXTitle{ideal}{John Abbott}



== Examples ==[examples]
%----------------------------------------------------------------------
- [ex-ideal1.C ../../examples/index.html#ex-ideal1.C]
- [ex-ideal2.C ../../examples/index.html#ex-ideal2.C]
- [ex-RingHom3.C ../../examples/index.html#ex-RingHom3.C]
- [ex-AlexanderDual.C ../../examples/index.html#ex-AlexanderDual.C]
- [ex-QuotientBasis.C ../../examples/index.html#ex-QuotientBasis.C]
-

== User documentation ==
%======================================================================

The class ``ideal`` is for representing values which are ideals of some
[[ring]].  There are several ways to create an ``ideal``:

NOTE: THIS SYNTAX WILL PROBABLY CHANGE
- ``ideal I(r)`` -- ``I`` is the principal ideal generated by ``r`` (a [[RingElem]])
                    in the ring ``owner(r)``
- ``ideal I(r1, r2)``         --  [[RingElem]]s in the same [[ring]]
- ``ideal I(r1, r2, r3)``     --  [[RingElem]]s in the same [[ring]]
- ``ideal I(r1, r2, r3, r4)`` --  [[RingElem]]s in the same [[ring]]
- ``ideal I(R, gens)`` -- ``I`` is the ideal of ``R`` generated by the [[RingElem]]s of the
                C++ ``vector<RingElem>`` ``gens``, (all in the ring ``R``)
- ``ideal I(gens)`` -- ``gens`` must be a non-empty ``vector<RingElem>`` all in the same [[ring]]; equivalent to ``I(owner(gens[0]), gens)``.  If ``gens`` is empty, throws ERROR.


If you want to make an ideal in ``R`` with no generators use this syntax
``ideal(R, vector<RingElem>() )``


=== Operations ===[operations]

The permitted operations on ``ideal``s are:
let ``I`` and ``J`` be two ideals of the same ring
- ``I+J`` --             the sum of two ideals
- ``I += J`` --          equivalent to ``I = I+J``
- ``intersection(I, J)`` --  intersection of two ideals
- ``colon(I, J)`` --      the quotient of two ideals

We may also enquire about certain properties of an ideal:
- ``IsZero(I)`` --        true iff the ideal is a zero ideal
- ``IsOne(I)`` --         true iff the ideal is the whole ring
- ``IsMaximal(I)`` --     true iff the ideal is maximal in its ring
                    (i.e. iff the quotient ring is a field)
- ``IsPrime(I)`` --       true iff the ideal is prime
                    (i.e. quotient ring has no zero-divisors)
- ``IsContained(I, J)`` -- true iff the ideal ``I`` is a subset of the ideal ``J``
- ``IsElem(r, I)`` --     true iff ``r`` is an element of the ideal ``I``
- ``I == J`` --           true iff the ideals are equal
               		  (their generating sets may be different)

- ``RingOf(I)`` --   the ring in which the ideal ``I`` resides
- ``NumGens(I)`` --  length of list of generators of ``I``
- ``gens(I)`` --     a C++ vector<> of [[RingElem]]s which generate ``I``
- ``TidyGens(I)`` -- **see also GBasis** (below); returns a C++ vector of
                     [[RingElem]]s which generate ``I``
                     (this generating set is in some way "reduced",
                      and will never contain a zero element)


==== Queries ====

It is also possible to give some information about an ideal:
```
 I->UserAssertsIsPrime()       to specify that ``I`` is known to be prime
 I->UserAssertsIsNotPrime()    to specify that ``I`` is known not to be prime
 I->UserAssertsIsMaximal()     to specify that ``I`` is known to be maximal
 I->UserAssertsIsNotMaximal()  to specify that ``I`` is known not to be maximal
```
Making an incorrect assertion using these functions may lead to a
program crash, or at least to poorer run-time performance.


=== Queries and views ===[queries]
%----------------------------------------------------------------------
Additional queries for an ideal ``I`` in a [[SparsePolyRing]] ``P``.

- ``IsZeroDim(I)`` -- true iff ``I`` is zero-dimensional (and not the whole ring!)
- ``IsHomog(I)`` -- true iff ``I`` is homogeneous
- ``AreGensMonomial(I)`` -- true iff given ``gens(I)`` are all monomial. NB ``0`` is NOT monomial
- ``AreGensSqFreeMonomial(I)`` -- true iff given ``gens(I)`` are all monomial and radical.  NB ``0`` is NOT monomial
- ``HasGBasis(I)``   -- true iff ``GBasis(I)`` has been computed and is stored
-

=== Functions for ideals in polynomial rings ===
%----------------------------------------------------------------------
Additional functions for an ideal ``I`` in a [[SparsePolyRing]] ``P``.

- ``GBasis(I)``   -- returns a Groebner basis for ``I`` using the term-ordering
                     of the polynomial ring in which ``I`` resides; the basis
                     is stored inside ``I``, so will not be recomputed in the
                     future);  equivalent to ``TidyGens``.
- ``ReducedGBasis(I)``   -- like ``GBasis`` but guarantees that the result is a reduced basis.
- ``GBasisTimeout(I, Tmax)``   -- like ``GBasis`` but will throw an ``InterruptedByTimeout`` object if computation takes longer than ``Tmax`` seconds.

- ``LT(I)``       -- leading term ideal (also known as //initial ideal//)
- ``LF(I)``       -- leading form ideal (forms of maximum degree)
- ``homog(h, I)`` -- homogenization with the indeterminate ``h``, a
                     [[RingElem]], indeterminate in ``RingOf(I)``
- ``IdealOfGBasis(I)``  -- returns a **new ideal**  generated by the GBasis of ``I``
- ``IdealOfMinGens(I)`` -- returns a **new ideal** equal to ``I`` but generated by a minimal set of gens (only for homogeneous ideals)
- ``PrimaryDecomposition(I)`` -- only for square free monomial ideals (for now)
- ``QuotientBasis(I)``  -- basis of the quotient as a ``K``-vector space
- ``QuotientBasisSorted(I)``  -- same as ``QuotientBasis(I)`` but elements are sorted into increasing order.
-

==== Monomial ideals ====

Additional functions for a monomial ideal ``I`` in a [[SparsePolyRing]]

- ``PrimaryDecompositionMonId(I)`` -- only for square free monomial ideals (for now)
- ``AlexanderDual(I)`` -- only for square free monomial ideals (for now)


==== Using Frobby library ====

- ``PrimaryDecompositionFrobby(I)``
- ``AlexanderDual(I)``, ``AlexanderDual(I, pp)``
- and more...


=== Writing new types of ideal ===
%----------------------------------------------------------------------

Anyone who writes a new type of ring class will have to consider writing
a new type of ideal class to go with that ring.  The ideal class must be
derived from the abstract class IdealBase (and to be instantiable must
offer implementations of all pure virtual functions).  Be especially
careful to update the data members IamPrime and IamMaximal in the
non-const member functions (add, intersection, and colon).

Some guidance may be obtained from looking at the FieldIdealImpl class which
implements ideals in a field (there are only two: ideal(0) and ideal(1)).
See the file [[FieldIdeal]].


== Maintainer documentation for the classes ideal, IdealBase ==
%======================================================================

The class ideal is little more than a reference counting smart pointer
class pointing to an object of type derived from IdealBase.  This
approach allows many different implementations of ideals to be
manipulated in a convenient and transparent manner using a common
abstract interface.

The abstract class IdealBase specifies the interface which every
concrete ideal class must offer.  It is more complicated than one might
expect partly because we want to allow the advanced user to tell the
ideal whether it has certain important properties (which might be
computationally expensive to determine automatically).


== Bugs, Shortcomings and other ideas ==
%======================================================================

The maintainer documentation is still quite incomplete.

Shouldn't ideals be created by a function called NewIdeal???

I am not at all sure about the wisdom of having implemented ``IamPrime``
and ``IamMaximal``.  It seems to be terribly easy to forget to update
these values when ideal values are modified (e.g. in IdealBase::add).
It has also led to rather more complication that I would have liked.
BUT I don't see how to allow the user to state that an ideal is
maximal/prime without incurring such complication.

Functions to examine the bool3 flags could be handy for //heuristic//
short-cuts when an ideal is already known to have a certain property.

Is it worth having a constructor for principal ideals generated by
a number rather than a RingElem?  e.g.  NewIdeal(R,5) or NewIdeal(R,BigInt(5)).

Several member functions have names not in accordance with the coding
conventions.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
== Main changes ==
%======================================================================

**2017**
- February (v0.99543): added examples ex-ideal1 and ex-ideal2


**2016**
- November (v0.99543):
 - added HasGBasis
 - renamed AreGensSquareFreeMonomial into AreGensSqFreeMonomial
-


