Skip to content

docs: add some doxygen comments #245

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 5 commits into
base: master
Choose a base branch
from
Open

docs: add some doxygen comments #245

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
a8d3f79
add doxygen comments for Cell
kivvix Dec 10, 2024
49f3325
improve doc on cell
kivvix Dec 10, 2024
3523bd2
improve doc on cell
kivvix Dec 10, 2024
95d91e9
improve doc on cell
kivvix Dec 10, 2024
fa72c0e
improve doc on box.hpp file
kivvix Dec 10, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 1 addition & 2 deletions docs/source/api/cell.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,5 @@
Cell class
==========

.. doxygenclass:: samurai::Cell
.. doxygenfile:: cell.hpp
:project: samurai
:members:
43 changes: 35 additions & 8 deletions include/samurai/box.hpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,7 +55,7 @@ namespace samurai
////////////////////////

/**
* Construction of a bounded box.
* @brief Construction of a bounded box.
*
* @param min_corner The vertex with the minimum coordinates
* @param max_corner The vertex with the maximum coordinates
Expand All @@ -68,7 +68,7 @@ namespace samurai
}

/**
* Return the min corner of the box.
* @brief Return the min corner of the box.
*/
template <class value_t, std::size_t dim_>
inline auto Box<value_t, dim_>::min_corner() const -> const point_t&
Expand All @@ -77,7 +77,7 @@ namespace samurai
}

/**
* Return the min corner of the box.
* @brief Return the min corner of the box.
*/
template <class value_t, std::size_t dim_>
inline auto Box<value_t, dim_>::min_corner() -> point_t&
Expand All @@ -86,7 +86,7 @@ namespace samurai
}

/**
* Return the max corner of the box.
* @brief Return the max corner of the box.
*/
template <class value_t, std::size_t dim_>
inline auto Box<value_t, dim_>::max_corner() const -> const point_t&
Expand All @@ -95,7 +95,7 @@ namespace samurai
}

/**
* Return the max corner of the box.
* @brief Return the max corner of the box.
*/
template <class value_t, std::size_t dim_>
inline auto Box<value_t, dim_>::max_corner() -> point_t&
Expand All @@ -104,7 +104,7 @@ namespace samurai
}

/**
* Return the length of the box.
* @brief Return the length of the box.
*/
template <class value_t, std::size_t dim_>
inline auto Box<value_t, dim_>::length() const
Expand All @@ -113,7 +113,7 @@ namespace samurai
}

/**
* Return the minimum length of the box.
* @brief Return the minimum length of the box.
*/
template <class value_t, std::size_t dim_>
inline auto Box<value_t, dim_>::min_length() const
Expand All @@ -122,14 +122,19 @@ namespace samurai
}

/**
* Check if the box is valid.
* @brief Check if the box is valid.
*/
template <class value_t, std::size_t dim_>
inline bool Box<value_t, dim_>::is_valid() const
{
return xt::all(m_min_corner < m_max_corner);
}

/**
* @brief Inplace homothety operator of ratio v.
*
* @param v Ratio of homothety.
*/
template <class value_t, std::size_t dim_>
inline auto Box<value_t, dim_>::operator*=(value_t v) -> Box&
{
Expand All @@ -138,27 +143,49 @@ namespace samurai
return *this;
}

/**
* @brief Homothety operator of ratio v.
*
* @param box Box to dilate.
* @param v Ratio of homothety.
*/
template <class value_t, std::size_t dim_>
inline auto operator*(const Box<value_t, dim_>& box, value_t v)
{
Box<value_t, dim_> that(box);
return that *= v;
}

/**
* @brief Homothety operator of ratio v.
*
* @param v Ratio of homothety.
* @param box Box to dilate.
*/
template <class value_t, std::size_t dim_>
inline auto operator*(value_t v, const Box<value_t, dim_>& box)
{
Box<value_t, dim_> that(box);
return that *= v;
}

/**
* @brief Insert formatted box into an output stream.
*/
template <class value_t, std::size_t dim>
inline std::ostream& operator<<(std::ostream& out, const Box<value_t, dim>& box)
{
out << "Box(" << box.min_corner() << ", " << box.max_corner() << ")";
return out;
}

