The author proposes a new package written in Python for the computation of incoming solar radiation and integrals thereof, based on standard  solutions for planetary motion and precession. The package is open source and licensed under the CeCILL free software licence agreement. Computation of insolation is fairly standard and already done in several other open source packages. Scientifically and computationally,  a particularly valuable contribution of this article lies in section 4 where the author proposes numerical and analytical procedures for the computation of the minimum and maximum of the insolation for the year. One particularly interesting outcome is displayed in Figure 5, showing that  in some realistic configurations equatorial insolation has only one and not two maxima. This could have some implications for the interpretation of the double-precession signal, which is relevant for cyclostratigraphic interpretations.  The idea of computing  insolation above a threshold by computing an elliptic integral betwen true solar longitudes that are first identifiied is elegant and welcome. 

# Lacking references 

Mention of existence of other, similar packages by other authors is only made once and very indirectly line 549: “while most of the routines available in 'astro.py' and 'insol.py', as described above, are available in several other software packages or languages"

These packages are never explicitly cited and the phrasing be read as casting doubt on their reliability: l. 10: “some people might not be aware of” ; l. 49 : “A frequent mistake” ; l. 204 : “as some people tend to believe”. 

 

In addition,the description of the incorrect procedure  (“add daily insolation at some different positions") could be made more explicit to avoid ambiguity. Indeed, the time integral of any quantity can be well approximated with the rectangle or trapeze rule, over equally spaced intervals in time. That is: $int_\lambda_1^\lambda_2 W(lambda(t)) dt$ is correct; One can also replace the increment by “dlamda * dt/dlambda$. By contrast, it would be incorrect to simply substitute $dlambda$ by $dt$. This is  certainly what the author implies. Note that neither palinsol nor, to my knowledge, DINSOL make this mistake. 

Reference to previous work is also lacking in the introduction of the elliptic integrals. Berger et al., 2010 introduces these equations (also reproduced in palinsol) and also introduces the history of their usage in the context of insolation calculations, citing works in German, e.g. Fempl. 

My recommendation here would be to provide a more extensive review of previous work, outlining the specific needs addressed by this new package and acknowledge what has already been done successfully; and  focus on the more specific contribution of identifying minima and maxima of daily insolation. 

# Incorrect definition of caloric insolation

The definition of caloric insolation provided by  Milanković (1941; 2002), in his paragraph 87, “the half year that comprises all the days of stronger radiation”, and therefore “experiences the greatest possible irradiation. The boundaries of this half-year are determined by solving a differential equation (his eq. 138), whose solution is used by Berger (1978) in his “Long-term variations of caloric insolation resulting from the earth's orbital elements”, and not in general time-centred on the solstices as implied by eq. l. 215. 

Admittedly, the definition of Milanković is slightly ambiguous, since he does not explicitly mention that the half-year is meant to be continuous, though his Figure 42 implies this. This is a subtlety that I realised while doing the present review, and lead me to conclude that the brute-force approach in palinsol is not applicable in the tropics (this will be corrected in a next version). Outside the tropics, I would consider that the computations of Berger (1978), and the brute-force approach in palinsol  are, in principle, closer to the intended definition than in the current contribution. 

# Minor remark on geocentric vs heliocentric

The words “geocentric” and “heliocentric” are swapped ll. 125-126. Indeed, the equation coming just after eq 1, $\sin\delta = \sin\varepsilon\sin\lambda$ emerges from the resolution of a spherical triangle on the celestial sphere (geocentric), with, thus $\delta$ positive when $\lambda$ is between 0 and $\pi$. $\lambda$ is in that case the true longitude of the Sun, and is 0 when the Sun is aligned with the first point of Aries.  $\varpi$ is, indeed, commonly supplied in e.g., Laskar, in heliocentric coordinates, thus $\varpi=0$ when the perihelion in reach in September. 

 

# Minor typographic / others

Use English quotes (") rather than guillemets(«).  l. 282 : for "a" generic planet. l. 265  : "sun hour angle" rather than "time-step". ; l. 252 : The sentence "This is a pity" is probably unnecessarily colloquial; yes analytical solutions need to be preferred to numerical approximations when necessary, however assuming convergence checks are made a numerical approximation is not necessarily inaccurate ; l. 640 : hyperbolic functions: use LaTeX straight characters (as for $\cos$, etc.).

Note that Eq.  A2a -> A3 have not been thoroughly checked. 

# References 

Berger A. (1978), Long-term variations of caloric insolation resulting from the earth's orbital elements, Quaternary Research, (9) 139 - 167 doi:10.1016/0033-5894(78)90064-9

Berger A., M. F. Loutre and Q. Yin (2010), Total irradiation during any time interval of the year using elliptic integrals, Quaternary Science Reviews, (29) 1968 - 1982 doi:10.1016/j.quascirev.2010.05.007

Crucifix, M. (2023). palinsol : a R package to compute Incoming Solar Radiation (insolation) for palaeoclimate studies (v1.0 (CRAN)). Zenodo. https://doi.org/10.5281/zenodo.14893715

Oliveira, E. D.: Daily INSOLation (DINSOL-v1.0): an intuitive tool for classrooms and specifying solar radiation boundary conditions, Geosci. Model Dev., 16, 2371–2390, https://doi.org/10.5194/gmd-16-2371-2023, 2023.