Skip to content

Commit bc3feae

Browse files
MartinPdeSMartinPdeS
committed
enhance docstring
1 parent b4cfc19 commit bc3feae

15 files changed

Lines changed: 779 additions & 61 deletions

File tree

‎PyMieSim/cpp/coordinates/interface.cpp‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -128,8 +128,9 @@ PYBIND11_MODULE(coordinates, module)
128128
;
129129

130130
pybind11::class_<VectorField>(module, "VectorField")
131-
.def_property_readonly("data",
132-
[](const VectorField& self) {
131+
.def_property_readonly(
132+
"data",
133+
[](const VectorField& self) {
133134
std::vector<size_t> shape = {self.sampling, 3};
134135
return _vector_to_numpy(self.data, shape);
135136
},
@@ -138,7 +139,8 @@ PYBIND11_MODULE(coordinates, module)
138139
This property provides access to the raw vector field data.
139140
)pbdoc"
140141
)
141-
.def("_cpp_get_scalar_product",
142+
.def(
143+
"get_scalar_product",
142144
&VectorField::get_scalar_product,
143145
pybind11::arg("base"),
144146
R"pbdoc(

‎PyMieSim/cpp/experiment/detector_set/interface.cpp‎

Lines changed: 69 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,13 +10,33 @@
1010
#include <experiment/utils.h>
1111

1212
#include <limits>
13+
#include <sstream>
1314

1415
namespace py = pybind11;
1516

1617

1718
PYBIND11_MODULE(detector_set, module) {
1819
py::object ureg = get_shared_ureg();
1920

21+
auto format_detector_set_repr = [](const std::string& name, const BaseDetectorSet& self) {
22+
std::ostringstream stream;
23+
stream << "<" << name
24+
<< " elements=" << self.total_combinations
25+
<< ", shape=(";
26+
27+
for (size_t index = 0; index < self.shape.size(); ++index) {
28+
if (index != 0) {
29+
stream << ", ";
30+
}
31+
32+
stream << self.shape[index];
33+
}
34+
35+
stream << "), sequential=" << (self.is_sequential ? "True" : "False")
36+
<< ">";
37+
return stream.str();
38+
};
39+
2040
py::class_<BaseDetectorSet, std::shared_ptr<BaseDetectorSet>>(
2141
module,
2242
"BaseDetectorSet",
@@ -28,7 +48,35 @@ PYBIND11_MODULE(detector_set, module) {
2848
detector geometry, angular sampling, optional polarization filtering,
2949
and the surrounding medium.
3050
)pdoc"
31-
);
51+
)
52+
.def_readonly(
53+
"is_sequential",
54+
&BaseDetectorSet::is_sequential,
55+
R"pdoc(
56+
Whether the set should be interpreted sequentially instead of as
57+
a full Cartesian product.
58+
)pdoc"
59+
)
60+
.def_readonly(
61+
"shape",
62+
&BaseDetectorSet::shape,
63+
R"pdoc(
64+
Length of each parameter axis contributing to the detector set.
65+
)pdoc"
66+
)
67+
.def_readonly(
68+
"total_combinations",
69+
&BaseDetectorSet::total_combinations,
70+
R"pdoc(
71+
Total number of detector configurations generated by the set.
72+
)pdoc"
73+
)
74+
.def(
75+
"__repr__",
76+
[format_detector_set_repr](const BaseDetectorSet& self) {
77+
return format_detector_set_repr("BaseDetectorSet", self);
78+
}
79+
);
3280

3381

