Set up a workbook (Energy)

Set up yield calculation

The CalculationSettings class contains most of the settings used for the calculation (set in the 'Energy > Setup yield calculation' screen).

Note

Most of the effects in the user interface are shown as percentages, but when getting or settings the effects values through scripting they are values between -1.0 and 0.0 (for negative values) and between 0.0 and 1.0 (for positive values).

So just be careful to use the correct value when setting effects in scripting (divide the percentage value by 100.0).

Layout and Resources

CalculationSettings calcSettings = Workbook.CalculationSettings;

// Set the site layout to use 
calcSettings.SiteLayout = Workbook.Domain.VisibleSiteLayout;

// Set the solar resource and year
calcSettings.SolarResource = Workbook.Climate.SolarResources.First();
calcSettings.Year = 2017;

// Set the horizon
calcSettings.HorizonData = Workbook.Domain.Geography.HorizonData.First();
calcSettings.UseHorizonLine = true;

Soiling Effects

// Set and use an overall soiling effect (to a value of -12%)
Workbook.Domain.Geography.SoilingEffectData.OverallSoilingEffect = -0.12;
Workbook.Domain.Geography.SoilingEffectData.UseMonthlySoilingValues = false;

/// <summary>
/// Use monthly soiling.
/// </summary>
public void Execute()
{
    // Set and use an overall soiling effect (to a value of -12%)
    Workbook.Domain.Geography.SoilingEffectData.UseMonthlySoilingValues = true;
    SetMonthlySoilingEffect(1, -4);
    SetMonthlySoilingEffect(2, -3);
    SetMonthlySoilingEffect(3, -1.3);
    SetMonthlySoilingEffect(4, -0.3);
    SetMonthlySoilingEffect(5, 0);
    SetMonthlySoilingEffect(6, 0);
    SetMonthlySoilingEffect(7, 0);
    SetMonthlySoilingEffect(8, 0);
    SetMonthlySoilingEffect(9, 0);
    SetMonthlySoilingEffect(10, -0.8);
    SetMonthlySoilingEffect(11, -2.1);
    SetMonthlySoilingEffect(12, -3.4);
}

private void SetMonthlySoilingEffect(int month, double soilingEffectPercentage)
{
    MonthlySoilingValue monthlyEffect = Workbook.Domain.Geography.SoilingEffectData.MonthlySoilingEffects.FirstOrDefault(o => o.Month == month);
    if (monthlyEffect == null)
    {
        Toolbox.Log(string.Format("Could not find a monthly soiling effect with month of {0}", month), LogLevel.Error);
    }
    else
    {
        monthlyEffect.SoilingValue = soilingEffectPercentage * 0.01;
    }
}

Disable Models

CalculationSettings calcSettings = Workbook.CalculationSettings;

// Disable all the available models that can be disabled
calcSettings.DisabledModels.DiffuseTransposition = true;
calcSettings.DisabledModels.IncidenceAngleModifier = true;
calcSettings.DisabledModels.NearShading = true;
calcSettings.DisabledModels.CellTemperature = true;
calcSettings.DisabledModels.Spectral = true;
calcSettings.DisabledModels.Bifacial = true;

Electrical Effects and Limits

CalculationSettings calcSettings = Workbook.CalculationSettings;

// Module mismatch and grid availability effects
calcSettings.MismatchEffect = -0.015; // -1.5% effect
calcSettings.Availability = -0.025;   // -2.5 effect

// Grid connection limit
calcSettings.UseGridConnectionLimit = true;
calcSettings.GridConnectionLimit = 12000;   // 12 kW

Cell Temperature Model Parameters

CalculationSettings calcSettings = Workbook.CalculationSettings;

// Input irradiance type
calcSettings.CellTempModelParameters.InputIrradianceType = PvsystInputIrradianceType.WithoutIncidenceAngleModifier;

