# 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
- <s>do it simultaneously across all repos</s> 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`).
> :+1: [name=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`. [name=Max Horn]

original name | element type | parent type | notes
------------------|--------------------|--------------------|----------------------
Int | zzRingElem | zzRing | not a real suggestion
-|-|-|-
fmpz | ZZRingElem | ZZRing | Z
fmpz_mat | ZZMatrix | ZZMatrixSpace | matrices over Z
fmpz_mpoly | ZZMPolyRingElem | ZZMPolyRing | Z[x,...]
fmpz_poly | ZZPolyRingElem | ZZPolyRing | Z[x]
-|-|-|-
fmpq | QQFieldElem | QQField | Q
fmpq_mat | QQMatrix | QQMatrixSpace |
fmpq_mpoly | QQMPolyRingElem | QQMPolyRing |
fmpq_poly | QQPolyRingElem | QQPolyRing |
-|-|-|-
fmpz_mod | ZZModRingElem | ZZModRing | Z/nZ for any n
fmpz_mod_mat | ZZModMatrix | ZZModMatrixSpace |
fmpz_mod_mpoly | ZZModMPolyRingElem | ZZModMPolyRing |
fmpz_mod_poly | ZZModPolyRingElem | ZZModPolyRing |
-|-|-|-
nmod | zzModRingElem | zzModRing | Z/nZ for n < 2^64
nmod_mat | zzModMatrix | zzModMatrixSpace |
nmod_mpoly | zzModMPolyRingElem | zzModMPolyRing |
nmod_poly | zzModPolyRingElem | zzModPolyRing |
-|-|-|-
fq_default | FqFieldElem | FqField | any finite field, a C-union chosing the best rep. below; once we have this and drop the others, then we can rename this to `FinField`
fq_default_mat | FqMatrix | FqMatrixSpace |
fq_default_mpoly | FqMPolyRingElem | FqMPolyRing | does not exist
fq_default_poly | FqPolyRingElem | FqPolyRing |
-|-|-|-
gfp_fmpz_mod | FpFieldElem | FpField | Z/pZ for any prime p
gfp_fmpz_mod_mat | FpMatrix | FpMatrixSpace |
gfp_fmpz_mod_mpoly | FpMPolyRingElem | FpMPolyRing |
gfp_fmpz_mod_poly | FpPolyRingElem | FpPolyRing |
-|-|-|-
gfp_elem | fpFieldElem | fpField | Z/pZ for prime p < 2^64
gfp_elem_mat | fpMatrix | fpMatrixSpace |
gfp_elem_mpoly | fpMPolyRingElem | fpMPolyRing |
gfp_elem_poly | fpPolyRingElem | fpPolyRing |
-|-|-|-
fq | FqPolyRepFieldElem | FqPolyRepField | any finite field
fq_mat | FqPolyRepMatrix | FqPolyRepMatrixSpace |
fq_mpoly | FqPolyRepMPolyRingElem | FqPolyRepMPolyRing | does not exist
fq_poly | FqPolyRepPolyRingElem | FqPolyRepPolyRing |
-|-|-|-
fq_nmod | fqPolyRepFieldElem | fqPolyRepField | finite field with char < word size
fq_nmod_mat | fqPolyRepMatrix | fqPolyRepMatrixSpace |
fq_nmod_mpoly | fqPolyRepMPolyRingElem | fqPolyRepMPolyRing |
fq_nmod_poly | fqPolyRepPolyRingElem | fqPolyRepRing |
-|-|-|-
fq_zech | fqZechRepFieldElem | fqZechRepField | Zech log representation
fq_zech_mat | fqZechRepMatrix | fqZechRepMatrixSpace |
fq_zech_mpoly | fqZechRepMPolyRingElem | fqZechRepMPolyRing |
fq_zech_poly | fqZechRepPolyRingElem | fqZechRepPolyRing |
-|-|-|-
nf_elem | ?? | ?? | Tommy: this is *your* type, help yourself
-|-|-|-
arb | RealFieldElem | ArbField => RealField | These are Fredrik's types
arb_mat | ?? | ?? |
arb_poly | ?? | ?? |
-|-|-|-
acb | ComplexFieldElem | AcbField => ComplexField |
acb_mat | ?? | ?? |
acb_poly | ?? | ?? |

# 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

| Old | New | Comment |
| -------- | -------- | --------
| `Poly` | `CommPoly` | So that `CommPoly <: CommRingElem`, Is is `CommPoly` or `CommPolynomial`? How do we decide when the suffix `Elem` is needed?
| `Poly` | `Poly` | Will satisfy `Poly <: RingElem`
| `MPoly` | `CommMPoly` | Will satisfy `CommMPoly <: CommRingElem`

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.

