Climate modelling requires spending an extensive amount of time programming, which means reading, learning, testing, and evaluating source code. Fortunately, many climate models have been developed within the past decades, making it easier for climate studies to be conducted on a global scale. However, some climate models have millions of code lines, making the introduction of new parameterizations a laborious task that demands teamwork. While it is true that the high-complexity models perform realistic climate simulations, some researchers perform their studies using simplified climate models in the preliminary test phases. This realization motivated the development of Daily INSOLation (DINSOL-v1.0), a robust computer program to support the simplified climate models, performing solar radiation calculations while considering Milankovitch cycles and offering various simulation options for its users. DINSOL was intended to function as a program that supplies data (e.g. daily insolation, instantaneous solar radiation, orbital parameters of the Earth, and calendar dates), such as the Paleoclimate Modelling Intercomparison Project (PMIP). While preparing the boundary conditions of solar radiation for climate models, it was realized that the DINSOL model could also be a helpful tool for use in classrooms. Thus, it was decided that an intuitive graphical user interface would be required to cater to this educational purpose. The model was written in the Fortran 90 language, while its graphical user interface would be built using PyGTK, a Python application programming interface (API) based on GIMP ToolKit (GTK). Furthermore, the R language would also be used to generate a panel containing contour fields and sketches of the orbital parameters to support the graphical execution. The model evaluation made use of data from PMIP and other tools, and the data analysis was performed through statistical methods. Once all tests were concluded, an insignificant difference between the DINSOL-obtained results and the results obtained from other models validated the viability of DINSOL as a dependable tool.

In paleoclimatology, greenhouse gases (GHGs) and other climate features, such as air temperature, can be estimated using indirect methods (e.g. ice cores, speleothems, tree rings, lake and marine sediments, glacier fluctuations)

