Library API
The Meteonorm header file defines its Library API, which is as follows:
/**
* @file meteonorm.h
* @brief Meteonorm C API Header File
*
* Provides functions and data structures for accessing Meteonorm weather data and performing computations.
*
* Copyright (c) Meteotest AG
*/
#ifndef METEONORM_H
#define METEONORM_H
#include <stdbool.h>
#include <stdint.h>
#include <stdlib.h>
/**
* @def MN_EXPORT
* @brief Macro for exporting functions from the Meteonorm library.
*
* On Windows platforms, it resolves to `__declspec(dllexport)` to handle DLL exports.
* On other platforms, it expands to nothing.
*/
#if defined(_WIN32) || defined(_WIN64)
#define MN_EXPORT __declspec(dllexport)
#else
#define MN_EXPORT
#endif
#ifdef __cplusplus
extern "C" {
#endif
/* Enum definitions */
/**
* @enum mn_situation
* @brief Enumerates different environmental situations for Meteonorm computations.
*
* This enumeration defines various site situations that affect weather data interpolation and generation.
*/
typedef enum mn_situation {
MN_SITUATION_OPEN = 0,
MN_SITUATION_DEPRESSION = 1,
MN_SITUATION_COLD_AIR_LAKE = 2,
MN_SITUATION_SEA_LAKE = 3,
MN_SITUATION_CITY = 4,
MN_SITUATION_SLOPE_SOUTH = 5,
MN_SITUATION_SLOPE_WEST_EAST = 6,
MN_SITUATION_VALLEY = 7,
MN_SITUATION_VALLEY_FOEHN = 8,
MN_SITUATION_VALLEY_CENTRAL_ALPS = 9,
MN_SITUATION_VALLEY_ALPINE_FOOTHILLS = 10,
MN_SITUATION_VALLEY_SLOPE_SOUTH = 11,
MN_SITUATION_VALLEY_SLOPE_WEST_EAST = 12,
MN_SITUATION_SUMMIT = 13
} mn_situation;
/**
* @enum mn_status
* @brief Enumerates status codes returned by Meteonorm functions.
*
* Status codes indicate success or specific error conditions.
*/
typedef enum mn_status {
MN_STATUS_OK = 0,
MN_STATUS_INTERNAL_ERROR = 1,
MN_STATUS_NOT_INITIALIZED = 2,
MN_STATUS_INITIALIZATION_FAILED = 3,
MN_STATUS_COMPUTATION_FAILED = 4,
MN_STATUS_INPUT_UNDEFINED = 5,
MN_STATUS_INPUT_INVALID = 6,
MN_STATUS_VALUES_UNDEFINED = 7,
MN_STATUS_VALUES_INVALID = 8,
MN_STATUS_LATITUDE_UNDEFINED = 9,
MN_STATUS_LATITUDE_OUT_OF_RANGE = 10,
MN_STATUS_LONGITUDE_UNDEFINED = 11,
MN_STATUS_LONGITUDE_OUT_OF_RANGE = 12,
MN_STATUS_ALTITUDE_OUT_OF_RANGE = 13,
MN_STATUS_TIME_ZONE_INVALID = 14,
MN_STATUS_AZIMUTH_OUT_OF_RANGE = 15,
MN_STATUS_TILT_OUT_OF_RANGE = 16,
MN_STATUS_SEED_OUT_OF_RANGE = 17,
MN_STATUS_WMO_STATION_NOT_FOUND = 18,
MN_STATUS_HORIZON_OUT_OF_RANGE = 19,
} mn_status;
/**
* @enum mn_scenario
* @brief Enumerates RCP climate change scenarios.
*
* Defines the category of climate model projections used in the Meteonorm computation, representing different
* IPCC scenarios based on various Shared Socioeconomic Pathways (SSPs).
*/
typedef enum mn_scenario {
MN_SCENARIO_NONE = 0,
MN_SCENARIO_SSP1_26 = 1,
MN_SCENARIO_SSP2_45 = 2,
MN_SCENARIO_SSP3_70 = 3
} mn_scenario;
/**
* @enum mn_frequency
* @brief Enumerates available target frequencies for Meteonorm computations.
*
* Defines the time resolution for the computed time series.
*/
typedef enum mn_frequency { MN_FREQUENCY_1_HOUR = 0, MN_FREQUENCY_1_MINUTE = 1 } mn_frequency;
/* Struct definitions */
/**
* @struct mn_error
* @brief Structure representing an error with status code and message.
*/
typedef struct mn_error {
mn_status status;
char message[2000];
} mn_error;
/**
* @struct mn_version
* @brief Structure containing version information of the Meteonorm library.
*/
typedef struct mn_version {
char commit[100];
char build_date[100];
} mn_version;
/**
* @struct mn_wmo_station
* @brief Structure defining a WMO station with latitude, longitude, and name.
*/
typedef struct mn_wmo_station {
mn_error error;
double latitude;
double longitude;
char name[100];
} mn_wmo_station;
/**
* @struct mn_time_zone
* @brief Structure representing a time zone offset from UTC.
*/
typedef struct mn_time_zone {
mn_error error;
double offset;
} mn_time_zone;
/**
* @struct mn_altitude
* @brief Structure representing an altitude value in meters.
*/
typedef struct mn_altitude {
mn_error error;
double elevation;
} mn_altitude;
/**
* @struct mn_horizon
* @brief Structure representing a horizon line in 360 directions.
*/
typedef struct mn_horizon {
mn_error error;
double horizon[360];
} mn_horizon;
/**
* @struct mn_values
* @brief Structure representing an array of float values.
*/
typedef struct mn_values {
size_t n;
float *values;
} mn_values;
/**
* @struct mn_ipcc
* @brief Structure defining the IPCC scenario and target year for climate projections.
*/
typedef struct mn_ipcc {
int32_t year;
mn_scenario scenario;
} mn_ipcc;
/**
* @struct mn_input
* @brief Opaque structure representing the input parameters for Meteonorm computations.
*
* Use the provided functions to create and manipulate this structure.
*/
typedef struct mn_input mn_input;
/**
* @typedef mn_time
* @brief Represents time in seconds since the Unix epoch (January 1, 1970, 00:00:00 UTC).
*/
typedef int64_t mn_time;
/**
* @struct mn_result
* @brief Structure containing computation results.
*
* The mn_values attributes cover a full year, with the first value corresponding to January 1, 01:00 (local time)
* for hourly resolution and 00:01 for minute resolution.
* Note that time steps are "right aligned", e.g., 01:00 (for hourly resolution) covers the interval between
* 00:00 and 01:00.
*/
typedef struct mn_result {
mn_error error; // Error code indicating success or failure
double time_zone; // Local time zone offset from UTC in hours
double altitude; // Altitude of the location in meters
double horizon[360]; // Horizon elevation angles [°] at each azimuth angle (0-359°)
mn_frequency frequency; // Frequency of the time series (e.g., hourly, minute)
// Irradiance values (all pointers to time series data)
mn_values *global_horizontal_irradiance; // Global horizontal irradiance [W/m²]
mn_values *global_horizontal_irradiance_with_shading; // Global horizontal irradiance with shading taken into account [W/m²]
mn_values *diffuse_horizontal_irradiance; // Diffuse horizontal irradiance [W/m²]
mn_values *diffuse_horizontal_irradiance_with_shading; // Diffuse horizontal irradiance with shading taken into account [W/m²]
mn_values *direct_horizontal_irradiance; // Direct horizontal irradiance [W/m²]
mn_values *direct_horizontal_irradiance_with_shading; // Direct horizontal irradiance with shading taken into account [W/m²]
mn_values *direct_normal_irradiance; // Direct normal irradiance [W/m²]
mn_values *direct_normal_irradiance_with_shading; // Direct normal irradiance with shading taken into account [W/m²]
mn_values *global_tilted_irradiance; // Global tilted irradiance [W/m²]
mn_values *global_tilted_irradiance_with_shading; // Global tilted irradiance with shading taken into account [W/m²]
mn_values *direct_tilted_irradiance; // Direct tilted irradiance [W/m²]
mn_values *direct_tilted_irradiance_with_shading; // Direct tilted irradiance with shading taken into account [W/m²]
mn_values *diffuse_tilted_irradiance; // Diffuse tilted irradiance [W/m²]
mn_values *diffuse_tilted_irradiance_with_shading; // Diffuse tilted irradiance with shading taken into account [W/m²]
mn_values *pv_production; // Photovoltaic production estimate [Wh/kWp]
mn_values *pv_production_with_shading; // Photovoltaic production estimate accounting for shading [Wh/kWp]
mn_values *global_extraterrestrial_irradiance; // Irradiance at the top of the Earth's atmosphere [W/m²]
mn_values *global_clear_sky_irradiance; // Global horizontal irradiance under cloud-free conditions [W/m²]
mn_values *downwelling_longwave_irradiance; // Longwave irradiance incident on a horizontal surface from
// the sky (wavelength > 3µm) [W/m²]
// Meteorological parameters
mn_values *temperature; // Air temperature (2m above ground) [°C]
mn_values *dew_point_temperature; // Dew point temperature [°C]
mn_values *wet_bulb_temperature; // Wet-bulb temperature [°C]
mn_values *surface_temperature; // Surface temperature (representative for 5cm above grass surface) [°C]
mn_values *relative_humidity; // Relative humidity [%]
mn_values *wind_speed; // Wind speed [m/s]
mn_values *wind_direction; // Wind direction [°] (North = 0°, East = 90°, South = 180°, West = 270°)
mn_values *linke_turbidity_factor; // Linke turbidity factor [1]
mn_values *precipitation; // Precipitation [mm]
mn_values *pressure; // Atmospheric pressure [hPa]
mn_values *solar_azimuth; // Solar azimuth angle [°] (North = 0°, East = 90°, South = 180°, West = 270°)
mn_values *solar_elevation; // Solar elevation angle [°]
mn_values *albedo; // Ground albedo (fraction of incoming solar radiation reflected) [1]
mn_values *cloud_cover; // Cloud cover fraction [Okta]
mn_values *photo_active_irradiance; // Photosynthetically active radiation (PAR) [W/m²]
mn_values *snow_depth; // Snow depth [mm]
mn_values *mixing_ratio; // Water vapor mixing ratio [g/kg]
// Meta data
int32_t start_year_of_irradiance_period_of_nearest_station; // Start year of irradiance measurement period at nearest station
int32_t end_year_of_irradiance_period_of_nearest_station; // End year of irradiance measurement period at nearest station
double irradiance_station_data_weight; // Weight of station data in irradiance climatology estimation [%]
double uncertainty_of_irradiance_estimation; // Estimated uncertainty of irradiance [W/m²]
double uncertainty_of_temperature_estimation; // Estimated uncertainty of temperature [°]
double irradiance_year_to_year_variability; // Year-to-year variability of irradiance [W/m²]
int32_t irradiance_yearly_poe10; // Yearly mean irradiance expected to be exceeded in 10% of the years [W/m²]
int32_t irradiance_yearly_poe90; // Yearly mean irradiance expected to be exceeded in 90% of the years [W/m²]
} mn_result;
/**
* @brief Creates an mn_time value from the provided date and time components.
*
* Meteonorm input and results use mn_time for timestamps.
*
* @param year Year component (e.g., 2023).
* @param month Month component [1-12].
* @param day Day component [1-31].
* @param hour Hour component [0-23].
* @param minute Minute component [0-59].
* @param time_zone_offset_hours Time zone offset from UTC in hours. See mn_input_set_time_zone for valid values.
* @return mn_time value representing the specified time, or (mn_time)-1 if invalid.
*/
MN_EXPORT mn_time mn_time_new(int32_t year, int32_t month, int32_t day, int32_t hour, int32_t minute,
double time_zone_offset_hours);
/**
* @brief Checks if a given time zone offset is valid for Meteonorm computations.
*
* @param time_zone Time zone offset in hours.
* @return true if the time zone is valid, false otherwise.
*/
MN_EXPORT bool mn_time_zone_is_valid(double time_zone);
/**
* @brief Creates a new mn_values structure from an array of float values.
*
* The input array is copied into the new structure.
* **Important:** There is no corresponding `mn_values_free` function. The values struct is freed when the input struct
* is freed with `mn_input_free`.
*
* @param values Array of float values.
* @param size Number of elements in the array.
* @return Pointer to a newly allocated mn_values struct.
*/
MN_EXPORT mn_values *mn_values_new(const float *values, size_t size);
/**
* @brief Creates a new input structure for Meteonorm computations.
*
* The fields are initialized to default values.
* Free after use by calling `mn_input_free`.
*
* @return Pointer to a newly allocated mn_input struct.
*/
MN_EXPORT mn_input *mn_input_new();
/**
* @brief Frees an input structure, including imported monthly values and horizon (if set).
*
* @param input Input struct to free.
*/
MN_EXPORT void mn_input_free(mn_input *input);
/** Helper functions for setting the input fields */
/**
* @brief Sets the latitude in the input structure.
*
* This is a required parameter.
*
* @param input Pointer to the mn_input struct.
* @param latitude Latitude in degrees, must be in the range [-90, 90].
* @return MN_STATUS_OK if the latitude was set successfully, or an error code otherwise.
*/
MN_EXPORT mn_status mn_input_set_latitude(mn_input *input, double latitude);
/**
* @brief Sets the longitude in the input structure.
*
* This is a required parameter.
*
* @param input Pointer to the mn_input struct.
* @param longitude Longitude in degrees, must be in the range [-180, 180].
* @return MN_STATUS_OK if the longitude was set successfully, or an error code otherwise.
*/
MN_EXPORT mn_status mn_input_set_longitude(mn_input *input, double longitude);
/**
* @brief Sets the desired output frequency in the input struct.
*
* This is optional. If not set, the default frequency is hourly.
*
* @param input Pointer to the mn_input struct.
* @param frequency Desired frequency of the computations (0: hourly, 1: minute).
* @return MN_STATUS_OK if the frequency was set successfully, or an error code otherwise.
*/
MN_EXPORT mn_status mn_input_set_frequency(mn_input *input, mn_frequency frequency);
/**
* @brief Sets the altitude in the input structure.
*
* This is optional. If not set, Meteonorm determines the altitude from the location.
*
* @param input Pointer to the mn_input struct.
* @param altitude Altitude in meters, must be in the range [-500, 10000].
* @return MN_STATUS_OK if the altitude was set successfully, or an error code otherwise.
*/
MN_EXPORT mn_status mn_input_set_altitude(mn_input *input, double altitude);
/**
* @brief Sets the horizon in the input structure.
*
* This is optional. If not set, Meteonorm determines the horizon from the location.
* **Note:** The input struct takes ownership of the passed `mn_values` and will free it when `mn_input_free` is
* called. Do not free it manually.
*
* @param input Pointer to the mn_input struct.
* @param horizon Horizon line. Pointer to mn_values containing 360 values representing
elevation angles (in degrees) of the horizon in 360 directions.
Elevation angles must be ≥0° and <90°.
Index corresponds to azimuth:
Index 0 = 0° (North)
Index 90 = 90° (East)
Index 180 = 180° (South)
Index 270 = 270° (West)
* @return MN_STATUS_OK if the horizon was set successfully, or an error code otherwise.
*/
MN_EXPORT mn_status mn_input_set_horizon(mn_input *input, mn_values *horizon);
/**
* @brief Sets a flat horizon in the input structure (i.e., an elevation of 0° for all 360 directions).
*
* @param input Pointer to the mn_input struct.
* @return MN_STATUS_OK if the horizon was set successfully, or an error code otherwise.
*/
MN_EXPORT mn_status mn_input_set_horizon_flat(mn_input *input);
/**
* @brief Sets the time zone in the input structure.
*
* This is optional. If not set, Meteonorm determines the time zone from the location.
*
* @param input Pointer to the mn_input struct.
* @param time_zone Time zone offset from UTC in hours. Valid values include:
* [-12.0, -11.0, -10.0, -9.5, -9.0, -8.0, -7.0, -6.0, -5.0, -4.5, -4.0, -3.5, -3.0,
* -2.0, -1.0, 0.0, 1.0, 2.0, 3.0, 3.5, 4.0, 4.5, 5.0, 5.5, 5.75, 6.0, 6.5, 7.0, 8.0,
* 8.75, 9.0, 9.5, 10.0, 10.5, 11.0, 11.5, 12.0, 12.75, 13.0, 14.0].
* @return MN_STATUS_OK if the time zone was set successfully, or an error code otherwise.
*/
MN_EXPORT mn_status mn_input_set_time_zone(mn_input *input, double time_zone);
/**
* @brief Sets the situation in the input structure.
*
* This is optional. If not set, Meteonorm uses the default situation (open).
*
* @param input Pointer to the mn_input struct.
* @param situation The mn_situation value representing the site situation.
* @return MN_STATUS_OK if the situation was set successfully, or an error code otherwise.
*/
MN_EXPORT mn_status mn_input_set_situation(mn_input *input, mn_situation situation);
/**
* @brief Sets the surface azimuth in the input structure.
*
* This is optional. If not set, Meteonorm uses the default surface azimuth (0.0).
*
* @param input Pointer to the mn_input struct.
* @param azimuth Surface azimuth in degrees, must be in the range [0, 360]. 0°=north,
* 90°=east, 180°=south, 270°=west, and 360°=north.
* @return MN_STATUS_OK if the surface azimuth was set successfully, or an error code otherwise.
*/
MN_EXPORT mn_status mn_input_set_surface_azimuth(mn_input *input, double azimuth);
/**
* @brief Sets the surface tilt in the input structure.
*
* This is optional. If not set, Meteonorm uses the default surface tilt (0.0).
*
* @param input Pointer to the mn_input struct.
* @param tilt Surface tilt in degrees, must be in the range [0, 90].
* @return MN_STATUS_OK if the tilt was set successfully, or an error code otherwise.
*/
MN_EXPORT mn_status mn_input_set_surface_tilt(mn_input *input, double tilt);
/**
* @brief Sets the random seed in the input structure.
*
* This is optional. If not set, Meteonorm uses the default random seed (0).
*
* @param input Pointer to the mn_input struct.
* @param random_seed Random seed value, must be in the range [0, 99].
* @return MN_STATUS_OK if the random seed was set successfully, or an error code otherwise.
*/
MN_EXPORT mn_status mn_input_set_random_seed(mn_input *input, int32_t random_seed);
/**
* @brief Sets the IPCC scenario in the input structure.
*
* This is optional. If not set, Meteonorm does not use an IPCC scenario.
*
* @param input Pointer to the mn_input struct.
* @param ipcc_scenario The mn_ipcc struct defining the scenario and year.
* @return MN_STATUS_OK if the IPCC scenario was set successfully, or an error code otherwise.
*/
MN_EXPORT mn_status mn_input_set_ipcc_scenario(mn_input *input, mn_ipcc scenario);
/**
* @brief Sets the global horizontal irradiance values for imported monthly data.
*
* This is an optional parameter.
*
* **Note:** The input struct takes ownership of the passed `mn_values` and will free it when `mn_input_free` is called.
* Do not free it manually.
*
* **Important**: currently, only 12 months of data are supported. If you supply more than 12 months, only the first 12
* will be used. If you provide fewer than 12 months, the function will return an error.
*
* @param input Pointer to the mn_input struct.
* @param values Pointer to mn_values containing monthly global horizontal irradiance values [W/m²].
* @return MN_STATUS_OK if the values were set successfully, or an error code otherwise.
*/
MN_EXPORT mn_status mn_input_set_imported_monthly_global_horizontal_irradiance(mn_input *input, mn_values *values);
/**
* @brief Sets the temperature values for imported monthly data.
*
* This is an optional parameter.
*
* **Note:** The input struct takes ownership of the passed `mn_values` and will free it when `mn_input_free` is called.
* Do not free it manually.
*
* **Important**: currently, only 12 months of data are supported. If you supply more than 12 months, only the first 12
* will be used. If you provide fewer than 12 months, the function will return an error.
*
* @param input Pointer to the mn_input struct.
* @param values Pointer to mn_values containing monthly temperature values [°C].
* @return MN_STATUS_OK if the values were set successfully, or an error code otherwise.
*/
MN_EXPORT mn_status mn_input_set_imported_monthly_temperature(mn_input *input, mn_values *values);
/**
* @brief Sets the wind speed values for imported monthly data.
*
* This is an optional parameter.
*
* **Note:** The input struct takes ownership of the passed `mn_values` and will free it when `mn_input_free` is called.
* Do not free it manually.
*
* **Important**: currently, only 12 months of data are supported. If you supply more than 12 months, only the first 12
* will be used. If you provide fewer than 12 months, the function will return an error.
*
* @param input Pointer to the mn_input struct.
* @param values Pointer to mn_values containing monthly wind speed values [m/s].
* @return MN_STATUS_OK if the values were set successfully, or an error code otherwise.
*/
MN_EXPORT mn_status mn_input_set_imported_monthly_wind_speed(mn_input *input, mn_values *values);
/**
* @brief Sets the dew point temperature values for imported monthly data.
*
* This is an optional parameter.
*
* **Note:** The input struct takes ownership of the passed `mn_values` and will free it when `mn_input_free` is called.
* Do not free it manually.
*
* **Important**: currently, only 12 months of data are supported. If you supply more than 12 months, only the first 12
* will be used. If you provide fewer than 12 months, the function will return an error.
*
* @param input Pointer to the mn_input struct.
* @param values Pointer to mn_values containing monthly dew point temperature values [°C].
* @return MN_STATUS_OK if the values were set successfully, or an error code otherwise.
*/
MN_EXPORT mn_status mn_input_set_imported_monthly_dew_point_temperature(mn_input *input, mn_values *values);
/**
* @brief Sets the precipitation values for imported monthly data.
*
* This is an optional parameter.
*
* **Note:** The input struct takes ownership of the passed `mn_values` and will free it when `mn_input_free` is called.
* Do not free it manually.
*
* **Important**: currently, only 12 months of data are supported. If you supply more than 12 months, only the first 12
* will be used. If you provide fewer than 12 months, the function will return an error.
*
* @param input Pointer to the mn_input struct.
* @param values Pointer to mn_values containing monthly precipitation values [mm].
* @return MN_STATUS_OK if the values were set successfully, or an error code otherwise.
*/
MN_EXPORT mn_status mn_input_set_imported_monthly_precipitation(mn_input *input, mn_values *values);
/**
* @brief Frees a result structure returned by mn_compute_tmy.
*
* @param result Pointer to the mn_result struct to free.
*/
MN_EXPORT void mn_result_free(mn_result *result);
/**
* @brief Initializes the Meteonorm library with the provided key and data path.
*
* This function must be called before invoking any other Meteonorm functions.
* The data path is set during the first call. If the function is called again with a different data path, it will
* return an error.
*
* @param key Meteonorm key.
* @param data_path Path to Meteonorm data files.
* @return Error status MN_STATUS_OK if initialization was successful, or an error status with an error message
* otherwise.
*/
MN_EXPORT mn_error mn_init(char *key, char *data_path);
/**
* @brief Releases resources used by the Meteonorm library.
*
* This function should be called when the library is no longer needed.
*/
MN_EXPORT void mn_deinit();
/**
* @brief Retrieves the version information of the Meteonorm library.
*
* @return Version containing version information.
*/
MN_EXPORT mn_version mn_get_version();
/**
* @brief Retrieves the WMO station information for a given station ID.
*
* @param station_id WMO station ID.
* @return WMO station containing the station information.
*/
MN_EXPORT mn_wmo_station mn_get_wmo_station(int64_t station_id);
/**
* @brief Retrieves the time zone offset for a given location.
*
* @param latitude Latitude in degrees.
* @param longitude Longitude in degrees.
* @return Time zone offset in hours or an error if the time zone could not be determined.
*/
MN_EXPORT mn_time_zone mn_get_time_zone(double latitude, double longitude);
/**
* @brief Retrieves the altitude for a given location.
*
* @param latitude Latitude in degrees.
* @param longitude Longitude in degrees.
* @return Altitude in meters or an error if the altitude could not be determined.
*/
MN_EXPORT mn_altitude mn_get_altitude(double latitude, double longitude);
/**
* @brief Retrieves the horizon for a given location.
*
* @param latitude Latitude in degrees.
* @param longitude Longitude in degrees.
* @return 360 elevation angles in degrees, or an error if the horizon could not be determined.
*/
MN_EXPORT mn_horizon mn_get_horizon(double latitude, double longitude);
/**
* @brief Performs a Meteonorm computation based on the input parameters.
*
* @param input Pointer to the mn_input struct containing input parameters.
* @return Pointer to an mn_result struct where the results will be stored. Needs to be freed with
* mn_result_free by the caller.
*/
MN_EXPORT mn_result *mn_compute(mn_input *input);
#ifdef __cplusplus
}
#endif
#endif /* METEONORM_H */h