johnpye/grena/sunpos_grena.h

/*  ASCEND modelling environment
    Copyright (C) 2011 Carnegie Mellon University

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2, or (at your option)
    any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program.  If not, see <http://www.gnu.org/licenses/>.
*/

/* WARNING: this is a FIRST DRAFT of the code and HAS NOT BEEN CHECKED yet. */

/** @FILE
    Code reproduced with minor cosmetic changes from:
    R Grena (2008), An algorithm for the computation of the solar position,
    Solar Energy (82), pp 462-470.

    This header file contains the declaration of a class which includes all the
    input and output data, and the function that performs the calculation.

    To calculate the sun position, follow these steps:

    1. include this file.
    2. declare a variable of type SunCoord.
    3. Initialise the variable given the 9 input quantities required.
       This can be done in the declaration, listing the quantities between
       commas, or calling the function SetCoord(). In both cases, only the first
       four quantities are required; the others default to standard values
       (pressure = 1 atm, T = 20 ��C, 0 for all the other quantities) if omitted.
       Longitude and latitude must be given in RADIANS, pressure in ATM,
       temperature in ��C.
       Day, Month and Year are integer, UT in decimal hour from 0 to 24 (e.g.
       3:30 pm becomes 15.5).
    4. Call the Calculate() method of the SunCoord object.

    Example:
    (see the original publication)

    Warning: in order to improve accessibility and efficiency, there is not
    access control in the class. The user is free to directly access and
    modify all the data and there is not any control of consistency. Some
    caution in the use of the class is advisable.
*/
#ifndef SUNPOS_GRENA_H
#define SUNPOS_GRENA_H

#include <math.h>
#ifndef PI
# define PI 3.14159265358979
#endif

/**
    Structure to hold location data as well as desird time point.

    FIXME convert fields p, T to base SI units Pa and K.
*/
typedef struct SunPos_struct{
    // input data
    double t_G; ///< Julian Day, offset such that 0 = noon 1 Jan 2003.
    double Delta_t; ///< Difference between UT and Terrestrial Time, in seconds. Zero is probably OK here.
    double latitude; ///< Latitude (N = positive??), in RADIANS.
    double longitude; ///< Longitude (E = positive??), in RADIANS.
    double p; ///< Pressure, in ATM (used for refraction calculation)
    double T; ///< Temperature, in ��C (used for refraction calculation)
} SunPos;

// functions

/** Calculate time given the input date fields and store it in the SunPos object.
    @param UT fractional universal time (GMT) in hours from midnight (or fractional hours as required)
    @param Day Day of the month, starting at 1??
    @param Month Month of the year, starting at 1??
    @param Year Year, eg 2011.
    @param Delta_t Difference between UT and Terrestrial Time, in seconds.
*/
void SunPos_calc_time(SunPos *S, double UT, int Day, int Month, int Year, double Delta_t);

/** Set Julian Day time directly in days since noon 1 Jan 2003 UTC.
    @param t_G Julian Day (offset such that 0 = noon 1 Jan 2003 UTC)
    @param Delta_t @see SunPos_struct.
*/
void SunPos_set_time(SunPos *S, double t_G, double Delta_t);

/** Set location of observer on Earth
    @param latitude latitude in RADIANS!
    @param longitude longitude in RADIANS!
*/
void SunPos_set_lat_long(SunPos *S, double latitude, double longitude);

/** Set local atmospheric conditions
    @param p Pressure in ATM
    @param T Temperature in ��C
*/
void SunPos_set_press_temp(SunPos *S, double p, double T);

/**
    Calculate the sun position in local spherical coordinates.
    @param S sun position input data object (set using above functions)
    @param zenith zenith angle in radians (output)
    @param azimuth azimuth angle in radians (output)
*/
void SunPos_calc_zen_azi(SunPos *S, double *zenith, double *azimuth);

#endif /* SUNPOS_GRENA_H */