Presently, the Paleoclimate Modelling Intercomparison Project (PMIP) represents the best efforts of the scientific community in paleoclimate reconstructions. PMIP is in its fourth phase (PMIP4), with some studies ongoing and others already been published (e.g.

In recent years, useful tools to aid in calculating the EOPs and insolation were developed, tools like PALINSOL, an R package written by Michel Crucifix that adopts

Even though we have pre-existing programs to calculate the ISR following the Milankovitch cycle theory, they were developed to cater to different purposes and kinds of users. For instance, the PALINSOL package assumes that users already know how to program in the R language, which could be an obstacle for students at the beginner level. Thus, Earth Orbit v2.1 could be an alternative to get around the programming skill requirement as it can be executed using a user-friendly graphical user interface (GUI). Even still, it is expected that the Earth Orbit v2.1 users buy a MATLAB licence, which could be prohibitive to disadvantaged groups. Furthermore, none of these programs were idealized to be executed from only one command line or clique and, from that, prepare the boundary conditions of simplified climate models. Therefore, it would be helpful to have another software option that works similarly to the pre-existent tools, but, additionally, it should be free and not require any programming language skills to execute simple tasks, such as computing the daily insolation globally for a given year.

To achieve this goal, the Daily INSOLation (DINSOL-v1.0) program was developed, intended to be an intuitive and versatile tool ideal for paleoclimate simulations, such as those performed on PMIP, and still helpful for education purposes. From DINSOL, users can prepare solar radiation as a boundary condition for simplified climate models quickly and flexibly. Moreover, the DINSOL source code brings many comments, allowing advanced users to modify and adapt it more intuitively than other tools. For instance, introducing a new calendar option to compute the annual daily insolation for an exoplanet is a simple task. Still, a standard execution offers users various input choices to run their DINSOL simulations (e.g. year, solar constant, calendar, latitudinal and longitudinal number points). It also includes a GUI, with the GUI written in PyGTK, a Python program that adopts the GIMP ToolKit (GTK) library. Basically, the DINSOL source code is mostly a Fortran program because all its important processes (e.g. data reading, taking decisions, calculation, and writing results) were written using the Fortran 90 language. Besides PyGTK and Fortran 90, the model also contains some script templates written in the R language to assist its users in accessing computed solar radiation data. The program has a GNU GPL v3.0 licence, which allows users to modify, share, and improve it. For instance, DINSOL was adapted to prepare ISR data for an energy balance model used by

Ultimately, the following sections describe the program source code, giving a detailed explanation of the astronomical equations, ISR and EOP parameterizations, and input and output data. The “Model evaluation: a short statistical analysis” section adopts PMIP and other data sources as a reference.

This section details the astronomical fundamentals required to understand the DINSOL source code. The variables, constants, and mathematical relations are explained in the subsequent subsections.

The DINSOL model utilizes heliocentric coordinates, such as in

Heliocentrical coordinate sketch based on

Regarding Fig. 1, the Earth's obliquity representing the equatorial plane,

The DINSOL model implements the methodology from

Finally,

Figure 2 represents the annual variation in Earth–Sun distance,

Relative Earth–Sun distance,

The daily insolation algorithm used in

From

The astronomical event dates (seasons, perigee, and apogee) are functions of the changes in two orbital parameters: eccentricity and precession of equinoxes. Furthermore, it must be noted that DINSOL supports a 365 and 360 d calendar. Consequently, it must be considered that the vernal equinox (21 March) always occurs on the 80th day of a 365 d calendar and on the 81st day of a 360 d calendar. Thus, a modified version of Eq. (2) must be implemented assuming a simple calendar conversion (solar to Gregorian calendar), where estimation of the perihelion and aphelion dates is made using Eq. (4).

After obtaining

The DINSOL model has a subroutine that converts the day of the year to its correspondent month and day. Moreover, beyond perihelion and aphelion dates, the start date of a season can be determined. A fixed date for the spring equinox (21 March) must be assumed,

In

Sketch of the solar flux density

Therefore,

During simplified climate analysis, the global ISR average is

The incoming solar radiation as a parallel beam and its global average,

Although simplified climate approaches in zero-dimensional models are viable in classrooms, complex climate investigations require providing a realistic ISR. This way, the DINSOL model implements two different methods to calculate the ISR in the outer atmosphere. The first method is

To calculate the ISR, aspects of ISR incidence on spherical surfaces must be considered (e.g. solar zenith angle,

In Eq. (9) the constants for a given day are

Therefore, assuming that the angular speed of Earth is

Now, using

Prior to the initialization of the

The DINSOL model has a subroutine dedicated to calculating the instantaneous solar radiation,

Equation (20) is calculated using four nested loops (Fig. 5), where the first loop represents the passage of the days in a year,

An example of the loop employed to run the instantaneous solar radiation subroutine.

In the following, the hour angle,

Therefore, after calculating

The instantaneous solar radiation at the top of the atmosphere from the DINSOL model for the present day on 29 June.

The law of universal gravitation computes the mutual attraction force between two bodies, and, according to

Although Newton adopted the gravitational law for two celestial bodies with success (e.g. Sun–Earth, Earth–Moon, Sun–Mars), three-body problems proved to be more complex. Precise astronomical predictions require consideration of the gravitational influence of the other celestial bodies

Though complex astronomical motions cannot admit analytical solutions, a distinguished researcher overcame this obstacle by adopting the spectral decomposition technique. André Berger made it possible for anyone to estimate the Earth's orbital parameters (EOPs) within

Another remarkable researcher, Jacques Laskar, also simulated new long-term solutions for EOPs. Berger used the Laskar solutions in Be90

Thus, the efforts of André Berger and Jacques Laskar represent an important contribution to paleoclimatology. This way, following the idea of this section, the mathematical description of the Berger parameterizations, ranging from equations to constants, is provided, as well as a Laskar custom parameterization, such as in the DINSOL source code.

The constant values are used to solve the Berger parameterizations.

Both parameterizations, Be78 and Be90, use spectral analysis, which used the same trigonometrical equations. However, the Be78 and Be90 methods require distinctive data sources to work. Thus, DINSOL contains three tables for every Berger parameterization: obliquity, eccentricity, and precession, such as Tables 1, 4, and 5 in Be78, respectively. Furthermore, all these data tables were obtained from an R package named PALINSOL

The calculation of the obliquity (

If

The DINSOL model combines two Laskar time series solutions

Comparison between Be78 and Lask data with time (in years) on the horizontal axis. Additionally, graph

Next, Eq. (30) is shown, where

The annual change for each EOP is small, resulting in a small calculation error from the slope–interception equation. Additionally, comparing the Be78 and Lask data calculated from DINSOL, Fig. 7 shows that the graphs overlap; therefore, the Lask parameterization can accurately estimate the nonexistent original Laskar data. Both Laskar solutions were obtained from the web page

Fortran representation of the DINSOL source code, with subroutines, modules, namelist, input and output data, and brief explanations of the simulation steps.

The DINSOL source code has a simple hierarchical structure written in Fortran. A flow diagram representing the DINSOL source code is available in Fig. 8, including input data, the main program, modules, functions, subroutines, and output data. The model is initiated from the main program reading the input data: tables for analytical solutions of Be78 and Be90 and combined time series of Lask. The program also reads data from the namelist file (Table 2) as well as a module containing the declared variables and simulation parameters. In the next step, the program invokes the DINSOL subroutine, which is the main function and calls all other functions for the simulations.

The next steps are a series of commands executed from the namelist set-up function, where the calendar type must be initialized. Variables like spatial resolution, time interval, and calendar variables are then declared. The next step invokes parameterization to obtain the orbital parameters, and then the subroutines (seasons, perigee, and apogee) implement a calendar function to determine the day and month occurrences of summer, autumn, winter, the perihelion, and the aphelion. The solar longitude subroutine is then called and computes the annual true solar longitude for use in the daily insolation and instantaneous irradiance subroutines. Finally, the output subroutine is responsible for storing the data simulated during the DINSOL execution.

A short description of DINSOL namelist variables.

A short description of DINSOL output data.

The DINSOL model also works from a GUI, where the namelist options are the same, except for the spatial resolution, where the GUI mode offers only six options: 5, 4, 3, 2, 1, and 0.5

Snapshot of DINSOL-v1.0 GUI running on Windows 11.

Users have the option to customize their simulation set-up, implementing custom scenarios using a

This section evaluates the DINSOL program by comparing its products against data obtained from other similar tools or available in the literature. Still, the first subsection presents the Earth's orbital parameter (EOP) evaluation, where the Be78, Be90, and Lask parameterizations (Sect. 2.4) were evaluated. For that, we compared the Be78 parameterization with the Goddard Institute for Space Studies (GISS) data computed by

Time series of the Earth's orbital parameters (EOPs) for the last 150 kyr.

Evaluation of the DINSOL model adopting a statistical analysis from Earth's orbital parameters (EOPs), where the values are from the minima (Min), maxima (Max), average (

Over the following subsections, we analyse DINSOL compared to PMIPII and PALINSOL. At first, we evaluate the astronomical dates by using the PMIPII dates as a reference. Please note that the classical method of measuring the paleoclimate dates assumes the spring equinox to be a fixed date (21 March) and a constant month length regardless of the year. Still, in the final subsection, the evaluation of the monthly insolation data is conducted, where the assumption is that the solar constant is

The samples were analysed from measures of central tendency using average (

This table contains the dates of summer, autumn, winter, the perihelion, and the aphelion during present day (0 ka), the mid-Holocene (6 ka), and the Last Glacial Maximum (21 ka) calculated by DINSOL and by PMIPII, both using the method of Be78, for 365 and 360 d calendars.

In Fig. 10, there is a correlation between the GISS and DINSOL curves, indicating that DINSOL EOP subroutines (Be78, Be90, and Lask) function as expected. The error margin estimations were determined using a statistical summary shown in Table 4. Thus, measurements such as mean (

The GISS and Be78 values are nearly identical, which validates the Be78 subroutine. The same occurs with the Be90 and Lask parameterizations, where the test parameters indicate a roundoff error between DINSOL and PALINSOL. In addition, regarding the coefficient of variation,

DINSOL monthly insolation contour fields obtained from a 360 d calendar –

Monthly insolation differences between DINSOL and PMIPII from a 360 d calendar –

Although the parameterizations Be78, Be90, and Lask provide almost the same values, the users need to pay attention to the epoch and ecliptic reference used by each parameterization, that is, the time references, which are different from one another. For instance, while Be78 assumed 1950 to be the epoch and 1850 to be its ecliptic reference, the Lask parameterization adopted J2000 as a time reference, conforming to the Julian calendar. Therefore,

Contour fields of monthly insolation from Last Glacial Maximum minus present day:

Evaluation of the DINSOL model adopting a statistical analysis from monthly insolation data samples, where the data displayed represent the minimum values (Min), maximum values (Max), average (

Table 5 contains the dates of summer, autumn, winter, the perihelion, and the aphelion calculated by DINSOL and PMIPII, where both use the method of Be78. These dates represent present day (0 ka), the mid-Holocene (6 ka), and the Last Glacial Maximum (21 ka). Thus, perihelion and aphelion dates calculated by DINSOL are identical to those calculated by PMIPII. These dates correlate with the expected dates because they were determined using Eqs. (4), (5), and (6). Nevertheless, the summer, autumn, and winter dates have a small error compared to those determined by PMIPII. In DINSOL, these dates were estimated from a large number of values within the annual true solar longitude vector. In Table 5, an accumulative error is observed, where the season date error increases as a function of the distance to the spring equinox. The RMSE provides values around 12, 16, and 19 min for summer, autumn, and winter, respectively. Thus, for less than 20 min, the error remains small, meaning that DINSOL provides accurate date estimates. The compliance of DINSOL and PMIPII to the classical method of measuring astronomical events must always be considered. However, for a more realistic approach to paleoclimate calendars, it is recommended to follow the methodology of

The DINSOL monthly insolation was analysed from a visual evaluation of the contour fields (Figs. 11, 12, 13) and some statistical parameters (Table 6). This evaluation used PMIPII insolation samples prepared from 365 and 360 d calendars for three different periods: present day (0 ka), the mid-Holocene (6–0 ka), and the Last Glacial Maximum (21–0 ka). Simulations were thus performed with DINSOL using the same PMIPII set-up. Additionally, DINSOL was compared to the monthly insolation obtained from the PALINSOL package, but, in this case, we considered only the Last Glacial Maximum (21–0 ka) period. Incidentally, the contour fields present in Fig. 11a–c were generated using a 360 d calendar, with d–f employing a 365 d calendar set-up. From Fig. 11, compared to present day, the biggest insolation differences were found during the mid-Holocene, primarily due to the perihelion date changes, around 3 January for present day and 20 September during the mid-Holocene. This analysis of the mid-Holocene agrees with the presented discussion in

In order to perform the visual evaluation, we plotted the contour fields of DINSOL minus PMIPII (Fig. 12). Thus, in Fig. 12a–c, we have contour fields made from a 360 d calendar, whereas Fig. 12d–f is based on a 365 d calendar. Still, it is clear that for present day (0 ka), the mid-Holocene (6 ka), and the Last Glacial Maximum (21 ka), the differences are within the roundoff error, about

On the other hand, Fig. 12c and f show a systematic bias for high latitudes, where we can observe an almost harmonic behaviour between the Northern Hemisphere and Southern Hemisphere, which happens near the equinox dates. Despite that, the differences remain small, and as a confirmation test, we additionally decided to compare PMIPII (21–0 ka) to PALINSOL. Moreover, we also performed a DINSOL and PALINSOL comparison to the Last Glacial Maximum. Thus, Fig. 13a shows the same pattern at high latitudes, whereas Fig. 13b plots an almost uniform field. Therefore, DINSOL minus PALINSOL works as expected, suggesting that PMIPII (21–0 ka) contains some systematic roundoff error in the monthly insolation files, which should be reported to the PMIP team in order to investigate it.

With regard to the statistical analyses, the parameters available in Table 6 are dependable enough to confirm or reject our previous visual analyses from Figs. 11, 12, and 13. At first, we can see that the minima and maxima are nearly identical and converge towards the same value in the mid-Holocene. Furthermore, the central tendency indicates that all samples' average values are equal, while most median values are almost identical. The dispersion values also corroborate the previous conclusions, where the standard deviation and coefficient of variation suggest no significant differences. Still, in order to estimate the error between DINSOL and PMIPII samples, we also compute the RMSE. Table 6 shows that the highest value occurred from a calendar of 365 d when assaying present day,

As a final analysis, we focus on the Last Glacial Maximum, including the PALINSOL package as an alternative to the PMIPII samples. Thus, comparing PALINSOL and PMIPII, we realized that the RMSE was almost identical to the DINSOL and PMIPII values. However, evaluating DINSOL from PALINSOL, we got an RMSE of

The Daily INSOLation (DINSOL-v1.0) program is a robust and versatile tool offering various simulation options and usability. It is ideal to compute solar radiation data for climate models, which aids in simplified climate approaches or more complex studies. Furthermore, the DINSOL model may be employed as an educational tool by adopting its user-friendly GUI. The program was developed as a novel educational tool for use in geoscience colleges worldwide, providing a quick view of daily insolation by considering the Milankovitch cycles (ideal for paleoclimatology) or adopting hypothetical orbital parameters (ideal for exoplanets). Therefore, the program can aid students, teachers, and researchers in conducting their respective studies. Still, despite the program evaluation having presented insignificant differences compared to the literature, the users are incentivized to report any issues found during the program execution. Moreover, DINSOL is an open-source program whose author encourages users to develop the source code continuously. Ultimately, DINSOL may be considered a viable tool that accurately provides various types of output data, such as the Earth's orbital parameters; astronomical dates; daily insolation; and instantaneous solar radiation, simulating the passage of day to night realistically.

The output folder contains five scripts to aid users in analysing the simulation data. The files are listed with a brief description in Table A1.

Brief description of all scripts located in the DINSOL output folder.

DINSOL does not adopt restrictions for latitudinal and longitudinal number points during execution by command lines, which means that the high-resolution set-ups demand users' attention. This appendix brings a table containing the output file sizes for different simulation set-ups, where the instantaneous solar radiation file (

DINSOL short performance summary by considering the spatial resolution and time interval changes, where the computation was performed in the Ubuntu operating system using the IFORT 13 compiler. Thus, we have the required machine storage for each output file as well as the execution time.

The DINSOL program is available for download in different repositories: Zenodo, GitHub, and LabMet/UNIVASF. Further, even though the program is Linux/Unix software, a custom Windows OS version is available too. Both versions (Windows and Linux) contain manuals and README files to aid users in installing the dependencies and compiling the source code. On Zenodo, the Windows version is available at

The supplement related to this article is available online at:

EDO independently wrote all DINSOL source code, scripts, and manuals as well as this paper.

The author has declared that there are no competing interests.

Publisher’s note: Copernicus Publications remains neutral with regard to jurisdictional claims in published maps and institutional affiliations.

The author thanks Michel Crucifix, André Berger, and Jacques Laskar for providing the input data used in the DINSOL parameterizations. In addition, the author also thanks Patrick Bartlein for providing the time series of the Earth's orbital parameters; the Paleoclimate Modelling Intercomparison Project (PMIP) team for providing the monthly insolation data; and the PALINSOL author, whose package was crucial to perform a confirmation test. The author also thanks Kevin Schwarzwald and the referees for the valuable comments regarding the software and the article during the public discussion stage. Their suggestions and observations were fundamental to improving the article's quality. Moreover, the author is grateful to the topical editor Travis O'Brien and the whole journal editorial team. Finally, the author thanks the Federal University of Vale do São Francisco (UNIVASF) and the Laboratory of Meteorology (LabMet) for incentivizing the development of DINSOL-v1.0.

This paper was edited by Travis O'Brien and reviewed by two anonymous referees.