// Constant wind speed
calcSettings.CellTempModelParameters.UseConstantWindSpeedValue = true;
calcSettings.CellTempModelParameters.ConstantWindSpeed = 4.45;	 // 4.45 m/s

Calculation Model Settings

CalculationSettings calcSettings = Workbook.CalculationSettings;

calcSettings.DiffuseTranspositionModel = DiffuseTranspositionModel.Perez;
calcSettings.EnableDiffuseEdgeCaseHandling = true;

calcSettings.CircumsolarType = CircumsolarType.Direct;

calcSettings.IncludeSoilingLossInTemperatureModel = true;

Yield results

The following code runs the energy calculation and extracts and prints out some of the energy yield values from the results.

EnergyYieldCalculationScenario scenario = Toolbox.ExecuteEnergyCalculation(
    "Scenario 1",
    Workbook.CalculationSettings.SolarResource,
    Workbook.CalculationSettings.SiteLayout,
    Workbook.CalculationSettings.HorizonData);

// There may be more than one year.  For this example, just choose the first year of results.
AnnualEnergyYieldResults firstYearAnnualResults = scenario.YearlyResultsList.First();

// Print out some values of the annual energy yield results
Toolbox.Log(string.Format("Annual Energy Yield:       {0:0.0}", 
    firstYearAnnualResults.EnergyYield));
Toolbox.Log(string.Format("Annual Grid Energy:        {0:0.0}", 
    firstYearAnnualResults.NetEnergy));
Toolbox.Log(string.Format("Annual Performance Ratio:  {0:0.0}", 
    firstYearAnnualResults.PerformanceRatio));

// Print out some values of the monthly energy yield results
foreach (MonthlyEnergyYieldResults monthlyEnergyYieldResults in firstYearAnnualResults.MonthlyResults)
{
    Toolbox.Log(string.Format(
        "Month {0}: Energy Yield = {1:0.0}, Grid Energy = {2:0.0}, PR = {3:0.0}",
        monthlyEnergyYieldResults.MonthName,
        monthlyEnergyYieldResults.EnergyYield,
        monthlyEnergyYieldResults.NetEnergy,
        monthlyEnergyYieldResults.PerformanceRatio));
}

The script above produces output similar to the following:

Energy Calculation returned successfully
Annual Energy Yield:       1060.2
Annual Grid Energy:        383.7
Annual Performance Ratio:  74.5
Month January: Energy Yield = 35.8, Grid Energy = 12.9, PR = 62.7
Month February: Energy Yield = 54.4, Grid Energy = 19.7, PR = 73.1
Month March: Energy Yield = 85.6, Grid Energy = 31.0, PR = 73.5
Month April: Energy Yield = 81.1, Grid Energy = 29.4, PR = 64.1
Month May: Energy Yield = 114.2, Grid Energy = 41.3, PR = 69.6
Month June: Energy Yield = 150.8, Grid Energy = 54.6, PR = 77.7
Month July: Energy Yield = 156.9, Grid Energy = 56.8, PR = 79.8
Month August: Energy Yield = 127.5, Grid Energy = 46.1, PR = 82.4
Month September: Energy Yield = 106.3, Grid Energy = 38.5, PR = 82.1
Month October: Energy Yield = 77.4, Grid Energy = 28.0, PR = 80.6
Month November: Energy Yield = 43.9, Grid Energy = 15.9, PR = 64.9
Month December: Energy Yield = 26.3, Grid Energy = 9.5, PR = 56.3

As well as getting the EnergyYieldCalculationScenario object directly after running a calculation you can also get it from the Workbook, assuming that a calculation has been run:

// Get the first calculation scenario, if there is one
EnergyYieldCalculationScenario scenario = Workbook.CalculationScenarios.FirstOrDefault();
if (scenario == null)
{
    Toolbox.Log("Scenario is null");
    return;
}

