Skip to content

Commit 4c8d153

Browse files
jcurtis2jcurtis2
authored
Increase number of useful docstrings (#315)
1 parent 1c35768 commit 4c8d153

File tree

1 file changed

+45
-26
lines changed

1 file changed

+45
-26
lines changed

‎src/pypartmc.cpp‎

Lines changed: 45 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -80,12 +80,17 @@ PYBIND11_MODULE(_PyPartMC, m) {
8080
)pbdoc"
8181
)
8282
.def(py::init<const nlohmann::json&>())
83-
.def("spec_by_name", AeroData::spec_by_name)
84-
.def("__len__", AeroData::__len__)
85-
.def_property_readonly("n_source", AeroData::n_source)
86-
.def_property("frac_dim", &AeroData::get_frac_dim, &AeroData::set_frac_dim)
87-
.def_property("vol_fill_factor", &AeroData::get_vol_fill_factor, &AeroData::set_vol_fill_factor)
88-
.def_property("prime_radius", &AeroData::get_prime_radius, &AeroData::set_prime_radius)
83+
.def("spec_by_name", AeroData::spec_by_name,
84+
"Returns the number of the species in AeroData with the given name")
85+
.def("__len__", AeroData::__len__, "Number of aerosol species")
86+
.def_property_readonly("n_source", AeroData::n_source,
87+
"Number of aerosol sources")
88+
.def_property("frac_dim", &AeroData::get_frac_dim, &AeroData::set_frac_dim,
89+
"Volume fractal dimension (1)")
90+
.def_property("vol_fill_factor", &AeroData::get_vol_fill_factor,
91+
&AeroData::set_vol_fill_factor, "Volume filling factor (1)")
92+
.def_property("prime_radius", &AeroData::get_prime_radius, &AeroData::set_prime_radius,
93+
"Radius of primary particles (m)")
8994
.def_property_readonly("densities", &AeroData::densities,
9095
"Return array of aerosol species densities")
9196
.def("density", &AeroData::density, "Return density of an aerosol species")
@@ -110,7 +115,8 @@ PYBIND11_MODULE(_PyPartMC, m) {
110115
)pbdoc"
111116
)
112117
.def(py::init<std::shared_ptr<AeroData>, const std::valarray<double>&>())
113-
.def_property_readonly("volumes", AeroParticle::volumes)
118+
.def_property_readonly("volumes", AeroParticle::volumes,
119+
"Constituent species volumes (m^3)")
114120
.def_property_readonly("volume", AeroParticle::volume,
115121
"Total volume of the particle (m^3).")
116122
.def("species_volume",
@@ -191,7 +197,8 @@ PYBIND11_MODULE(_PyPartMC, m) {
191197
)pbdoc"
192198
)
193199
.def(py::init<std::shared_ptr<AeroData>, const double, const std::string>())
194-
.def("__len__", AeroState::__len__)
200+
.def("__len__", AeroState::__len__,
201+
"returns current number of particles")
195202
.def_property_readonly("total_num_conc", AeroState::total_num_conc,
196203
"returns the total number concentration of the population")
197204
.def_property_readonly("total_mass_conc", AeroState::total_mass_conc,
@@ -212,7 +219,7 @@ PYBIND11_MODULE(_PyPartMC, m) {
212219
.def("crit_rel_humids", AeroState::crit_rel_humids,
213220
"returns the critical relative humidity of each particle in the population")
214221
.def("mixing_state", AeroState::mixing_state,
215-
"returns the mixing state parameters (chi,d_alpha,d_gamma) of the population",
222+
"returns the mixing state parameters (d_alpha, d_gamma, chi) of the population",
216223
py::arg("include") = py::none(), py::arg("exclude") = py::none(),
217224
py::arg("group") = py::none())
218225
.def("bin_average_comp", AeroState::bin_average_comp,
@@ -239,7 +246,8 @@ PYBIND11_MODULE(_PyPartMC, m) {
239246
)pbdoc"
240247
)
241248
.def(py::init<const py::tuple&>())
242-
.def("__len__", GasData::__len__)
249+
.def("__len__", GasData::__len__,
250+
"returns number of gas species")
243251
.def_property_readonly("n_spec", GasData::__len__)
244252
.def("__str__", GasData::__str__,
245253
"returns a string with JSON representation of the object")
@@ -269,8 +277,10 @@ PYBIND11_MODULE(_PyPartMC, m) {
269277
"returns time since start_time (s).")
270278
.def_property_readonly("start_time", EnvState::get_start_time,
271279
"returns start time (s since 00:00 UTC on start_day)")
272-
.def_property("height", &EnvState::get_height, &EnvState::set_height)
273-
.def_property("pressure", &EnvState::get_pressure, &EnvState::set_pressure)
280+
.def_property("height", &EnvState::get_height, &EnvState::set_height,
281+
"Box height (m)")
282+
.def_property("pressure", &EnvState::get_pressure, &EnvState::set_pressure,
283+
"Ambient pressure (Pa)")
274284
;
275285

276286
py::class_<Photolysis>(m,
@@ -321,14 +331,17 @@ PYBIND11_MODULE(_PyPartMC, m) {
321331
"returns aero_emissions AeroDists at a given index")
322332
.def_property_readonly("aero_emissions_n_times", Scenario::get_emissions_n_times,
323333
"returns the number of times specified for emissions")
324-
.def_property_readonly("aero_emissions_rate_scale", Scenario::emission_rate_scale)
334+
.def_property_readonly("aero_emissions_rate_scale", Scenario::emission_rate_scale,
335+
"Aerosol emission rate scales at set-points (1)")
325336
.def_property_readonly("aero_emissions_time", Scenario::emission_time)
326337
.def("aero_background", Scenario::get_aero_background_dist,
327338
"returns aero_background AeroDists at a given index")
328339
.def_property_readonly("aero_dilution_n_times", Scenario::get_aero_dilution_n_times,
329340
"returns the number of times specified for dilution")
330-
.def_property_readonly("aero_dilution_rate", Scenario::aero_dilution_rate)
331-
.def_property_readonly("aero_dilution_time", Scenario::aero_dilution_time)
341+
.def_property_readonly("aero_dilution_rate", Scenario::aero_dilution_rate,
342+
"Aerosol-background dilution rates at set-points (s^{-1})")
343+
.def_property_readonly("aero_dilution_time", Scenario::aero_dilution_time,
344+
"Aerosol-background dilution set-point times (s)")
332345

333346
;
334347

@@ -352,8 +365,9 @@ PYBIND11_MODULE(_PyPartMC, m) {
352365
//.def("__setitem__", GasState::set_items)
353366
.def("__getitem__", GasState::get_item)
354367
//.def("__getitem__", GasState::get_items)
355-
.def("__len__", GasState::__len__)
356-
.def_property_readonly("n_spec", GasState::__len__)
368+
.def("__len__", GasState::__len__, "returns number of gas species")
369+
.def_property_readonly("n_spec", GasState::__len__,
370+
"returns number of gas species")
357371
.def("__str__", GasState::__str__,
358372
"returns a string with JSON representation of the object")
359373
.def("set_size", GasState::set_size,
@@ -375,7 +389,7 @@ PYBIND11_MODULE(_PyPartMC, m) {
375389

376390
py::class_<BinGrid>(m,"BinGrid")
377391
.def(py::init<const double, const py::str, const double, const double>())
378-
.def("__len__", BinGrid::__len__)
392+
.def("__len__", BinGrid::__len__, "returns number of bins")
379393
.def_property_readonly("edges", BinGrid::edges, "Bin edges")
380394
.def_property_readonly("centers", BinGrid::centers, "Bin centers")
381395
;
@@ -387,22 +401,27 @@ PYBIND11_MODULE(_PyPartMC, m) {
387401
.def("num_dist", &AeroMode::num_dist,
388402
"returns the binned number concenration of a mode")
389403
.def_property("vol_frac", &AeroMode::get_vol_frac,
390-
&AeroMode::set_vol_frac)
404+
&AeroMode::set_vol_frac, "Species fractions by volume")
391405
.def_property("vol_frac_std", &AeroMode::get_vol_frac_std,
392-
&AeroMode::set_vol_frac_std)
406+
&AeroMode::set_vol_frac_std, "Species fraction standard deviation")
393407
.def_property("char_radius", &AeroMode::get_char_radius,
394-
&AeroMode::set_char_radius)
408+
&AeroMode::set_char_radius,
409+
"Characteristic radius, with meaning dependent on mode type (m)")
395410
.def_property("gsd", &AeroMode::get_gsd,
396-
&AeroMode::set_gsd)
411+
&AeroMode::set_gsd, "Geometric standard deviation")
397412
.def("set_sample", &AeroMode::set_sampled)
398-
.def_property("type", &AeroMode::get_type, &AeroMode::set_type)
399-
.def_property("name", &AeroMode::get_name, &AeroMode::set_name)
413+
.def_property("type", &AeroMode::get_type, &AeroMode::set_type,
414+
"Mode type (given by module constants)")
415+
.def_property("name", &AeroMode::get_name, &AeroMode::set_name,
416+
"Mode name, used to track particle sources")
400417
;
401418

402419
py::class_<AeroDist>(m,"AeroDist")
403420
.def(py::init<std::shared_ptr<AeroData>, const nlohmann::json&>())
404-
.def_property_readonly("n_mode", &AeroDist::get_n_mode)
405-
.def_property_readonly("num_conc", &AeroDist::get_total_num_conc)
421+
.def_property_readonly("n_mode", &AeroDist::get_n_mode,
422+
"Number of aerosol modes")
423+
.def_property_readonly("num_conc", &AeroDist::get_total_num_conc,
424+
"Total number concentration of a distribution (#/m^3)")
406425
.def("mode", AeroDist::get_mode,
407426
"returns the mode of a given index")
408427
;

0 commit comments

Comments
 (0)