ladybug.sunpath module

Module for calculating sun positions and visualizing the sun path.

class ladybug.sunpath.Sun(datetime, altitude, azimuth, is_solar_time, is_daylight_saving, north_angle, data=None)[source]

Bases: object

An object representing a single Sun.

Parameters:

  • datetime – A DateTime that represents the datetime for this sun_vector

  • altitude – Solar Altitude in degrees.

  • azimuth – Solar Azimuth in degrees.

  • is_solar_time – Boolean indicating if the datetime represents a solar time.

  • is_daylight_saving – A Boolean indicating if the datetime is calculated for a daylight saving period

  • north_angle – North angle of the sunpath in degrees. This is only used to adjust the sun_vector and does not affect the sun altitude or azimuth.

Properties:

  • datetime

  • north_angle

  • hoy

  • altitude

  • azimuth

  • altitude_in_radians

  • azimuth_in_radians

  • is_solar_time

  • is_daylight_saving

  • data

  • is_during_day

  • sun_vector

  • sun_vector_reversed

ToString()[source]

Overwrite .NET ToString method.

position_2d(projection='Orthographic', origin=Point2D(0.00, 0.00), radius=100)[source]

Get a Point2D for the position of this sun on a sunpath.

Parameters:

  • projection –

    Text for the name of the projection to use from the sky dome hemisphere to the 2D plane. (Default: ‘Orthographic’). Choose from the following:

    • Orthographic

    • Stereographic

  • origin – A ladybug_geometry Point2D to note the center of the sun path.

  • radius – A number to note the radius of the sunpath.

Returns:

A Point2D for the position of this sun on a sunpath.

position_3d(origin=Point3D(0.00, 0.00, 0.00), radius=100)[source]

Get a Point3D for the position of this sun on a sunpath.

Parameters:

  • origin – A ladybug_geometry Point3D to note the center of the sun path.

  • radius – A number to note the radius of the sunpath.

Returns:

A Point3D for the position of this sun on a sunpath.

PI = 3.141592653589793
property altitude

Return solar altitude in degrees.

property altitude_in_radians

Return solar altitude in radians.

property azimuth

Return solar azimuth in degrees.

This value is the same regardless of what the north_angle is.

property azimuth_from_y_axis

Return solar azimuth in degrees with respect to the Y-axis of the scene.

This value will change as the north_angle is changed.

property azimuth_in_radians

Return solar azimuth in radians.

property data

Get or set metadata to this sun position.

No particular data type is enforced for this metadata but a dictionary is recommended so that it can be extended for multiple properties.

property datetime

Return datetime.

property hoy

Return Hour of the year.

property is_daylight_saving

Return a Boolean that indicates is datetime is solar time.

property is_during_day

Boolean to note if this sun position is during day.

property is_solar_time

Return a Boolean that indicates is datetime is solar time.

property north_angle

Return north angle for +YAxis.

property sun_vector

A ladybug_geometry Vector3D representing the vector for this sun.

Note that daytime sun vectors point downward (z will be negative).

property sun_vector_reversed

A ladybug_geometry Vector3D representing the reversed vector for this sun.

Daytime sun_vector_reversed point upward (z will be positive).

class ladybug.sunpath.Sunpath(latitude=0, longitude=0, time_zone=None, north_angle=0, daylight_saving_period=None)[source]

Bases: object

Calculate sun positions and visualize the sun path

Parameters:

  • latitude – A number between -90 and 90 for the latitude of the location in degrees. (Default: 0 for the equator)

  • longitude – A number between -180 and 180 for the longitude of the location in degrees (Default: 0 for the prime meridian)

  • time_zone – A number representing the time zone of the location for the sun path. Typically, this value is an integer, assuming that a standard time zone is used but this value can also be a decimal for the purposes of modeling location-specific solar time. The time zone should follow the epw convention and should be between -12 and +14, where 0 is at Greenwich, UK, positive values are to the East of Greenwich and negative values are to the West. If None, this value will be set to solar time using the Sunpath’s longitude. (Default: None).

  • north_angle – A number between -360 and 360 for the counterclockwise difference between the North and the positive Y-axis in degrees. 90 is West and 270 is East (Default: 0).

  • daylight_saving_period – An analysis period for daylight saving time. If None, no daylight saving time will be used. (Default: None)

