Merge pull request #3574 from oscar-system/backports-release-1.0

Backports Oscar 1.0.1
oscar-system · Apr 17, 2024 · e0e8ed9 · e0e8ed9 · benlorenz · Apr 17, 2024
2 parents a148cee + d1caf3f
commit e0e8ed9
Show file tree

Hide file tree

Showing 233 changed files with 6,162 additions and 127 deletions.
diff --git a/.github/workflows/CI.yml b/.github/workflows/CI.yml
@@ -54,6 +54,9 @@ jobs:
           - julia-version: '1.10'
             group: 'long'
             os: macOS-latest
+          - julia-version: '1.10'
+            group: 'book'
+            os: ubuntu-latest
           # nightly on macos is disabled for now since the macos jobs take too long
           # with just 5 runners
           #- julia-version: 'nightly'

diff --git a/CITATION.cff b/CITATION.cff
@@ -31,6 +31,7 @@ preferred-citation:
     given-names: "Max"
   - family-names: "Joswig"
     given-names: "Michael"
-  title: The OSCAR book
+  title: "The Computer Algebra System OSCAR: Algorithms and Examples"
   year: 2024
-
+  publisher:
+    name: "Springer"
diff --git a/Project.toml b/Project.toml
@@ -1,7 +1,7 @@
 name = "Oscar"
 uuid = "f1435218-dba5-11e9-1e4d-f1a5fab5fc13"
-authors = ["The OSCAR Team <oscar@mathematik.uni-kl.de>"]
-version = "1.0.0"
+authors = ["The OSCAR Team <oscar@oscar-system.org>"]
+version = "1.0.1"
 
 [deps]
 AbstractAlgebra = "c3fe647b-3220-5bb0-a1ea-a7954cac585d"
@@ -26,7 +26,7 @@ UUIDs = "cf7118a7-6976-5b1a-9a39-7adc72f591a4"
 cohomCalg_jll = "5558cf25-a90e-53b0-b813-cadaa3ae7ade"
 
 [compat]
-AbstractAlgebra = "0.40.1"
+AbstractAlgebra = "0.40.8"
 AlgebraicSolving = "0.4.11"
 Distributed = "1.6"
 DocStringExtensions = "0.8, 0.9"

diff --git a/README.md b/README.md
@@ -37,7 +37,7 @@ julia> using Oscar
  / _ \ / ___| / ___|  / \  |  _ \   |  Combining ANTIC, GAP, Polymake, Singular
 | | | |\___ \| |     / _ \ | |_) |  |  Type "?Oscar" for more information
 | |_| | ___) | |___ / ___ \|  _ <   |  Manual: https://docs.oscar-system.org
- \___/ |____/ \____/_/   \_\_| \_\  |  Version 1.0.0
+ \___/ |____/ \____/_/   \_\_| \_\  |  Version 1.0.1
 
 julia> k, a = quadratic_field(-5)
 (Imaginary quadratic field defined by x^2 + 5, sqrt(-5))
@@ -120,25 +120,30 @@ pm::Array<topaz::HomologyGroup<pm::Integer> >
 If you have used OSCAR in the preparation of a paper please cite it as described below:
 
     [OSCAR]