// Print out some values of the annual energy yield results
AnnualEnergyYieldResults annualResults = scenario.YearlyResultsList.First();
Toolbox.Log(string.Format("Annual Energy Yield: {0:0.0}", annualResults.EnergyYield));
Toolbox.Log(string.Format("Annual Grid Energy: {0:0.0}", annualResults.NetEnergy));
Toolbox.Log(string.Format("Annual Performance Ratio: {0:0.0}", annualResults.PerformanceRatio));

Effects diagram

The following code runs the energy calculation and extracts and prints out some of the effect values from the results.

EnergyYieldCalculationScenario scenario = Toolbox.ExecuteEnergyCalculation(
    "Scenario 1",
    Workbook.CalculationSettings.SolarResource,
    Workbook.CalculationSettings.SiteLayout,
    Workbook.CalculationSettings.HorizonData);

// There may be more than one year.  For this example, just choose the first year of results.
AnnualEnergyYieldResults firstYearAnnualResults = scenario.YearlyResultsList.First();

// Print out some values of the annual energy effects
EnergyYieldEffects annualEffects = firstYearAnnualResults.AnnualEffects;

// Don't forget to multiply the effects by 100 to get a percentage, as they are stored as
// values between -1.0 and 0.0 (for negative values) and values between 0.0 and 1.0 (for
// positive values)
Toolbox.Log(string.Format("Annual Shading Effect:             {0:0.0}%", 
    100 * annualEffects.NearShadingIrradiance));
Toolbox.Log(string.Format("Annual Soiling Effect:             {0:0.0}%", 
    100 * annualEffects.Soiling));
Toolbox.Log(string.Format("Annual Electrical Mismatch Effect: {0:0.0}%", 
    100 * annualEffects.ElectricalMismatch));
Toolbox.Log(string.Format("Annual Inverter Efficiency Effect: {0:0.0}%", 
    100 * annualEffects.InverterEfficiency));

// Print out some values of the monthly energy yield results
foreach (MonthlyEnergyYieldEffects monthlyEffects in firstYearAnnualResults.MonthlyEffects)
{
    Toolbox.Log(string.Format(
        "Month {0}: Shading = {1:0.0}%, Soiling = {2:0.0}%, Electrical Mismatch = {3:0.0}%",
        monthlyEffects.MonthName,
        100 * monthlyEffects.NearShadingIrradiance,
        100 * monthlyEffects.Soiling,
        100 * monthlyEffects.ElectricalMismatch));
}

The script above produces output similar to the following:

Energy Calculation returned successfully
Annual Shading Effect:             -7.6%
Annual Soiling Effect:             -0.7%
Annual Electrical Mismatch Effect: -1.9%
Annual Inverter Efficiency Effect: -4.2%
Month January: Shading = -22.4%, Soiling = -4.0%, Electrical Mismatch = -9.0%
Month February: Shading = -8.9%, Soiling = -3.0%, Electrical Mismatch = -8.3%
Month March: Shading = -5.1%, Soiling = -1.3%, Electrical Mismatch = -0.1%
Month April: Shading = -5.9%, Soiling = -0.3%, Electrical Mismatch = 0.0%
Month May: Shading = -5.7%, Soiling = 0.0%, Electrical Mismatch = 0.0%
Month June: Shading = -5.1%, Soiling = 0.0%, Electrical Mismatch = 0.0%
Month July: Shading = -4.7%, Soiling = 0.0%, Electrical Mismatch = 0.0%
Month August: Shading = -5.6%, Soiling = 0.0%, Electrical Mismatch = 0.0%
Month September: Shading = -5.0%, Soiling = 0.0%, Electrical Mismatch = 0.0%
Month October: Shading = -7.3%, Soiling = -0.8%, Electrical Mismatch = -5.5%
Month November: Shading = -17.6%, Soiling = -2.1%, Electrical Mismatch = -13.1%
Month December: Shading = -27.9%, Soiling = -3.4%, Electrical Mismatch = -11.5%