Properties:

  • latitude

  • longitude

  • time_zone

  • north_angle

  • daylight_saving_period

  • is_leap_year

Usage:

import ladybug.sunpath as sunpath
# initiate sunpath
sp = sunpath.Sunpath(50)
sun = sp.calculate_sun(1, 1, 12) # calculate sun data for Jan 1 at noon
print(sun.azimuth, sun.altitude)
analemma_suns(time, daytime_only=False, is_solar_time=False, start_month=1, end_month=12, steps_per_month=1)[source]

Get an array of Suns that represent an analemma for a single time of day.

Parameters:

  • time – A ladybug Time object for the specific time of day to make the analemma.

  • daytime_only – A boolean to note whether only daytime suns should be included in the resulting array. Note that this can result in a completely empty array. (Default: False)

  • is_solar_time – A boolean to indicate if the output analemmas should be for solar hours instead of the hours of the sunpath time zone. (Default: False)

  • start_month – An integer from 1 to 12 to set the staring month for which the analemma is drawn. (Default: 1).

  • end_month – An integer from 1 to 12 to set the ending month for which the analemma is drawn. (Default: 12).

  • steps_per_month – An integer to set the number of sun positions that will be used to represent a single month. Higher numbers will take more time to compute but can produce smoother-looking analemmas. (Default: 1).

Returns:

An array of suns representing an analemma for a specific time. Analemmas will each have 12 suns for the 12 months of the year if daytime_only is False.

calculate_sun(month, day, hour, is_solar_time=False)[source]

Get Sun data for an hour of the year.

Parameters:

  • month – An integer between 1 and 12.

  • day – An integer between 1 and 31.

  • hour – A positive number between 0 and 23. This can be a decimal value to yield a solar position in between hours (eg. 12.5).

  • is_solar_time – A boolean to indicate if the input hour is in solar time. (Default: False)

Returns:

A sun object for the input month, day, hour.

calculate_sun_from_date_time(datetime, is_solar_time=False)[source]

Get Sun for a specific datetime.

This code is originally written by Trygve Wastvedt (Trygve.Wastvedt@gmail.com) based on (NOAA) and modified by Chris Mackey and Mostapha Roudsari.

Parameters:

  • datetime – Ladybug datetime.

  • is_solar_time – A boolean to indicate if the input hour is in solar time. (Default: False)

Returns:

A sun object for the input datetime.

calculate_sun_from_hoy(hoy, is_solar_time=False)[source]

Get Sun data for an hour of the year.

Parameters:

  • hoy – A number for the hour of the year. This can be a decimal value to yield a solar position in between hours (eg. 12.5).

  • is_solar_time – A boolean to indicate if the input hoy is in solar time. (Default: False)

Returns:

A sun object for the input hoy.

calculate_sun_from_moy(moy, is_solar_time=False)[source]

Get Sun data for a minute of the year.

Parameters:

  • moy – An integer for the minute of the year.

  • is_solar_time – A boolean to indicate if the input moy is in solar time. (Default: False)

Returns:

A sun object for the input moy.

calculate_sunrise_sunset(month, day, depression=0.5334, is_solar_time=False)[source]

Calculate sunrise, noon and sunset.

Parameters:

  • month – Integer for the month in which sunrise and sunset are computed.

  • day – Integer for the day of the month in which sunrise and sunset are computed.

  • depression – An angle in degrees indicating the additional period before/after the edge of the sun has passed the horizon where the sun is still considered up. Setting this value to 0 will compute sunrise/sunset as the time when the edge of the sun begins to touch the horizon. Setting it to the angular diameter of the sun (0.5334) will compute sunrise/sunset as the time when the sun just finishes passing the horizon (actual sunset). Setting it to 0.833 will compute the apparent sunrise/sunset, accounting for atmospheric refraction. Setting this to 6 will compute sunrise/sunset as the beginning/end of civil twilight. Setting this to 12 will compute sunrise/sunset as the beginning/end of nautical twilight. Setting this to 18 will compute sunrise/sunset as the beginning/end of astronomical twilight. (Default: 0.5334).

  • is_solar_time – A boolean to indicate if the output datetimes for sunrise, noon and sunset should be in solar time as opposed to the time zone of this Sunpath. (Default: False)