3482
py::class_<PhotodiodeSet, BaseDetectorSet, std::shared_ptr<PhotodiodeSet>>(
@@ -111,6 +159,16 @@ PYBIND11_MODULE(detector_set, module) {
111159
Names of the detector parameters stored by ``PhotodiodeSet``.
112160
)pdoc"
113161
)
162+
.def(
163+
"__repr__",
164+
[format_detector_set_repr](const PhotodiodeSet& self) {
165+
return format_detector_set_repr("PhotodiodeSet", self);
166+
},
167+
R"pdoc(
168+
Return a concise representation showing the number of generated
169+
detector configurations and the set shape.
170+
)pdoc"
171+
)
114172
.def_readonly(
115173
"sampling",
116174
&PhotodiodeSet::sampling,
@@ -393,6 +451,16 @@ PYBIND11_MODULE(detector_set, module) {
393451
Names of the detector parameters stored by ``CoherentModeSet``.
394452
)pdoc"
395453
)
454+
.def(
455+
"__repr__",
456+
[format_detector_set_repr](const CoherentModeSet& self) {
457+
return format_detector_set_repr("CoherentModeSet", self);
458+
},
459+
R"pdoc(
460+
Return a concise representation showing the number of generated
461+
detector configurations and the set shape.
462+
)pdoc"
463+
)
396464
.def_readonly(
397465
"mean_coupling",
398466
&CoherentModeSet::mean_coupling,

‎PyMieSim/cpp/experiment/material_set/interface.cpp‎

Lines changed: 96 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
#include <pybind11/pybind11.h>
22
#include <pybind11/stl.h> // For binding std::vector and similar STL containers
3+
#include <sstream>
34
#include <pybind11/complex.h>
45

56
#include <pint/pint.h>
@@ -11,30 +12,115 @@ namespace py = pybind11;
1112
PYBIND11_MODULE(material_set, module) {
1213
py::object ureg = get_shared_ureg();
1314

14-
py::class_<MaterialSet, std::shared_ptr<MaterialSet>>(module, "MaterialSet")
15+
auto format_material_like_repr = [](const std::string& name, size_t size) {
16+
std::ostringstream stream;
17+
stream << "<" << name << " elements=" << size << ">";
18+
return stream.str();
19+
};
20+
21+
py::class_<MaterialSet, std::shared_ptr<MaterialSet>>(
22+
module,
23+
"MaterialSet",
24+
R"pdoc(
25+
Container of material definitions used by experiment scatterer and
26+
detector sets.
27+
28+
A ``MaterialSet`` behaves like a lightweight sequence of material
29+
objects or refractive index values converted to material objects.
30+
)pdoc"
31+
)
1532
.def(py::init<>())
16-
.def(py::init<const std::vector<std::shared_ptr<BaseMaterial>>&>())
17-
.def(py::init<const std::vector<std::complex<double>>&>())
18-
.def("__len__", [](const MaterialSet& self){return self.size();})
33+
.def(
34+
py::init<const std::vector<std::shared_ptr<BaseMaterial>>&>(),
35+
py::arg("materials"),
36+
R"pdoc(
37+
Initialize a material set from existing material objects.
38+
39+
Parameters
40+
----------
41+
materials : list[BaseMaterial]
42+
Material instances stored in the set.
43+
)pdoc"
44+
)
45+
.def(
46+
py::init<const std::vector<std::complex<double>>&>(),
47+
py::arg("refractive_indices"),
48+
R"pdoc(
49+
Initialize a material set from complex refractive index values.
50+
51+
Parameters
52+
----------
53+
refractive_indices : list[complex]
54+
Complex refractive indices converted into constant material
55+
objects.
56+
)pdoc"
57+
)
58+
.def("__len__", [](const MaterialSet& self){return self.size();}, "Return the number of stored materials.")
1959
.def("__getitem__", [](const MaterialSet& self, std::size_t index) {
2060
if (index >= self.size()) {
2161
throw py::index_error();
2262
}
2363
return self[index];
24-
})
64+
}, py::arg("index"), "Return the material at the given index.")
65+
.def(
66+
"__repr__",
67+
[format_material_like_repr](const MaterialSet& self) {
68+
return format_material_like_repr("MaterialSet", self.size());
69+
},
70+
"Return a compact representation showing the number of stored materials."
71+
)
2572
;
2673

27-
py::class_<MediumSet, std::shared_ptr<MediumSet>>(module, "MediumSet")
74+
py::class_<MediumSet, std::shared_ptr<MediumSet>>(
75+
module,
76+
"MediumSet",
77+
R"pdoc(
78+
Container of medium definitions used by experiment scatterer and
79+
detector sets.
80+
81+
A ``MediumSet`` behaves like a lightweight sequence of medium
82+
objects or refractive index values converted to medium objects.
83+
)pdoc"
84+
)
2885
.def(py::init<>())
29-
.def(py::init<const std::vector<std::shared_ptr<BaseMedium>>&>())
30-
.def(py::init<const std::vector<double>&>())
31-
.def("__len__", [](const MediumSet& self){return self.size();})
86+
.def(
87+
py::init<const std::vector<std::shared_ptr<BaseMedium>>&>(),
88+
py::arg("mediums"),
89+
R"pdoc(
90+
Initialize a medium set from existing medium objects.
91+
92+
Parameters
93+
----------
94+
mediums : list[BaseMedium]
95+
Medium instances stored in the set.
96+
)pdoc"
97+
)
98+
.def(
99+
py::init<const std::vector<double>&>(),
100+
py::arg("refractive_indices"),
101+
R"pdoc(
102+
Initialize a medium set from refractive index values.
103+
104+
Parameters
105+
----------
106+
refractive_indices : list[float]
107+
Refractive indices converted into constant medium objects.
108+
)pdoc"
109+
)
110+
.def("__len__", [](const MediumSet& self){return self.size();}, "Return the number of stored media.")
32111
.def("__getitem__", [](const MediumSet& self, std::size_t index) {
33112
if (index >= self.size()) {
34113
throw py::index_error();
35114
}
36115
return self[index];
37-
})
116+
}, py::arg("index"), "Return the medium at the given index.")
117+
.def(
118+
"__repr__",
119+
[format_material_like_repr](const MediumSet& self) {
120+
return format_material_like_repr("MediumSet", self.size());
121+
},
122+
"Return a compact representation showing the number of stored media."
123+
)
38124
;
39125
}
40126