/**
* @brief Return approximate box with given subdivision length with a tolerance.
*
* @param box Box to approximate.
* @param tol Tolerance for approximate box if subdivision isn't given.
* @param subdivision_length Length of subdivision (modified if is 0 to the approximate box with given tolerance).
*/
template <class value_t, std::size_t dim>
Box<value_t, dim> approximate_box(const Box<value_t, dim>& box, double tol, double& subdivision_length)
{
Expand Down
78 changes: 67 additions & 11 deletions include/samurai/cell.hpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,10 +11,16 @@

namespace samurai
{
/**
* @brief Return length (\f$\Delta x\f$) of a cell on a specific level with a specific scaling factor
*
* @param scaling_factor Scaling factor of the box.
* @param level Level of cell.
*/
template <typename LevelType, std::enable_if_t<std::is_integral<LevelType>::value, bool> = true>
inline double cell_length(double scaling_factor, LevelType level)
{
return scaling_factor / (1 << level);
return scaling_factor / static_cast<double>(1 << level);
}

/** @class Cell
Expand All @@ -29,12 +35,12 @@ namespace samurai
template <std::size_t dim_, class TInterval>
struct Cell
{
static constexpr std::size_t dim = dim_;
using interval_t = TInterval;
using value_t = typename interval_t::value_t;
using index_t = typename interval_t::index_t;
using indices_t = xt::xtensor_fixed<value_t, xt::xshape<dim>>;
using coords_t = xt::xtensor_fixed<double, xt::xshape<dim>>;
static constexpr std::size_t dim = dim_; ///< The dimension of the cell.
using interval_t = TInterval; ///< Type of interval.
using value_t = typename interval_t::value_t; ///< Type of value stored in interval.
using index_t = typename interval_t::index_t; ///< Type of index stored in interval.
using indices_t = xt::xtensor_fixed<value_t, xt::xshape<dim>>; ///< Type of indices to access to field data.
using coords_t = xt::xtensor_fixed<double, xt::xshape<dim>>; ///< Type of coordinates.

Cell() = default;

Expand All @@ -46,14 +52,15 @@ namespace samurai
const xt::xtensor_fixed<value_t, xt::xshape<dim - 1>> others,
index_t index);

// The minimum corner of the cell.
coords_t corner() const;
double corner(std::size_t i) const;

/// The center of the cell.
// The center of the cell.
coords_t center() const;
double center(std::size_t i) const;

/// The center of the face in the requested Cartesian direction.
// The center of the face in the requested Cartesian direction.
template <class Vector>
coords_t face_center(const Vector& direction) const;

Expand All @@ -74,6 +81,15 @@ namespace samurai
double length = 0;
};

/**
* @brief Construct a new Cell<dim_, TInterval>::Cell object
*
* @param origin_point_
* @param scaling_factor
* @param level_
* @param indices_
* @param index_
*/
template <std::size_t dim_, class TInterval>
inline Cell<dim_, TInterval>::Cell(const coords_t& origin_point_,
double scaling_factor,
Expand All @@ -88,6 +104,16 @@ namespace samurai
{
}

/**
* @brief Construct a new Cell<dim_, TInterval>::Cell object
*
* @param origin_point_
* @param scaling_factor
* @param level_
* @param i
* @param others
* @param index_
*/
template <std::size_t dim_, class TInterval>
inline Cell<dim_, TInterval>::Cell(const coords_t& origin_point_,
double scaling_factor,
Expand All @@ -107,35 +133,51 @@ namespace samurai
}

/**
* The minimum corner of the cell.
* @brief The minimum corner of the cell.
*/
template <std::size_t dim_, class TInterval>
inline auto Cell<dim_, TInterval>::corner() const -> coords_t
{
return origin_point + length * indices;
}

/**
* @brief The ith coordinate of minimum corner of the cell.
*
* @param i Component number.
*/
template <std::size_t dim_, class TInterval>
inline double Cell<dim_, TInterval>::corner(std::size_t i) const
{
return origin_point[i] + length * indices[i];
}

/**
* The minimum corner of the cell.
* @brief The center of the cell.
*/
template <std::size_t dim_, class TInterval>
inline auto Cell<dim_, TInterval>::center() const -> coords_t
{
return origin_point + length * (indices + 0.5);
}

/**
* @brief The ith coordinate of center of the cell.
*
* @param i Component number.
*/
template <std::size_t dim_, class TInterval>
inline double Cell<dim_, TInterval>::center(std::size_t i) const
{
return origin_point[i] + length * (indices[i] + 0.5);
}

/**
* @brief The center of the face in the requested Cartesian direction.
*
* @tparam Vector Type of direction, must be addable with a `coords_t`.
* @param direction Cartesian unit vector of direction where we request center.
*/
template <std::size_t dim_, class TInterval>
template <class Vector>
inline auto Cell<dim_, TInterval>::face_center(const Vector& direction) const -> coords_t
Expand All @@ -144,25 +186,39 @@ namespace samurai
return center() + (length / 2) * direction;
}

/**
* @brief Insert formatted cell into an output stream.
*
* @param os output stream
*/
template <std::size_t dim_, class TInterval>
inline void Cell<dim_, TInterval>::to_stream(std::ostream& os) const
{
os << "Cell -> level: " << level << " indices: " << indices << " center: " << center() << " index: " << index;
}

/**
* @brief Insert formatted cell into an output stream.
*/
template <std::size_t dim, class TInterval>
inline std::ostream& operator<<(std::ostream& out, const Cell<dim, TInterval>& cell)
{
cell.to_stream(out);
return out;
}

/**
* @brief Test equality between cells.
*/
template <std::size_t dim, class TInterval>
inline bool operator==(const Cell<dim, TInterval>& c1, const Cell<dim, TInterval>& c2)
{
return !(c1.level != c2.level || c1.indices != c2.indices || c1.index != c2.index || c1.length != c2.length);
}

/**
* @brief Test inequality between cells.
*/
template <std::size_t dim, class TInterval>
inline bool operator!=(const Cell<dim, TInterval>& c1, const Cell<dim, TInterval>& c2)
{
Expand Down
Loading