Returns:

A dictionary. Keys are (“sunrise”, “noon”, “sunset”). Values are datetimes that correspond to these moments. Note that some values may be None if there is no sunrise or sunset on the specified day.

calculate_sunrise_sunset_from_datetime(datetime, depression=0.5334, is_solar_time=False)[source]

Calculate sunrise, sunset and noon for a day of year.

Parameters:

  • datetime – A ladybug DateTime object to indicate the month and day for which sunrise and sunset are computed.

  • depression – An angle in degrees indicating the additional period before/after the edge of the sun has passed the horizon where the sun is still considered up. Setting this value to 0 will compute sunrise/sunset as the time when the edge of the sun begins to touch the horizon. Setting it to the angular diameter of the sun (0.5334) will compute sunrise/sunset as the time when the sun just finishes passing the horizon (actual sunset). Setting it to 0.833 will compute the apparent sunrise/sunset, accounting for atmospheric refraction. Setting this to 6 will compute sunrise/sunset as the beginning/end of civil twilight. Setting this to 12 will compute sunrise/sunset as the beginning/end of nautical twilight. Setting this to 18 will compute sunrise/sunset as the beginning/end of astronomical twilight. (Default: 0.5334).

  • is_solar_time – A boolean to indicate if the output datetimes for sunrise, noon and sunset should be in solar time as opposed to the time zone of this Sunpath. (Default: False)

Returns:

A dictionary. Keys are (“sunrise”, “noon”, “sunset”). Values are datetimes that correspond to these moments. Note that some values may be None if there is no sunrise or sunset on the specified day.

day_arc3d(month, day, origin=Point3D(0.00, 0.00, 0.00), radius=100, daytime_only=True, depression=0.5334)[source]

Get a ladybug_geometry Arc3D for the path taken by the sun on a single day.

Parameters:

  • month – Integer for the month in which sunrise and sunset are computed.

  • day – Integer for the day of the month in which sunrise and sunset are computed.

  • origin – A ladybug_geometry Point3D to note the center of the sun path.

  • radius – A number to note the radius of the sunpath.

  • daytime_only – A boolean to note whether None should be returned if the sun never rises above the horizon on the the input day. For example, in the arctic circle in winter. (Default: True)

  • depression – An angle in degrees indicating the additional period before/after the edge of the sun has passed the horizon where the sun is still considered up. Setting this value to 0 will return an arc that ends when the edge of the sun begins to touch the horizon. Setting it to the angular diameter of the sun (0.5334) will return an arc that ends right at the horizon (actual sunset). Setting it to 0.833 will compute the apparent sunrise/sunset, accounting for atmospheric refraction. Setting to 6 will return an arc that ends at the beginning/end of civil twilight. Setting to 12 will return an arc that ends at the beginning/end of nautical twilight. Setting to 18 will return an arc that ends at the beginning/end of astronomical twilight. (Default: 0.5334)

Returns:

An Arc3D for the path of the sun taken over the course of a day. Will be None if daytime_only is True and the sun is completely below the horizon for the entire day.

day_polyline2d(month, day, projection='Orthographic', origin=Point2D(0.00, 0.00), radius=100, daytime_only=True, depression=0.5334, divisions=10)[source]

Get a Polyline2D for the path taken by the sun on a single day.

Parameters:

  • month – Integer for the month in which sunrise and sunset are computed.

  • day – Integer for the day of the month in which sunrise and sunset are computed.

  • projection –

    Text for the name of the projection to use from the sky dome hemisphere to the 2D plane. (Default: ‘Orthographic’). Choose from the following:

    • Orthographic

    • Stereographic

  • origin – A ladybug_geometry Point2D to note the center of the sun path.

  • radius – A number to note the radius of the sunpath.

  • daytime_only – A boolean to note whether None should be returned if the sun never rises above the horizon on the the input day. For example, in the arctic circle in winter. (Default: True)

  • depression – An angle in degrees indicating the additional period before/after the edge of the sun has passed the horizon where the sun is still considered up. Setting this value to 0 will return an arc that ends when the edge of the sun begins to touch the horizon. Setting it to the angular diameter of the sun (0.5334) will return an arc that ends right at the horizon (actual sunset). Setting it to 0.833 will compute the apparent sunrise/sunset, accounting for atmospheric refraction. Setting to 6 will return an arc that ends at the beginning/end of civil twilight. Setting to 12 will return an arc that ends at the beginning/end of nautical twilight. Setting to 18 will return an arc that ends at the beginning/end of astronomical twilight. (Default: 0.5334)

