Geometry: Doc Strings

Add more argument names and doc strings.
Use properties more and avoid equivalent overloads.

src/Base/Geometry.cpp

@@ -24,22 +24,27 @@ void init_Geometry(py::module& m)
  }
  )
  .def(py::init<>())
- .def_readonly("prob_domain", &GeometryData::prob_domain)
- .def_readonly("domain", &GeometryData::domain)
- .def_readonly("coord", &GeometryData::coord)
+ .def_readonly("prob_domain", &GeometryData::prob_domain, "The problem domain (real).")
+ .def_readonly("domain", &GeometryData::domain, "The index domain.")
+ .def_readonly("coord", &GeometryData::coord, "The Coordinates type.")
  .def_property_readonly("dx",
  [](const GeometryData& gd){
  std::array<Real,AMREX_SPACEDIM> dx {AMREX_D_DECL(
  gd.dx[0], gd.dx[1], gd.dx[2]
  )};
  return dx;
- })
+ },
+ "The cellsize for each coordinate direction."
+ )
  .def_property_readonly("is_periodic",
  [](const GeometryData& gd){
  std::array<int,AMREX_SPACEDIM> per {AMREX_D_DECL(
  gd.is_periodic[0], gd.is_periodic[1], gd.is_periodic[2]
  )};
- return per;})
+ return per;
+ },
+ "Returns whether the domain is periodic in each coordinate direction."
+ )
  // ,
  // [](GeometryData& gd, std::vector<Real> per_in) {
  // AMREX_D_TERM(gd.is_periodic[0] = per_in[0];,
@@ -128,16 +133,18 @@ void init_Geometry(py::module& m)
 
  .def("define", py::overload_cast<const Box&, const RealBox&,
  int, Array<int,AMREX_SPACEDIM> const&>
- (&Geometry::define), "Set geometry")
-
+ (&Geometry::define),
+ py::arg("dom"), py::arg("rb"), py::arg("coord"), py::arg("is_per"),
+ "Set geometry"
+ )
 
