Type renaming in Oscar

We intend to rename a bunch of types in AbstractAlgebra, Nemo, Hecke, Oscar and possibly other of our packages. The motivation for this is to have consistent, predictable type name as much as possible.

Also, while initially it was a good idea to keep the flint-names (fmpz and friends) it is now more of a problem than a feature, the names internal to flint do not have to be the ones visible and used in Oscar.

The plan for Nemo.jl thus is to change mutable struct fmpz to mutable struct ZZElem and then add const fmpz = ZZElem inside Nemo.jl resp. right after the struct is , not much Nemo code needs to change. Then a few doctests or examples in the manual may need to be updated. No other changes should be needed in Nemo (e.g. no files need to be renamed)

The list here is far from complete, so please add more.

The Plan is to

• do it simultaneously across all repos stagger the change where possible, using the new @alias macro, starting with AA then proceeding to the others; only a few things (NCRing -> Ring -> CommRing) can't be done like that and require simultaneous breaking changes; these should be done separately and at once
• provide a script that can be applied to private projects
• then do staggered releases
• provide const old=new statements to protect the old code
• formulate the naming "rules" to help the next decision
• also to circulate this among Oscar-dev, Nemo-dev, … to reach as many as possible

Nemo types

Tommy: I think we want to get away from names like nmod/fmpz_mod, since we want to convey a bit more mathematical meaning in the type names (similar to the proposed change from fmpz to ZZElemz).

Image Not Showing Possible Reasons

• The image file may be corrupted
• The server hosting the image is unavailable
• The image path is incorrect
• The image format is not supported

Learn More →

Max Horn

These are some of flint types that must be renamed (FqNmodFiniteFieldElem is simply too long)

Tommy:

• @dan: Is the _Rep*-suffix a place holder or the really part of the name? If so, why? Answer: It doesn't matter, I just had to fill in the table. If we continue with the ZZ/zz idea, it could be fq => FqElem_PolyRep, fq_nmod => fqElem_PolyRep, fq_zech => fqElem_ZechRep.
  I love it! Let's do this.
• I like the zz/ZZ and fp/Fp idea, although it clashes a bit with the camel case convention for types. On the other hand, I agree that FqNmodFiniteFieldMPolynomial might be a bit too long.

  One issue with zz/ZZ is that we'd like to offer all-lowercase variants for all constructors so that users don't need to learn (really: guess) when to capitzalize things and when not. Alternative: immitate Julia and use Big prefix to distinguish. I'd not do this for fmpz/fmpq, but for the others; e.g. fmpz_mod -> BigZZModElem while nmod -> ZZModElem. Max Horn

AbstractAlgebra types

Abstract types

If the wise algebra wizards come to the conclusion that a univariate polynomial ring over a non-commutative ring make sense, we also need

Michael: Generally, I am in favor of long names. After all OSCAR is a large project, and we have numerous objects, types, functions etc (and tab completion is your friend). Yet, from the tables above I can see that there are reasons for combinations of short names like FqPolyRepMatrix.

I suggest at the very least to keep the generic names long, like Polynomial (with a coefficient domain to be specified by an argument), CommutativeRing (leaving Ring for the not necessarily commutative case). I would also go with AbelianGroup (but I can live with AbGroup if someone has a strong opinion; I would hate things like AbGrp though).

Let me also (softly) suggest to consider Integer for fmpz and Rational for fmpq [this probably will not work well because these names are already taken by Julia for it's abstract types]. Since these will be used much more often by most users than any other types, it would be good to give them good names. This is not meant as a contradiction to Tommy's table. We could keep, e.g., zzElem (or any other systematic name) as a synonym for Integer. The names ZZ and QQ are good, of course.<

Generic (concrete!) types

If you can't get a general idea of what the type represents from the name, then it probably needs renaming. If we follow this, we are going to be typing Comm everywhere. If we drop the notion of polynomials over non-commutative coefficient rings (and don't call them polynomials), then we can avoid this CommPoly, CommSeries, CommMPoly, CommMSeries business. I am in general applying the shortenings PolynomialRing => PolyRing and AlgebraElem => AlgElem.

EDIT: I have now crossed these out, for the variation where we don't type Comm everywhere.

Suggestion: use "graded" instead of "Decorated" and just don't mention that we can also handle filtrations?

Decision: for now we just stay with the name _dec

Quo -> Quotient??? and how does this related to quo(...) should it become quotient(..).

Localized <-> Loc ???

some more type names in Oscar:

some things that should be consistently named but are not:

• FPGroup vs. PcGroup (in GAP, it's FpGroup and PcGroup)
• FPModule vs. ModuleFP
  • apparently one is dense the other is sparse
  • so we'll call them FPModule and SparseFPModule
  • also compare with FPGroup and FPGroupElem
  • potential for confusion with "Fp" in FpField / FpFieldElem (note that this is not an abbrevation)
  • maybe better to use FinPres instead of FP ?

• We have elem_type, parent_type, abs_series_type, dense_poly_type, ..
  • we also have mpoly_type but basically no methods; add those?
  • should have have matrix_space_type or so? then we could rewrite matrix_space with a single method

Rules for naming types

The following should eventually appear in the OSCAR dev manual (and perhaps other places)

• types for rings/groups/ideals/modules/… end with Ring/Group/Ideal/Module/…
• types for element should have the same name as the type of the parent with Elem added
  • exception: MatrixSpace elements end with Matrix
• We abbreviate certain parts of type names, according to a fixed set of substitutions; further abbreviations should be carefully decided upon
• every abbreviation must be unique; e.g. Abs stands for Absolute, and so must not be used for e.g. Abstract
• list of approved abbreviations
  • quotient -> Quo
  • subquotient -> Subquo
  • localized -> Loc
  • decorated -> Dec
  • absolute -> Abs
    • abstract -> Abstract
  • relative -> Rel
  • polynomial -> Poly
  • multivariate polynomial -> MPoly
  • matrix -> Matrix or Mat ??
  • group -> Group
  • ring ->Ring
  • ideal -> Ideal
  • module -> Module
• If a type comes in sparse and dense variants, then call the dense type T and the sparse on SparseT

Other renaming

Besides types, also some function may be renamed (?)

Some suggestions:

• gens -> generators
• gen -> generator
• ngens -> number_of_generators or number_generators ???

(some of) the shorter names may remain for programmer's convenience?

• PolynomialRing -> polynomial_ring

• GradedPolynomialRing -> (graded_)polynomial_ring

  • but also ensure they take the same arguments?

• change is_normal to is_normalizing plus is_normal_subgroup

• FakeFmpqMat -> …

other tasks

• add docstrings to all these types
  • ideally with examples how to instantiate them
• raise awareness of certain type unions (IntegerUnion, RingElem, MatElem, …) and supertypes
  • e.g. by adding see XXX links to them in more places, mentioning them in docstrings for types, …

For Thursday:

• Thomas:
  • maybe change is_normal to is_normalizing plus is_normal_subgroup ? (do we have an open issue for that?)
• discuss again: we have Matrix instead of MatrixSpaceElem, so why not
  • PowerSeries vs. PowerSeriesRingElem
  • Poly(nomial) vs. PolyRingElem
• look at some more table entries:
  • Rat -> …?
  • FreeAssAlg…
• document @req https://github.com/thofma/Hecke.jl/issues/919

Actual renaming

These are renamings we decided upon.

• fmpz => ZZRingElem
• fmpz_mat => ZZMatrix
• fmpz_mpoly => ZZMPolyRingElem
• fmpz_poly => ZZPolyRingElem
• fmpq => QQFieldElem
• fmpq_mat => QQMatrix
• fmpq_mpoly => QQMPolyRingElem
• fmpq_poly => QQPolyRingElem
• fmpz_mod => ZZModRingElem
• fmpz_mod_mat => ZZModMatrix
• fmpz_mod_poly => ZZModPolyRingElem
• nmod => zzModRingElem
• nmod_mat => zzModMatrix
• nmod_mpoly => zzModMPolyRingElem
• nmod_poly => zzModPolyRingElem
• fq_default => FqFieldElem
• fq_default_mat => FqMatrix
• fq_default_mpoly => FqMPolyRingElem
• fq_default_poly => FqPolyRingElem
• gfp_fmpz_elem => FpFieldElem
• gfp_fmpz_mat => FpMatrix
• gfp_fmpz_mpoly => FpMPolyRingElem
• gfp_fmpz_poly => FpPolyRingElem
• gfp_elem => fpFieldElem
• gfp_mat => fpMatrix
• gfp_mpoly => fpMPolyRingElem
• gfp_poly => fpPolyRingElem
• fq => FqPolyRepFieldElem
• fq_mat => FqPolyRepMatrix
• fq_poly => FqPolyRepPolyRingElem
• fq_nmod => fqPolyRepFieldElem
• fq_nmod_mat => fqPolyRepMatrix
• fq_nmod_mpoly => fqPolyRepMPolyRingElem
• fq_nmod_poly => fqPolyRepPolyRingElem
• FlintIntegerRing => ZZRing
• FmpzMatSpace => ZZMatrixSpace
• FmpzMPolyRing => ZZMPolyRing
• FmpzPolyRing => ZZPolyRing
• FlintRationalField => QQField
• FmpqMatSpace => QQMatrixSpace
• FmpqMPolyRing => QQMPolyRing
• FmpqPolyRing => QQPolyRing
• FmpzModRing => ZZModRing
• FmpzModMatSpace => ZZModMatrixSpace
• FmpzModPolyRing => ZZModPolyRing
• NmodRing => zzModRing
• NmodMatSpace => zzModMatrixSpace
• NmodMPolyRing => zzModMPolyRing
• NmodPolyRing => zzModPolyRing
• FqDefaultFiniteField => FqField
• FqDefaultMatSpace => FqMatrixSpace
• FqDefaultMPolyRing => FqMPolyRing
• FqDefaultPolyRing => FqPolyRing
• GaloisFmpzField => FpField
• GaloisFmpzMatSpace => FpMatrixSpace
• GFPFmpzMPolyRing => FpMPolyRing
• GFPFmpzPolyRing => FpPolyRing
• GaloisField => fpField
• GFPMatSpace => fpMatrixSpace
• GFPMPolyRing => fpMPolyRing
• GFPPolyRing => fpPolyRing
• FqFiniteField => FqPolyRepField
• FqMatSpace => FqPolyRepMatrixSpace
• FqPolyRing => FqPolyRepPolyRing
• FqNmodFiniteField => fqPolyRepField
• FqNmodMatSpace => fqPolyRepMatrixSpace
• FqNmodMPolyRing => fqPolyRepMPolyRing
• FqNmodPolyRing => fqPolyRepPolyRing

fmpq_abs_series QQAbsPowerSeriesRingElem
fmpq_rel_series QQRelPowerSeriesRingElem
FmpqAbsSeriesRing QQAbsPowerSeriesRing
FmpqRelSeriesRing QQRelPowerSeriesRing

fmpz_abs_series ZZAbsPowerSeriesRingElem
fmpz_rel_series ZZRelPowerSeriesRingElem
FmpzAbsSeriesRing ZZAbsPowerSeriesRing
FmpzRelSeriesRing ZZRelPowerSeriesRing

fmpz_laurent_series ZZLaurentSeriesRingElem
FmpzLaurentSeriesRing ZZLaurentSeriesRing

fmpz_mod_abs_series ZZModAbsPowerSeriesRingElem
fmpz_mod_rel_series ZZModRelPowerSeriesRingElem
FmpzModAbsSeriesRing ZZModAbsPowerSeriesRing
FmpzModRelSeriesRing ZZModRelPowerSeriesRing

fq_default_abs_series FqAbsPowerSeriesRingElem
fq_default_rel_series FqRelPowerSeriesRingElem
FqDefaultAbsSeriesRing FqAbsPowerSeriesRing
FqDefaultRelSeriesRing FqRelPowerSeriesRing

fq_abs_series FqPolyRepAbsPowerSeriesRingElem
fq_rel_series FqPolyRepRelPowerSeriesRingElem
FqAbsSeriesRing FqPolyRepAbsPowerSeriesRing
FqRelSeriesRing FqPolyRepRelPowerSeriesRing

fq_nmod_abs_series fqPolyRepAbsPowerSeriesRingElem
fq_nmod_rel_series fqPolyRepRelPowerSeriesRingElem
FqNmodAbsSeriesRing fqPolyRepAbsPowerSeriesRing
FqNmodRelSeriesRing fqPolyRepRelPowerSeriesRing

gfp_abs_series fpAbsPowerSeriesRingElem
gfp_rel_series fpRelPowerSeriesRingElem
GFPAbsSeriesRing fpAbsPowerSeriesRing
GFPRelSeriesRing fpRelPowerSeriesRing

gfp_fmpz_abs_series FpAbsPowerSeriesRingElem
gfp_fmpz_rel_series FpRelPowerSeriesRingElem
GFPFmpzAbsSeriesRing FpAbsPowerSeriesRing
GFPFmpzRelSeriesRing FpRelPowerSeriesRing

nmod_abs_series zzModAbsPowerSeriesRingElem
nmod_rel_series zzModRelPowerSeriesRingElem
NmodAbsSeriesRing zzModAbsPowerSeriesRing
NmodRelSeriesRing zzModRelPowerSeriesRing

We also wanted to do this, but then discovered that RealField, RealElem, ComplexField, ComplexElem exist… these seem to be almost identical but have a "single parent" approach…

• arb => RealFieldElem
• arb_mat => RealMatrix
• arb_mpoly => RealMPolyRingElem
• arb_poly => RealPolyRingElem
• ArbField => RealField
• ArbMatSpace => RealMatrixSpace
• ArbMPolyRing => RealMPolyRing
• ArbPolyRing => RealPolyRing
• acb => ComplexFieldElem
• acb_mat => ComplexMatrix
• acb_mpoly => ComplexMPolyRingElem
• acb_poly => ComplexPolyRingElem
• AcbField => ComplexField
• AcbMatSpace => ComplexMatrixSpace
• AcbMPolyRing => ComplexMPolyRing
• AcbPolyRing => ComplexPolyRing

TODOs:

• also deal with the *Series types in Nemo
• deal with MatSpace/MatrixSpace/matrix_space
• also PolynomialRing, PowerSeriesRing, LaurentSeriesRing, LaurentSeriesField, FractionField, ResidueRing, ResidueField, NumberField constructors all to snake_case?