Returns:

A Polyline2D for the path of the sun taken over the course of a day. Will be None if daytime_only is True and the sun is completely below the horizon for the entire day.

classmethod from_location(location, north_angle=0, daylight_saving_period=None)[source]

Create a sun path from a ladybug.location.Location.

hourly_analemma_polyline2d(projection='Orthographic', origin=Point2D(0.00, 0.00), radius=100, daytime_only=True, is_solar_time=False, start_month=1, end_month=12, steps_per_month=1)[source]

Get an array of ladybug_geometry Polyline2D for hourly analemmas.

Parameters:

  • projection –

    Text for the name of the projection to use from the sky dome hemisphere to the 2D plane. (Default: ‘Orthographic’). Choose from the following:

    • Orthographic

    • Stereographic

  • origin – A ladybug_geometry Point2D to note the center of the sun path.

  • radius – A number to note the radius of the sunpath.

  • daytime_only – A boolean to note whether only the daytime hours should be represented in the output Polyline2D. (Default: True)

  • is_solar_time – A boolean to indicate if the output analemmas should be for solar hours instead of the hours of the sunpath time zone. (Default: False).

  • start_month – An integer from 1 to 12 to set the staring month for which the analemma is drawn. (Default: 1).

  • end_month – An integer from 1 to 12 to set the ending month for which the analemma is drawn. (Default: 12).

  • steps_per_month – An integer to set the number of sun positions that will be used to represent a single month. Higher numbers will take more time to compute but can produce smoother-looking analemmas. (Default: 1).

Returns:

An array of ladybug_geometry Polyline2D with at least one polyline for each analemma.

hourly_analemma_polyline3d(origin=Point3D(0.00, 0.00, 0.00), radius=100, daytime_only=True, is_solar_time=False, start_month=1, end_month=12, steps_per_month=1)[source]

Get an array of ladybug_geometry Polyline3D for hourly analemmas.

Parameters:

  • origin – A ladybug_geometry Point3D to note the center of the sun path.

  • radius – A number to note the radius of the sunpath.

  • daytime_only – A boolean to note whether only the daytime hours should be represented in the output Polyline3D. (Default: True)

  • is_solar_time – A boolean to indicate if the output analemmas should be for solar hours instead of the hours of the sunpath time zone. (Default: False).

  • start_month – An integer from 1 to 12 to set the staring month for which the analemma is drawn. (Default: 1).

  • end_month – An integer from 1 to 12 to set the ending month for which the analemma is drawn. (Default: 12).

  • steps_per_month – An integer to set the number of sun positions that will be used to represent a single month. Higher numbers will take more time to compute but can produce smoother-looking analemmas. (Default: 1).

Returns:

An array of ladybug_geometry Polyline3D with at least one polyline for each analemma.

hourly_analemma_suns(daytime_only=False, is_solar_time=False, start_month=1, end_month=12, steps_per_month=1)[source]

Get a nested array of Suns with one sub-array for each hourly analemma.

Parameters:

  • daytime_only – A boolean to note whether only daytime suns should be included in the resulting arrays. Note that this will likely result in completely empty arrays for some hours. (Default: False)

  • is_solar_time – A boolean to indicate if the output analemmas should be for solar hours instead of the hours of the sunpath time zone. (Default: False).

  • start_month – An integer from 1 to 12 to set the staring month for which the analemma is drawn. (Default: 1).

  • end_month – An integer from 1 to 12 to set the ending month for which the analemma is drawn. (Default: 12).

  • steps_per_month – An integer to set the number of sun positions that will be used to represent a single month. Higher numbers will take more time to compute but can produce smoother-looking analemmas. (Default: 1).

Returns:

An array of 24 arrays with each sub-array representing an analemma. Analemmas will have a number of suns equal to (end_month - start_month) * steps_per_month. The default is 12 suns for the 12 months of the year.

is_daylight_saving_hour(datetime)[source]

Check if a datetime is within the daylight saving time.

monthly_day_arc3d(origin=Point3D(0.00, 0.00, 0.00), radius=100, daytime_only=True, depression=0.5334)[source]

Get an array of Arc3Ds for the path taken by the sun on the 21st of each month.

Parameters:

  • origin – A ladybug_geometry Point3D to note the center of the sun path.

  • radius – A number to note the radius of the sunpath.

  • daytime_only – A boolean to note whether arcs should be excluded from the output array if the sun never rises above the horizon on the the day. For example, in the arctic circle in winter. (Default: True)

  • depression – An angle in degrees indicating the additional period before/after the edge of the sun has passed the horizon where the sun is still considered up. Setting this value to 0 will return an arc that ends when the edge of the sun begins to touch the horizon. Setting it to the angular diameter of the sun (0.5334) will return an arc that ends right at the horizon (actual sunset). Setting it to 0.833 will compute the apparent sunrise/sunset, accounting for atmospheric refraction. Setting to 6 will return an arc that ends at the beginning/end of civil twilight. Setting to 12 will return an arc that ends at the beginning/end of nautical twilight. Setting to 18 will return an arc that ends at the beginning/end of astronomical twilight. (Default: 0.5334)

Returns:

An array of ladybug_geometry Arc3D with an arc for the 21st of each month.

monthly_day_polyline2d(projection='Orthographic', origin=Point2D(0.00, 0.00), radius=100, daytime_only=True, depression=0.5334, divisions=10)[source]

Get an array of Polyline2Ds for the sun path on the 21st of each month.

Parameters:

  • projection –

    Text for the name of the projection to use from the sky dome hemisphere to the 2D plane. (Default: ‘Orthographic’). Choose from the following:

    • Orthographic

    • Stereographic

  • origin – A ladybug_geometry Point2D to note the center of the sun path.

  • radius – A number to note the radius of the sunpath.

  • daytime_only – A boolean to note whether arcs should be excluded from the output array if the sun never rises above the horizon on the the day. For example, in the arctic circle in winter. (Default: True)

  • depression – An angle in degrees indicating the additional period before/after the edge of the sun has passed the horizon where the sun is still considered up. Setting this value to 0 will return an arc that ends when the edge of the sun begins to touch the horizon. Setting it to the angular diameter of the sun (0.5334) will return an arc that ends right at the horizon (actual sunset). Setting it to 0.833 will compute the apparent sunrise/sunset, accounting for atmospheric refraction. Setting to 6 will return an arc that ends at the beginning/end of civil twilight. Setting to 12 will return an arc that ends at the beginning/end of nautical twilight. Setting to 18 will return an arc that ends at the beginning/end of astronomical twilight. (Default: 0.5334)

  • divisions – An integer for the number of divisions to be used when converting the daily arcs into Polyline2Ds. (Default: 10).

Returns:

An array of ladybug_geometry Polyline2D with a polyline for the 21st of each month.

PI = 3.141592653589793
property daylight_saving_period

Get or set an AnalysisPeriod for the daylight saving period.

Note that the st_hour and end_hour of the AnalysisPeriod will be interpreted as indicating the time of day when the shift in clocks happen. So setting the st_hour and end_hour to 2 will ensure that the time shift happens at 2 AM on the dates specified. Note that this is different than how the hour inputs of AnalysisPeriods typically work, where the st_hour and end_hour apply to every day of the analysis period.

If None, no daylight saving period will be used.

property is_leap_year

Get or set a boolean to indicate is sunpath calculated for a leap year.

property latitude

Get or set a number between -90 and 90 for the latitude in degrees.

property longitude

Get or set a number between -180 and 180 for the longitude in degrees.

Note that you will also likely want to update the time zone of the Sunpath if this value is set to something far from its original value.

property north_angle

Get or set a number between -360 and 360 for the north_angle in degrees.

property time_zone

Get or set the time zone as a number between -12 and + 14.

Setting this property to None will automatically set the Sunpath to use solar time for the Sunpath’s longitude.