- .def("ProbDomain", py::overload_cast<>(&Geometry::ProbDomain, py::const_),
- "Return problem domain")
- .def("ProbDomain", [](Geometry& gm, const RealBox& rb) {
- if(gm.Ok()) { gm.ProbDomain(rb);}
- else { throw std::runtime_error("Can't call ProbDomain on undefined Geometry; use Define");}
- })
+ .def_property("prob_domain",
+ py::overload_cast<>(&Geometry::ProbDomain, py::const_),
+ py::overload_cast<RealBox const &>(&Geometry::ProbDomain),
+ "The problem domain (real)."
+ )
  .def("ProbLo", py::overload_cast<int>(&Geometry::ProbLo, py::const_),
+ py::arg("dir"),
  "Get the lo end of the problem domain in specified direction")
  .def("ProbLo",
  [](const Geometry& gm) {
@@ -147,6 +154,7 @@ void init_Geometry(py::module& m)
  "Get the list of lo ends of the problem domain"
  )
  .def("ProbHi", py::overload_cast<int>(&Geometry::ProbHi, py::const_),
+ py::arg("dir"),
  "Get the hi end of the problem domain in specified direction")
  .def("ProbHi",
  [](const Geometry& gm) {
@@ -157,11 +165,12 @@ void init_Geometry(py::module& m)
  )
  .def("ProbSize", &Geometry::ProbSize, "the overall size of the domain")
  .def("ProbLength", &Geometry::ProbLength, "length of problem domain in specified dimension")
- .def("Domain", py::overload_cast<>(&Geometry::Domain, py::const_), "Return rectangular domain")
- // .def("Domain", py::overload_cast<const Box&>(&Geometry::Domain), "Set rectangular domain")
- .def("Domain", [](Geometry& gm, const Box& bx) {
- if(gm.Ok()) { gm.Domain(bx);}
- else { throw std::runtime_error("Can't call Domain on undefined Geometry; use Define");}})
+
+ .def_property("domain",
+ py::overload_cast<>(&Geometry::Domain, py::const_),
+ py::overload_cast<Box const &>(&Geometry::Domain),
+ "The rectangular domain (index space)."
+ )
 
  // GetVolume
  // .def("GetVolume", py::overload_cast<MultiFab&>(&Geometry::GetVolume, py::const_))
@@ -178,30 +187,47 @@ void init_Geometry(py::module& m)
  "Is domain periodic in all directions?")
  .def("isPeriodic", py::overload_cast<>(&Geometry::isPeriodic, py::const_),
  "Return list indicating whether domain is periodic in each direction")
- .def("period", [](const Geometry& gm, const int dir) {
- if(gm.isPeriodic(dir)){ return gm.period(dir); }
- else { throw std::runtime_error("Geometry is not periodic in this direction."); }
- }, "Return the period in the specified direction")
- .def("periodicity", py::overload_cast<>(&Geometry::periodicity, py::const_)
- )
- .def("periodicity", py::overload_cast<const Box&>(&Geometry::periodicity, py::const_),
+ .def("period",
+ [](const Geometry& gm, const int dir) {
+ if(gm.isPeriodic(dir)){ return gm.period(dir); }
+ else { throw std::runtime_error("Geometry is not periodic in this direction."); }
+ },
+ py::arg("dir"),
+ "Return the period in the specified direction")
+ .def("periodicity",
+ py::overload_cast<>(&Geometry::periodicity, py::const_)
+ )
+ .def("periodicity",
+ py::overload_cast<const Box&>(&Geometry::periodicity, py::const_),
+ py::arg("b"),
  "Return Periodicity object with lengths determined by input Box"
-  )
+ )
 
  // .def("periodicShift", &Geometry::periodicShift)
- .def("growNonPeriodicDomain", py::overload_cast<IntVect const&>(&Geometry::growNonPeriodicDomain, py::const_))
- .def("growNonPeriodicDomain", py::overload_cast<int>(&Geometry::growNonPeriodicDomain, py::const_))
- .def("growPeriodicDomain", py::overload_cast<IntVect const&>(&Geometry::growPeriodicDomain, py::const_))
- .def("growPeriodicDomain", py::overload_cast<int>(&Geometry::growPeriodicDomain, py::const_))
-
- .def("setPeriodicity", &Geometry::setPeriodicity)
- .def("coarsen", &Geometry::coarsen)
- .def("refine", &Geometry::refine)
+ .def("growNonPeriodicDomain", py::overload_cast<IntVect const&>(&Geometry::growNonPeriodicDomain, py::const_),
+ py::arg("ngrow"))
+ .def("growNonPeriodicDomain", py::overload_cast<int>(&Geometry::growNonPeriodicDomain, py::const_),
+ py::arg("ngrow"))
+ .def("growPeriodicDomain", py::overload_cast<IntVect const&>(&Geometry::growPeriodicDomain, py::const_),
+ py::arg("ngrow"))
+ .def("growPeriodicDomain", py::overload_cast<int>(&Geometry::growPeriodicDomain, py::const_),
+ py::arg("ngrow"))
+
+ .def("setPeriodicity",
+ &Geometry::setPeriodicity,
+ py::arg("period"),
+ "Set periodicity flags and return the old flags.\n"
+ "Note that, unlike Periodicity class, the flags are just boolean."
+ )
+ .def("coarsen", &Geometry::coarsen, py::arg("rr"))
+ .def("refine", &Geometry::refine, py::arg("rr"))
  .def("outsideRoundOffDomain", py::overload_cast<AMREX_D_DECL(ParticleReal, ParticleReal, ParticleReal)>
- (&Geometry::outsideRoundoffDomain, py::const_),
+ (&Geometry::outsideRoundoffDomain, py::const_),
+ AMREX_D_DECL(py::arg("x"), py::arg("y"), py::arg("z")),
  "Returns true if a point is outside the roundoff domain. All particles with positions inside the roundoff domain are sure to be mapped to cells inside the Domain() box. Note that the same need not be true for all points inside ProbDomain()")
  .def("insideRoundOffDomain", py::overload_cast<AMREX_D_DECL(ParticleReal, ParticleReal, ParticleReal)>
- (&Geometry::insideRoundoffDomain, py::const_),
+ (&Geometry::insideRoundoffDomain, py::const_),
+ AMREX_D_DECL(py::arg("x"), py::arg("y"), py::arg("z")),
  "Returns true if a point is inside the roundoff domain. All particles with positions inside the roundoff domain are sure to be mapped to cells inside the Domain() box. Note that the same need not be true for all points inside ProbDomain()")
 
  // .def("computeRoundoffDomain")

tests/test_geometry.py

@@ -75,7 +75,7 @@ def test_probDomain(box, real_box):
  lo = [0, -1, 1]
  hi = [1, 0, 2]
  rb = amr.RealBox(lo, hi)
- gm.ProbDomain(rb)
+ gm.prob_domain = rb
  assert (
  np.isclose(gm.ProbLo(0), lo[0])
  and np.isclose(gm.ProbLo(1), lo[1])
@@ -105,8 +105,8 @@ def test_domain(box, real_box):
  gm.define(box, real_box, coord, is_periodic)
  assert gm.ok()
 
- gm.Domain(bx)
- assert gm.Domain().small_end == bx.small_end and gm.Domain().big_end == bx.big_end
+ gm.domain = bx
+ assert gm.domain.small_end == bx.small_end and gm.domain.big_end == bx.big_end
 
 
 @pytest.mark.skipif(amr.Config.spacedim != 3, reason="Requires AMREX_SPACEDIM = 3")
@@ -130,7 +130,7 @@ def test_periodic_queries(box, real_box):
 @pytest.mark.skipif(amr.Config.spacedim != 3, reason="Requires AMREX_SPACEDIM = 3")
 def test_periodicity(geometry):
  gm = geometry
- bx = gm.Domain()
+ bx = gm.domain
 
  for _non_periodic_coord in [0, 1]:
  error_thrown = False
@@ -166,8 +166,8 @@ def test_data(geometry, box, real_box):
  geometry_data = geometry.data()
  gd = geometry_data
 
- assert gd.domain.small_end == box.small_end == gd.Domain().small_end
- assert gd.domain.big_end == box.big_end == gd.Domain().big_end
+ assert gd.domain.small_end == box.small_end == gd.domain.small_end
+ assert gd.domain.big_end == box.big_end == gd.domain.big_end
 
  assert amr.AlmostEqual(gd.prob_domain, real_box)
  assert np.allclose(real_box.lo(), gd.prob_domain.lo())
@@ -219,14 +219,14 @@ def test_coarsen_refine(geometry):
  gmc = amr.Geometry(bx, rb, 1, [0, 0, 1])
  cv = amr.IntVect(2, 2, 1)
  gmc.coarsen(cv)
- assert gmc.Domain().small_end == amr.IntVect(-1, -1, -3)
- assert gmc.Domain().big_end == amr.IntVect(2, 2, 6)
+ assert gmc.domain.small_end == amr.IntVect(-1, -1, -3)
+ assert gmc.domain.big_end == amr.IntVect(2, 2, 6)
 
  gmr = amr.Geometry(bx, rb, 1, [0, 0, 1])
  rv = amr.IntVect(2, 2, 3)
  gmr.refine(rv)
- assert gmr.Domain().small_end == amr.IntVect(-2, -4, -9)
- assert gmr.Domain().big_end == amr.IntVect(9, 11, 20)
+ assert gmr.domain.small_end == amr.IntVect(-2, -4, -9)
+ assert gmr.domain.big_end == amr.IntVect(9, 11, 20)
 
 
 @pytest.mark.skipif(amr.Config.spacedim != 3, reason="Requires AMREX_SPACEDIM = 3")

tests/test_particleContainer.py

@@ -330,7 +330,7 @@ def test_per_cell(empty_particle_container, std_geometry, std_particle):
  real_arrays = pt.get_struct_of_arrays().get_real_data()
  sum_1 += np.sum(real_arrays[1])
  print(sum_1)
- ncells = std_geometry.Domain().numPts()
+ ncells = std_geometry.domain.numPts()
  print("ncells from box", ncells)
  print("NumberOfParticles", pc.number_of_particles_at_level(0))
  assert (