/// \defgroup PkgPeriodic3Mesh3Ref Reference Manual

/// \defgroup PkgPeriodic3Mesh3Concepts Concepts
/// \ingroup PkgPeriodic3Mesh3Ref
/// The concepts of this package.

/// \defgroup PkgPeriodic3Mesh3MeshClasses Mesh Classes
/// \ingroup PkgPeriodic3Mesh3Ref
/// The classes in this group are the main classes involved in the mesh generation process.

/// \defgroup PkgPeriodic3Mesh3Domains Domain Classes
/// \ingroup PkgPeriodic3Mesh3Ref
/// The classes in this group are models of domain concepts and their associated classes.

/// \defgroup PkgPeriodic3Mesh3Functions Mesh Generation Functions
/// \ingroup PkgPeriodic3Mesh3Ref
/// The two main functions to generate a periodic mesh are `make_periodic_3_mesh_3()`
/// and `refine_periodic_3_mesh_3()`. Other functions are provided to optimize
/// an existing periodic mesh.

/// \defgroup PkgPeriodic3Mesh3IOFunctions Input/Output Functions
/// \ingroup PkgPeriodic3Mesh3Ref
/// The free functions that can be used to read and write periodic meshes.

/*!
\addtogroup PkgPeriodic3Mesh3Ref
\cgalPkgDescriptionBegin{3D Periodic Mesh Generation,PkgPeriodic3Mesh3}
\cgalPkgPicture{periodic_mesher_small.png}
\cgalPkgSummaryBegin
\cgalPkgAuthors{Mikhail Bogdanov, Aymeric Pellé, Mael Rouxel-Labbé, and Monique Teillaud}
\cgalPkgDesc{This package is devoted to the generation of isotropic simplicial meshes
discretizing periodic 3D domains. The domain to be meshed is a region of
the three-dimensional flat torus. The periodic mesh generator provides users with the same
flexibility that is offered in the \ref PkgMesh3 package.}
\cgalPkgManuals{Chapter_3D_Periodic_Mesh_Generation,PkgPeriodic3Mesh3Ref}
\cgalPkgSummaryEnd
\cgalPkgShortInfoBegin
\cgalPkgSince{4.13}
\cgalPkgDependsOn{\ref PkgPeriodic3Triangulation3, \ref PkgMesh3, and \ref thirdpartyEigen}
\cgalPkgBib{cgal:btprl-p3m3}
\cgalPkgLicense{\ref licensesGPL "GPL"}
\cgalPkgShortInfoEnd
\cgalPkgDescriptionEnd

\cgalHeading{Relation to the 3D Mesh Generation and 3D Periodic Triangulations Packages}

A periodic mesh extends, by definition, infinitely in space. To avoid storing and
manipulating duplicate points, well-chosen "dummy" points are inserted
at the beginning of the meshing process, thus ensuring that the underlying periodic
triangulation forms at all times a simplicial complex within a single copy of the periodic space \f$ \mathbb T_c^3\f$
(see Sections \ref P3Triangulation3secspace and \ref P3Triangulation3secintro
of the package \ref PkgPeriodic3Triangulation3).
By identifying a single copy of the flat torus \f$ \mathbb T_{c_x,c_y,c_y}^3\f$ (where `c_x`,`c_y`,
and `c_z` denote the period along the canonical axes) with a cuboid of side lengths `c_x`,`c_y`,
and`c_z` in \f$ \mathbb R^3\f$, the meshing process can be exclusively conducted within a cuboid.
The mesh within a single copy is created using \cgal's \ref PkgMesh3 package, but
because \cgal's \ref PkgMesh3 package aims to mesh traditional (non-periodic)
domains, an interface is necessary between \cgal's \ref PkgMesh3 package
and \cgal's \ref PkgPeriodic3Triangulation3.
This package offers these interfaces.

\cgalClassifedRefPages

\cgalCRPSection{Concepts}

This package relies entirely on the \ref PkgMesh3Concepts
and the \ref PkgMesh3SecondaryConcepts described in the \ref PkgMesh3 package.
The following concepts are essentially identical to the concepts `MeshDomain_3`
and `MeshDomainWithFeatures_3` in the package \ref PkgMesh3 :

- `Periodic_3MeshDomain_3`
- `Periodic_3MeshDomainWithFeatures_3`

\cgalCRPSection{Classes}

The following class provides the interface between \cgal's periodic triangulation
and \cgal's three-dimensional mesh generator:
- `CGAL::Periodic_3_mesh_triangulation_3<MD, K, Vertex_base, Cell_base>`

The following class allows to construct a periodic implicit function from an implicit function that is not periodic:
- `CGAL::Periodic_3_function_wrapper<Function,BGT>`

The following class allows to split the canonical cuboid in two subdomains,
separated by the zero-level of an implicit function:
- `CGAL::Implicit_to_labeled_subdomains_function_wrapper<Function,BGT>`

\cgalCRPSection{Function Templates}

The following functions handle the generation of a periodic mesh:
- `CGAL::make_periodic_3_mesh_3()`
- `CGAL::refine_periodic_3_mesh_3()`
- `CGAL::exude_periodic_3_mesh_3()`
- `CGAL::perturb_periodic_3_mesh_3()`
- `CGAL::lloyd_optimize_periodic_3_mesh_3()`
- `CGAL::odt_optimize_periodic_3_mesh_3()`

\cgalCRPSection{Classes and Functions of `Mesh_3`}

Many classes and functions used by this package are defined within the package
\ref PkgMesh3, see \ref PkgMesh3MeshClasses, \ref PkgMesh3Domains,
and \ref PkgMesh3Parameters.

\cgalCRPSection{Input/Output Functions}
- \link PkgPeriodic3Mesh3IOFunctions `CGAL::IO::output_periodic_mesh_to_medit()` \endlink

*/