| old element / parent | new element / parent | notes
|-|-|-|
| Poly{T} / PolyRing{T} | ~~Comm~~Polynomial{T} / ~~Comm~~PolyRing{T} | _unfortunate new name_
| NCPoly{T} / NCPolyRing{T}| ~~Polynomial{T}~~ (??) / ~~PolyRing{T}~~ (??) | ~~new name is also unfortunate, leaves a bad taste~~ what are these things called?
| MPoly{T} / MPolyRing{T} | ~~Comm~~MPolynomial{T} / ~~Comm~~MPolyRing{T} | MPolyCoeffs, MPolyExponentVectors, MPolyTerms, MPolyMonomials, MPolyBuildCtx
| UnivPoly{T,U} / UnivPolyRing{T,U} | Universal~~Comm~~Polynomial{T} / Universal~~Comm~~PolyRing{T} | `UnivPoly` definitely must be renamed
| SparsePoly{T} / SparsePolyRing{T} | ? |
| LaurentPolyWrap{T, PE, LR} / LaurentPolyWrapRing{T, PR} | ? drop the `Wrap` |
| Res{T} / ResRing{T} | ResidueRingElem{T} / ResidueRing{T} | must be commutative to take the residues?
| ResF{T} / ResField{T} | ResidueFieldElem{T} / ResidueField{T} |
| RelSeries{T} / RelSeriesRing{T} | ~~Comm~~RelativePowerSeries{T} / ~~Comm~~RelativePowerSeriesRing{T} |
| AbsSeries{T} / AbsSeriesRing{T} | ~~Comm~~AbsolutePowerSeries{T} / ~~Comm~~AbsolutePowerSeriesRing{T} |
| LaurentSeriesRingElem{T} / LaurentSeriesRing{T} | ? |
| LaurentSeriesFieldElem{T} / LaurentSeriesField{T} | ? |
| PuiseuxSeriesRingElem{T} / PuiseuxSeriesRing{T} | ? |
| PuiseuxSeriesFieldElem{T} / PuiseuxSeriesField{T} | ? |
| AbsMSeries{T} / AbsMSeriesRing{T} | ~~Comm~~AbsoluteMPowerSeries{T} / ~~Comm~~AbsoluteMPowerSeriesRing{T} |
| FreeAssAlgElem{T} / FreeAssAlgebra{T} | FreeAssociativeAlgElem{T} / FreeAssociativeAlgebra{T} | Q: "Alg" or "Algebra" -- or "Ring" ?
| Frac{T} / FracField{T} | Fraction{T}/FractionField{T} | must be commutative?
| Rat{T} / RationalFunctionField{T} | RationalFunctionFieldElem{T} |
| FunctionFieldElem{T} / FunctionField{T} | ? | a finite extension of a rational function field
| MatSpaceElem{T} / MatSpace{T} | MatrixSpaceElem{T} / MatrixSpace{T} | I think `Matrix` is already taken by Julia. There is also `MatrixSpaceView`. (No there isn't?)
| MatAlgElem{T} / MatAlgebra{T} | MatrixAlgElem{T} / MatrixAlgebra{T} |
| FreeModuleElem{T} / FreeModule{T} | ? |
| SubmoduleElem{T} / Submodule{T} | ? |
| QuotientModuleElem{T} / QuotientModule{T} | ? |
| SNFModuleElem{T} / SNFModule{T} | ? |
| DirectSumModuleElem{T} / DirectSumModule{T} | ? |

| old element / parent | new element / parent | notes
|-|-|-|
| MPolyElem / MPolyRing | MPolyRingElem / MPolyRing |
| MPolyElem_dec / MPolyRing_dec | MPolyDecRingElem / MPolyDecRing |
| MPolyLocalizedRingElem / MPolyLocalizedRing | MPolyLocRingElem / MPolyLocRing |
| MPolyQuoElem / MPolyQuo | MPolyQuoRingElem / MPolyQuoRing |
| MPolyQuoLocalizedRingElem / MPolyQuoLocalizedRing | MPolyQuoLocRingElem / MPolyQuoLocRing |
|
|
| SubQuoElem / SubQuo | SubquoModuleElem / SubquoModule |
| SubQuoElem_dec / SubQuo_dec| SubquoDecModuleElem / SubquoDecModule | bonus: SubQuoHom_dec
| FreeModElem / FreeMod | ? leave it for now | sparse ... versus FreeModule in AA which is dense
| ? / SubModuleOfFreeModule | ? leave it for now | there is no elem type?

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 ???

| old |
|-|
|CompositeMap{D, C} |
|FunctionalMap{D, C} |
|IdentityMap{D} |
|FunctionalCompositeMap{D, C} |
|MapWithSection{D, C} |
|MapWithRetraction{D, C} |
|MapCache{D, C, S, T, De, Ce} |

### 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` ?

| old |
|-|
|MatAlgElem |
|MatAlgebra |
|MatSpace | MatrixSpace
|MatSpaceElem | MatrixSpaceElem?
|MatSpaceView | MatrixSpaceView?
|MatrixSpace | matrix_space

- 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`?