SYNOPSIS (optional) use Sim::OPT::Modish; modish( "PATH_TO_THE_ESP-r_CONFIGURATION_FILE.cfg", zone_number, surface_1_number, surface_2_number, ..., surface_n_number );

Example: modish( "/home/x/model/cfg/model.cfg", 1, 7, 9 ); (Which means: calculate for zone 1, surfaces 7 and 9.)


modish is a program for altering the shading values calculated by the ESP-r building simulation platform to take into account reflections from obstructions. More precisely, modish brings into account the reflective effect of solar obstructions on solar gains on building models on the basis of irradiance ratios. Those ratios are obtained combining the direct radiation on a surface and the total radiation calculated by the means of a raytracer (Radiance) on the same surface.

The effect of solar reflections is taken into account at each hour on the basis of the ratios between the irradiances measured at the models' surfaces in: a) the original model; b) a transitional model derived from that.

The irradiances are calculated through Radiance and derive from the following building models: a) a model in which the solar obstructions have their true reflectivity ; b) a model in which the solar obstructions are completely black.

The value given by 1 minus those irradiance ratios gives the diffuse shading factors that are put in the ISH file in place of the original values.

The original ISH's ".shda" files are not substituted. Two new files are added in the "zone" folder of the ESP-r model: the ".mod.shda" file is usable by ESP-r. It features the newly calculated shading factors; the ".report.shda" file lists the original shading factors and, at the bottom, the irradiance ratios from which the new shading factors in the ".mod.shda" file have been derived. Note that when the radiation on a surface is increased, instead of decreased, as an effect of reflections on obstructions, the shading factor may be negative, and the irradiance ratio will be greater than 1.

To this procedure another procedure can be chained to take additionally into account in the shading effect of the obstrucontions with respect to the radiation reflected from the ground.

Finally, modish is capable of calculating the shading factors from scratch by the means of the Radiance raytracer.

At the moment, the documentation describing how these operations are obtained and other information is inserted at the beginning of the source code.

The settings for managing modish are specified in a configuration file in the example folder and written as a comment at the beginning of the source code. This file must be named "" and be placed in the same directory from which modish is called, together with the "" and the "" file.

To launch modish, if it is installed as a Perl module:

use Sim::OPT::Modish;

modish( "PATH_TO_THE_ESP-r_CONFIGURATION_FILE.cfg", zone_number, surface_1_number, surface_2_number, ..., surface_n_number );

Example: modish( "/home/x/model/cfg/model.cfg", 1, 7, 9 );

If instead the file is used by itself, as a script, it has to be launched from the command like with:

perl ./modish PATH_TO_THE_ESP-r_CONFIGURATION_FILE.cfg zone_number surface_1_number surface_2_number surface_n_number

For example:

perl ./ 1 7 9 (which means: calculate for zone 1, surfaces 7 and 9.)

The path of the ESP-r model configuration path has to be specified in full, like in the example above.

To be sure that the code works as a script, the header "package" etc. should be transformed in a comment.

In calculating the irradiance ratios, the program defaults to: 5 direction vectors; diffuse reflections: 2 ; direct reflections: 7; surface grid: 2 x 2; distance from the surface for calculating the irradiances: 0.01 (metres).

For the program to work correctly, the materials, construction and optics databases must be local to the ESP-r model.

modish should works with Linux and hopefully still the Mac.




Gian Luca Brunetti, <>


Copyright (C) 2008-2019 by Gian Luca Brunetti and Politecnico di Milano. This 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, version 3.