-        OSCAR -- Open Source Computer Algebra Research system, Version 1.0.0, The OSCAR Team, 2024. (https://www.oscar-system.org)
+        OSCAR -- Open Source Computer Algebra Research system, Version 1.0.1,
+        The OSCAR Team, 2024. (https://www.oscar-system.org)
     [OSCAR-book]
-        Wolfram Decker, Christian Eder, Claus Fieker, Max Horn, Michael Joswig, The OSCAR book, 2024.
+        Wolfram Decker, Christian Eder, Claus Fieker, Max Horn, Michael Joswig, eds.
+        The Computer Algebra System OSCAR: Algorithms and Examples,
+        Algorithms and Computation in Mathematics, Springer, 2024.
 
 If you are using BibTeX, you can use the following BibTeX entries:
 
     @misc{OSCAR,
       key          = {OSCAR},
       organization = {The OSCAR Team},
       title        = {OSCAR -- Open Source Computer Algebra Research system,
-                      Version 1.0.0},
+                      Version 1.0.1},
       year         = {2024},
       url          = {https://www.oscar-system.org},
       }
 
-    @Book{OSCAR-book,
+    @book{OSCAR-book,
       editor = {Decker, Wolfram and Eder, Christian and Fieker, Claus and Horn, Max and Joswig, Michael},
-      title = {The OSCAR book},
+      title = {The {C}omputer {A}lgebra {S}ystem {OSCAR}: {A}lgorithms and {E}xamples},
       year = {2024},
+      publisher = {Springer},
+      series = {Algorithms and {C}omputation in {M}athematics},
     }
 
 ## Funding

diff --git a/docs/src/AlgebraicGeometry/Curves/ProjectivePlaneCurves.md b/docs/src/AlgebraicGeometry/Curves/ProjectivePlaneCurves.md
@@ -94,7 +94,7 @@ parametrization(C::ProjectivePlaneCurve{QQField})
 
 Please direct questions about this part of OSCAR to the following people:
 * [Janko Böhm](https://www.mathematik.uni-kl.de/~boehm/),
-* [Wolfram Decker](https://www.mathematik.uni-kl.de/en/agag/people/head/prof-dr-wolfram-decker/seite).
+* [Wolfram Decker](https://math.rptu.de/en/wgs/agag/people/head/decker).
 
 You can ask questions in the [OSCAR Slack](https://www.oscar-system.org/community/#slack).
 

diff --git a/docs/src/AlgebraicGeometry/Miscellaneous/miscellaneous.md b/docs/src/AlgebraicGeometry/Miscellaneous/miscellaneous.md
@@ -17,7 +17,7 @@ grassmann_pluecker_ideal
 ## Contact
 
 Please direct questions about this part of OSCAR to the following people:
-* [Wolfram Decker](https://www.mathematik.uni-kl.de/en/agag/people/head/prof-dr-wolfram-decker).
+* [Wolfram Decker](https://math.rptu.de/en/wgs/agag/people/head/decker).
 
 You can ask questions in the [OSCAR Slack](https://www.oscar-system.org/community/#slack).
 

diff --git a/docs/src/AlgebraicGeometry/Schemes/intro.md b/docs/src/AlgebraicGeometry/Schemes/intro.md
@@ -20,7 +20,7 @@ This project is work-in-progress.
 Please direct questions about this part of OSCAR to the following people:
 * [Simon Brandhorst](https://www.math.uni-sb.de/ag/brandhorst/index.php?lang=en).
 * [Anne Frühbis-Krüger](https://uol.de/anne-fruehbis-krueger),
-* [Matthias Zach](https://www.mathematik.uni-kl.de/en/agag/people/members),
+* [Matthias Zach](https://math.rptu.de/en/wgs/agag/people/members),
 
 You can ask questions in the [OSCAR Slack](https://www.oscar-system.org/community/#slack).
 

diff --git a/docs/src/AlgebraicGeometry/Surfaces/K3Surfaces.md b/docs/src/AlgebraicGeometry/Surfaces/K3Surfaces.md
@@ -36,7 +36,7 @@ has_zero_entropy
 
 Please direct questions about this part of OSCAR to the following people:
 * [Simon Brandhorst](https://www.math.uni-sb.de/ag/brandhorst/index.php?lang=en).
-* [Matthias Zach](https://www.mathematik.uni-kl.de/en/agag/people/members),
+* [Matthias Zach](https://math.rptu.de/en/wgs/agag/people/members),
 
 You can ask questions in the [OSCAR Slack](https://www.oscar-system.org/community/#slack).
 

diff --git a/docs/src/AlgebraicGeometry/Surfaces/SurfacesP4.md b/docs/src/AlgebraicGeometry/Surfaces/SurfacesP4.md
@@ -341,7 +341,7 @@ elliptic_d12_pi14_ss_inf()
 ## Contact
 
 Please direct questions about this part of OSCAR to the following people:
-* [Wolfram Decker](https://www.mathematik.uni-kl.de/en/agag/people/head/prof-dr-wolfram-decker).
+* [Wolfram Decker](https://math.rptu.de/en/wgs/agag/people/head/decker).
 
 You can ask questions in the [OSCAR Slack](https://www.oscar-system.org/community/#slack).
 

diff --git a/docs/src/AlgebraicGeometry/ToricVarieties/AlgebraicCycles.md b/docs/src/AlgebraicGeometry/ToricVarieties/AlgebraicCycles.md
@@ -61,7 +61,7 @@ rational_equivalence_class(v::NormalToricVarietyType, p::MPolyQuoRingElem)
 rational_equivalence_class(v::NormalToricVarietyType, coefficients::Vector{T}) where {T <: IntegerUnion}
 ```
 
-### Special constructors
+### [Special constructors](@id toric_special_constructors)
 
 ```@docs
 rational_equivalence_class(d::ToricDivisor)
@@ -95,7 +95,7 @@ An algebraic cycle can be intersected `n`- with itself via `^n`,
 where `n` can be an integer of of type `ZZRingElem`.
 
 A closed subvarieties defines in a natural way a rational equivalence
-class (cf. section on special constructors above). This allows to
+class (cf. [Special constructors](@ref toric_special_constructors)). This allows to
 compute intersection products among closed subvarieties and rational
 equivalence classes in the Chow ring.
 

diff --git a/docs/src/AlgebraicGeometry/ToricVarieties/ToricSchemes.md b/docs/src/AlgebraicGeometry/ToricVarieties/ToricSchemes.md
@@ -34,7 +34,7 @@ forget_toric_structure(X::NormalToricVariety)
 
 Please direct questions about this part of OSCAR to the following people:
 * [Martin Bies](https://martinbies.github.io/),
-* [Matthias Zach](https://www.mathematik.uni-kl.de/en/agag/people/members/seite).
+* [Matthias Zach](https://math.rptu.de/en/wgs/agag/people/members).
 
 You can ask questions in the [OSCAR Slack](https://www.oscar-system.org/community/#slack).
 

diff --git a/docs/src/CommutativeAlgebra/GroebnerBases/groebner_bases.md b/docs/src/CommutativeAlgebra/GroebnerBases/groebner_bases.md
@@ -5,7 +5,7 @@ DocTestSetup = quote
 end
 ```
 
-# Gröbner/Standard Bases Over Fields
+# [Gröbner/Standard Bases Over Fields](@id gb_fields)
 
 We fix our notation in the context of standard (Gröbner) bases and present relevant OSCAR functions.
 
@@ -77,7 +77,7 @@ julia> default_ordering(S)
 wdegrevlex([x, y, z], [1, 2, 3])
 ```
 
-## Monomials, Terms, and More
+## [Monomials, Terms, and More](@id monomials_terms_more)
 
 Here are examples which indicate how to recover monomials, terms, and
 more from a given polynomial.
@@ -400,7 +400,7 @@ normal_form(g::T, I::MPolyIdeal; ordering::MonomialOrdering = default_ordering(b
 
 ## Syzygies
 
-We refer to the section on modules for more on syzygies.
+We refer to the section on [modules](@ref modules_multivariate) for more on syzygies.
 
 ```@docs
 syzygy_generators(G::Vector{<:MPolyRingElem})

diff --git a/docs/src/CommutativeAlgebra/GroebnerBases/groebner_bases_integers.md b/docs/src/CommutativeAlgebra/GroebnerBases/groebner_bases_integers.md
@@ -33,7 +33,7 @@ julia> reduce(6*x, [5*x, 2*x])
 0
 ```
 
-The notion of *leading ideals*  as formulated in the previous section and the definitions of
+The notion of *leading ideals*  as formulated in [the previous section](@ref gb_fields) and the definitions of
 standard bases (Gröbner bases) carry over: A *standard basis* for an ideal $I\subset K[x]_>$
 with respect to $>$ is a finite subset $G$ of $I$ such that $\text{L}_>(G) = \text{L}_>(I)$ (a
 standard basis with respect to a global monomial ordering is also called a *Gröbner basis*).

diff --git a/docs/src/CommutativeAlgebra/GroebnerBases/orderings.md b/docs/src/CommutativeAlgebra/GroebnerBases/orderings.md
@@ -5,7 +5,7 @@ DocTestSetup = quote
 end
 ```
 
-# Monomial Orderings
+# [Monomial Orderings](@id monomial_orderings)
 
 Given a coefficient ring $C$ as in the previous section, let $C[x]=C[x_1, \ldots, x_n]$
 be the polynomial ring over $C$ in the set of variables $x=\{x_1, \ldots, x_n\}$. Monomials
@@ -37,7 +37,7 @@ A monomial ordering $>$ on $\text{Mon}_n(x)$ is called
 !!! note
     The lexicograpical monomial ordering specifies the default way of storing and displaying multivariate polynomials in OSCAR (terms are sorted in descending order).
     The other orderings which can be attached to a multivariate polynomial ring are the degree lexicographical ordering  and the degree reverse lexicographical
-    ordering. Independently of the attached orderings, Gröbner bases can be computed with respect to any monomial ordering. See the section on Gröbner bases.
+    ordering. Independently of the attached orderings, Gröbner bases can be computed with respect to any monomial ordering. See the section on [Gröbner bases](@ref gb_fields).
 
 In this section, we show how to create monomial orderings in OSCAR. 
 

diff --git a/docs/src/CommutativeAlgebra/Miscellaneous/binomial_ideals.md b/docs/src/CommutativeAlgebra/Miscellaneous/binomial_ideals.md
@@ -31,7 +31,7 @@ While the first step can be performed over any ground field for which Gröbner b
 !!! note
     A *pure difference binomial* is a binomial which is the difference of two monomials. A *unital binomial ideal* is an ideal which can be generated by pure difference binomials and monomials. Note that cellular components of unital binomial ideals are unital as well. For unital binomial ideals in $\mathbb Q[x_1, \dots, x_n]$, binomial primary decompositions exist already over cyclotomic extensions of $\mathbb Q$. In particular, any such ideal can be decomposed over the abelian closure $\mathbb Q^{\text{ab}}$ of $\mathbb Q$. While OSCAR offers functionality for doing this, computing  binomial primary decompositions  in other cases is not yet supported. 
 
-    See the number theory chapter for how to deal with $\mathbb Q^{\text{ab}}$.
+    See the [number theory](@ref number_theory) chapter for how to deal with $\mathbb Q^{\text{ab}}$.
 !!! note
     Binomial primary decompositions computed with OSCAR are not necessarily minimal.
 

diff --git a/docs/src/CommutativeAlgebra/ModulesOverMultivariateRings/free_modules.md b/docs/src/CommutativeAlgebra/ModulesOverMultivariateRings/free_modules.md
@@ -5,7 +5,7 @@ DocTestSetup = quote
 end
 ```
 
-# Free Modules
+# [Free Modules](@id free_modules)
 
 In this section, the expression *free module*  refers to a free module of finite rank
 over a ring of type `MPolyRing`, `MPolyQuoRing`, `MPolyLocRing`, or `MPolyQuoLocRing`.

diff --git a/docs/src/CommutativeAlgebra/ModulesOverMultivariateRings/intro.md b/docs/src/CommutativeAlgebra/ModulesOverMultivariateRings/intro.md
@@ -2,7 +2,7 @@
 CurrentModule = Oscar
 ```
 
-# Introduction
+# [Introduction](@id modules_multivariate)
 
 Our focus in this section is on finitely presented modules over rings from the following list:
 - multivariate polynomial rings (OSCAR type `MPolyRing`),
@@ -17,8 +17,8 @@ modules which naturally  includes both submodules and quotients of free modules.
 
 !!! note
     Most functions in this section rely on Gröbner (standard) bases techniques. Thus, the functions
-    should not be applied to modules over rings other than those from the list above. See the Linear
-    Algebra chapter for module types which are designed to handle modules over Euclidean
+    should not be applied to modules over rings other than those from the list above. See the [Linear
+    Algebra](@ref linear_algebra) chapter for module types which are designed to handle modules over Euclidean
     domains.
 
 !!! note

diff --git a/docs/src/CommutativeAlgebra/ModulesOverMultivariateRings/subquotients.md b/docs/src/CommutativeAlgebra/ModulesOverMultivariateRings/subquotients.md
@@ -34,7 +34,7 @@ Finally, we refer to
 and regard $M$ as a submodule of that ambient module, embedded in the natural way.
 
 !!! note
-    Recall from the section on free modules that by a free $R$-module we mean a free
+    Recall from the section on [free modules](@ref free_modules) that by a free $R$-module we mean a free
     module of type $R^p$ , where we think of $R^p$ as a free module with a given
     basis, namely the basis of standard unit vectors. Accordingly, elements of free modules
     are represented by coordinate vectors, and homomorphisms between free modules by

diff --git a/docs/src/CommutativeAlgebra/affine_algebras.md b/docs/src/CommutativeAlgebra/affine_algebras.md
@@ -5,7 +5,7 @@ DocTestSetup = quote
 end
 ```
 
-# Affine Algebras and Their Ideals
+# [Affine Algebras and Their Ideals](@id affine_algebras)
 
 With regard to notation, we use *affine algebra* as a synonym for *quotient of a multivariate polynomial ring by an ideal*.
 More specifically, if $R$ is a multivariate polynomial ring with coefficient ring $C$, and $A=R/I$ is the quotient of $R$
@@ -14,14 +14,14 @@ discuss functionality for handling such algebras in OSCAR.
 
 !!! note
     To emphasize this point: In this section, we view $R/I$ together with its ring structure. Realizing $R/I$ as an
-    $R$-module means to implement it as the quotient of a free $R$-module of rank 1. See the section on modules.
+    $R$-module means to implement it as the quotient of a free $R$-module of rank 1. See the section on [modules](@ref modules_multivariate).
 
 !!! note
     Most functions discussed here rely on Gröbner basis techniques. In particular, they typically make use of a Gröbner basis for the
     modulus of the quotient. Nevertheless, the construction of quotients is lazy in the sense that the computation of such a Gröbner
     basis is delayed until the user performs an operation that indeed requires it (the Gröbner basis is then computed with respect
     to the monomial ordering entered by the user when creating the quotient; if no such ordering is entered, OSCAR will use the
-	`default_ordering` on the underlying polynomial ring; see the section on Gröbner/Standard Bases for default orderings in OSCAR).
+	`default_ordering` on the underlying polynomial ring; see the section on [Gröbner/Standard Bases](@ref gb_fields) for default orderings in OSCAR).
 	Once computed, the Gröbner basis is cached for later reuse.
 
 !!! note
@@ -31,7 +31,7 @@ discuss functionality for handling such algebras in OSCAR.
 !!! note
     In OSCAR, elements of a quotient $A = R/I$ are not necessarily represented by polynomials which are reduced with regard to $I$.
     That is, if $f\in R$ is the internal polynomial representative of an element of $A$, then $f$ may not be the normal form mod $I$
-    with respect to the default ordering on $R$ (see the section on *Gröbner/Standard Bases* for normal forms). Operations involving
+    with respect to the default ordering on $R$ (see the section on [Gröbner/Standard Bases](@ref gb_fields) for normal forms). Operations involving
     Gröbner basis computations may lead to (partial) reductions. The function `simplify` discussed in this section computes fully
     reduced representatives.
 

diff --git a/docs/src/CommutativeAlgebra/intro.md b/docs/src/CommutativeAlgebra/intro.md
@@ -2,7 +2,7 @@
 CurrentModule = Oscar
 ```
 
-# Introduction
+# [Introduction](@id commutative_algebra)
 
 The commutative algebra part of OSCAR provides functionality for dealing with
 
@@ -15,7 +15,7 @@ We use *affine algebra* as a synonym for *quotient of a multivariate polynomial
 
 Fundamental to computational commutative algebra is the concept of *standard bases*. Each such basis
 is defined relative to a *monomial ordering*. If this ordering is a well-ordering, a standard basis is also called
-a *Gröbner basis*. We refer to the corresponding section in this chapter for details.
+a *Gröbner basis*. We refer to the corresponding [section](@ref gb_fields) in this chapter for details.
 
 !!! note
     Each multivariate polynomial ring in OSCAR comes equipped with a monomial ordering according to which the
@@ -44,7 +44,7 @@ General textbooks offering details on theory and algorithms include:
 ## Contact
 
 Please direct questions about this part of OSCAR to the following people:
-* [Wolfram Decker](https://www.mathematik.uni-kl.de/en/agag/people/head/prof-dr-wolfram-decker).
+* [Wolfram Decker](https://math.rptu.de/en/wgs/agag/people/head/decker).
 
 You can ask questions in the [OSCAR Slack](https://www.oscar-system.org/community/#slack).
 

diff --git a/docs/src/CommutativeAlgebra/localizations.md b/docs/src/CommutativeAlgebra/localizations.md
@@ -23,7 +23,7 @@ Mimicking the standard arithmetic for fractions, ``R[U^{-1}]`` can be made into
 \iota : R\to R[U^{-1}],\; r \mapsto \frac{r}{1}.
 ```
 Given an ``R``-module ``M``, the analogous construction yields an ``R[U^{-1}]``-module ``M[U^{-1}]`` which is
-called the *localization  of ``M`` at ``U``*. See the section on modules.
+called the *localization  of ``M`` at ``U``*. See the section on [modules](@ref modules_multivariate).
 
 Our focus in this section is on localizing multivariate polynomial rings and their quotients. The starting point
 for this is to provide functionality for handling (several types of) multiplicatively closed subsets of multivariate

diff --git a/docs/src/CommutativeAlgebra/rings.md b/docs/src/CommutativeAlgebra/rings.md
@@ -7,8 +7,9 @@ end
 
 # Creating Multivariate Rings
 
-In this section, for the convenience of the reader, we recall from the chapters on rings and fields
-how to create multivariate polynomial rings and their elements, adding illustrating examples.
+In this section, for the convenience of the reader, we recall from the chapters on
+[rings](@ref rings) and [fields](@ref fields) how to create multivariate polynomial
+rings and their elements, adding illustrating examples.
 At the same time, we introduce and illustrate a ring type for modelling multivariate polynomial
 rings with gradings.
 
@@ -432,7 +433,7 @@ Given an element `f` of a multivariate polynomial ring `R` or a graded version o
     the notion of total degree ignores the weights given to the variables in the graded case.
 
 For iterators which allow one to recover the monomials  (terms, $\dots$) of `f` we refer to the
-subsection *Monomials, Terms, and More* of the section on *Gröbner/Standard Bases*.
+subsection [Monomials, Terms, and More](@ref monomials_terms_more) of the section on [Gröbner/Standard Bases](@ref gb_fields).
 
 ###### Examples
 
@@ -502,5 +503,5 @@ refer to `R` and `S`, respectively.
 !!! note
     The OSCAR homomorphism type `AffAlgHom` models ring homomorphisms `R` $\to$ `S` such that
     the type of both `R` and `S`  is a subtype of `Union{MPolyRing{T}, MPolyQuoRing{U}}`, where `T <: FieldElem` and
-    `U <: MPolyRingElem{T}`. Functionality for these homomorphism is discussed in the section on affine algebras.
+    `U <: MPolyRingElem{T}`. Functionality for these homomorphism is discussed in the section on [affine algebras](@ref affine_algebras).
 
diff --git a/docs/src/DeveloperDocumentation/new_developers.md b/docs/src/DeveloperDocumentation/new_developers.md
@@ -75,7 +75,7 @@ in Julia. This will create a directory `~/.julia/dev/Oscar`. This directory is
 a git clone of the central OSCAR repository. You can develop your code here,
 however you will still have to fork OSCAR, as you have no rights to push to the
 central repository. You can then add your fork as another remote, have a look
-at the section on rebasing below for hints.
+at the section on [rebasing](@ref rebasing) below for hints.
 
 
 ## The edit process
@@ -160,7 +160,7 @@ naming conventions, code formatting, etc.
 To build and test the documentation, please have a look at [Documenting OSCAR
 code](@ref).
 
-### Rebasing
+### [Rebasing](@id rebasing)
 One way to stay up to date with the current master is rebasing. In order to do
 this, add the main Oscar.jl repository as a remote, fetch, and then rebase.
 ```

diff --git a/docs/src/DeveloperDocumentation/styleguide.md b/docs/src/DeveloperDocumentation/styleguide.md
@@ -59,7 +59,13 @@ Here is a summary of the naming convention followed in OSCAR:
   also being consistent.
   For compatibility with standard Julia, while staying consistent internally,
   we also provide aliases (using `AbstractAlgebra.@alias`) for various standard
-  Julia functions, e.g. `is_one` as alias for `isone`
+  Julia functions, e.g. `is_one` as alias for `isone`.
+- A function returning the number of some things should be named `number_of_things`,
+  alternatively it can be named `n_things` with an alias to `number_of_things`.
+  The preferred style should be consistent throughout the corresponding part.
+  For some very common things, like the number of generators, we additionally
+  provide a shorter alias, e.g. `ngens` for `number_of_generators`. These aliases should be
+  very short and without underscores.
 - For generic concepts choose generic names, based on general algebraic
   concepts, preferably not special names from your area of speciality.
 - **Avoid direct access to members of our objects.** This means, do not use