‎PyMieSim/cpp/experiment/polarization_set/interface.cpp‎

Lines changed: 60 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,8 @@
22
#include <pybind11/stl.h> // For binding std::vector and similar STL containers
33
#include <complex> // For std::complex support
44

5+
#include <sstream>
6+
57
#include <pint/pint.h>
68
#include <utils/numpy_interface.h>
79
#include "./polarization_set.h"
@@ -13,7 +15,29 @@ namespace py = pybind11;
1315
PYBIND11_MODULE(polarization_set, module) {
1416
py::object ureg = get_shared_ureg();
1517

16-
py::class_<PolarizationSet, std::shared_ptr<PolarizationSet>>(module, "PolarizationSet")
18+
auto format_polarization_set_repr = [](const PolarizationSet& self) {
19+
std::ostringstream stream;
20+
stream << "<PolarizationSet states=" << self.number_of_states();
21+
22+
if (!self.angles.empty()) {
23+
stream << ", angles=" << self.angles.size();
24+
}
25+
26+
stream << ">";
27+
return stream.str();
28+
};
29+
30+
py::class_<PolarizationSet, std::shared_ptr<PolarizationSet>>(
31+
module,
32+
"PolarizationSet",
33+
R"pdoc(
34+
Ordered collection of polarization states.
35+
36+
A ``PolarizationSet`` can be created either from polarization angles
37+
or from Jones vectors. It is used throughout the experiment API to
38+
describe one or more analyzer or source polarization states.
39+
)pdoc"
40+
)
1741
.def(
1842
py::init<>(
1943
[](const py::object& angles) {
@@ -22,7 +46,15 @@ PYBIND11_MODULE(polarization_set, module) {
2246
return std::make_shared<PolarizationSet>(angles_value);
2347
}
2448
),
25-
py::arg("angles")
49+
py::arg("angles"),
50+
R"pdoc(
51+
Initialize a polarization set from one or more angles.
52+
53+
Parameters
54+
----------
55+
angles : Angle or array-like of Angle
56+
Polarization angles converted to radians internally.
57+
)pdoc"
2658
)
2759
.def(
2860
py::init<>(
@@ -31,15 +63,32 @@ PYBIND11_MODULE(polarization_set, module) {
3163
return std::make_shared<PolarizationSet>(angle_radian);
3264
}
3365
),
34-
py::arg("angles")
66+
py::arg("angles"),
67+
R"pdoc(
68+
Initialize a polarization set from a single angle quantity.
69+
70+
Parameters
71+
----------
72+
angles : Angle
73+
Single polarization angle converted to radians internally.
74+
)pdoc"
3575
)
3676
.def(
3777
py::init(
3878
[](const std::vector<std::vector<complex128>>& jones_vector) {
3979
return std::make_shared<PolarizationSet>(jones_vector);
4080
}
4181
),
42-
py::arg("jones_vectors")
82+
py::arg("jones_vectors"),
83+
R"pdoc(
84+
Initialize a polarization set from Jones vectors.
85+
86+
Parameters
87+
----------
88+
jones_vectors : list[list[complex]]
89+
Sequence of Jones vectors, each containing exactly two
90+
complex components.
91+
)pdoc"
4392
)
4493
.def(
4594
"__len__",
@@ -64,6 +113,13 @@ PYBIND11_MODULE(polarization_set, module) {
64113
py::keep_alive<0, 1>(), // Keep the PolarizationSet alive while the iterator is used
65114
"Returns an iterator over the polarization angles in the set."
66115
)
116+
.def(
117+
"__repr__",
118+
[format_polarization_set_repr](const PolarizationSet& self) {
119+
return format_polarization_set_repr(self);
120+
},
121+
"Return a compact representation showing the number of polarization states."
122+
)
67123
;
68124
}
69125

0 commit comments

Comments
 (0)