1	jpye	2470	/* ASCEND modelling environment
2			Copyright (C) 2011 Carnegie Mellon University
3	jpye	2469
4	jpye	2470	This program is free software; you can redistribute it and/or modify
5			it under the terms of the GNU General Public License as published by
6			the Free Software Foundation; either version 2, or (at your option)
7			any later version.
8
9			This program is distributed in the hope that it will be useful,
10			but WITHOUT ANY WARRANTY; without even the implied warranty of
11			MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12			GNU General Public License for more details.
13
14			You should have received a copy of the GNU General Public License
15	jpye	2649	along with this program. If not, see <http://www.gnu.org/licenses/>.
16	jpye	2470	*/
17
18	jpye	2469	/* WARNING: this is a FIRST DRAFT of the code and HAS NOT BEEN CHECKED yet. */
19
20			/** @FILE
21			Code reproduced with minor cosmetic changes from:
22	jpye	2649	R Grena (2008), An algorithm for the computation of the solar position,
23	jpye	2469	Solar Energy (82), pp 462-470.
24
25			This header file contains the declaration of a class which includes all the
26			input and output data, and the function that performs the calculation.
27
28			To calculate the sun position, follow these steps:
29
30			1. include this file.
31			2. declare a variable of type SunCoord.
32			3. Initialise the variable given the 9 input quantities required.
33	jpye	2649	This can be done in the declaration, listing the quantities between
34	jpye	2469	commas, or calling the function SetCoord(). In both cases, only the first
35			four quantities are required; the others default to standard values
36			(pressure = 1 atm, T = 20 ��C, 0 for all the other quantities) if omitted.
37			Longitude and latitude must be given in RADIANS, pressure in ATM,
38			temperature in ��C.
39			Day, Month and Year are integer, UT in decimal hour from 0 to 24 (e.g.
40			3:30 pm becomes 15.5).
41			4. Call the Calculate() method of the SunCoord object.
42
43			Example:
44			(see the original publication)
45
46	jpye	2649	Warning: in order to improve accessibility and efficiency, there is not
47			access control in the class. The user is free to directly access and
48	jpye	2469	modify all the data and there is not any control of consistency. Some
49			caution in the use of the class is advisable.
50			*/
51			#ifndef SUNPOS_GRENA_H
52			#define SUNPOS_GRENA_H
53
54	jpye	2471	#include <math.h>
55	jpye	2469	#ifndef PI
56			# define PI 3.14159265358979
57			#endif
58
59	jpye	2470	/**
60	jpye	2473	Structure to hold location data as well as desird time point.
61	jpye	2469
62	jpye	2470	FIXME convert fields p, T to base SI units Pa and K.
63			*/
64			typedef struct SunPos_struct{
65	jpye	2469	// input data
66	jpye	2471	double t_G; ///< Julian Day, offset such that 0 = noon 1 Jan 2003.
67			double Delta_t; ///< Difference between UT and Terrestrial Time, in seconds. Zero is probably OK here.
68	jpye	2470	double latitude; ///< Latitude (N = positive??), in RADIANS.
69			double longitude; ///< Longitude (E = positive??), in RADIANS.
70			double p; ///< Pressure, in ATM (used for refraction calculation)
71			double T; ///< Temperature, in ��C (used for refraction calculation)
72			} SunPos;
73	jpye	2469
74	jpye	2470	// functions
75	jpye	2469
76	jpye	2470	/** Calculate time given the input date fields and store it in the SunPos object.
77			@param UT fractional universal time (GMT) in hours from midnight (or fractional hours as required)
78			@param Day Day of the month, starting at 1??
79			@param Month Month of the year, starting at 1??
80			@param Year Year, eg 2011.
81			@param Delta_t Difference between UT and Terrestrial Time, in seconds.
82			*/
83			void SunPos_calc_time(SunPos *S, double UT, int Day, int Month, int Year, double Delta_t);
84	jpye	2469
85	jpye	2649	/** Set Julian Day time directly in days since noon 1 Jan 2003 UTC.
86	jpye	2471	@param t_G Julian Day (offset such that 0 = noon 1 Jan 2003 UTC)
87			@param Delta_t @see SunPos_struct.
88			*/
89			void SunPos_set_time(SunPos *S, double t_G, double Delta_t);
90	jpye	2469
91	jpye	2470	/** Set location of observer on Earth
92			@param latitude latitude in RADIANS!
93			@param longitude longitude in RADIANS!
94			*/
95			void SunPos_set_lat_long(SunPos *S, double latitude, double longitude);
96	jpye	2469
97	jpye	2649	/** Set local atmospheric conditions
98	jpye	2470	@param p Pressure in ATM
99			@param T Temperature in ��C
100			*/
101	jpye	2472	void SunPos_set_press_temp(SunPos *S, double p, double T);
102	jpye	2469
103	jpye	2470	/**
104			Calculate the sun position in local spherical coordinates.
105			@param S sun position input data object (set using above functions)
106			@param zenith zenith angle in radians (output)
107			@param azimuth azimuth angle in radians (output)
108			*/
109			void SunPos_calc_zen_azi(SunPos S, double zenith, double *azimuth);
110	jpye	2469
111	jpye	2471	#endif /* SUNPOS_GRENA_H */
112