Sim-OPTS version 0.36.16.11
============================

INSTALLATION

To install this module type the following:

   perl Makefile.PL
   make
   make test
   make install

DEPENDENCIES

This module requires these other modules and libraries:

  Math::Trig
  Data::Dumper
  List::Util
  List::MoreUtils
  Devel::REPL

COPYRIGHT AND LICENCE

Copyright (C) 2008-2014 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 2 or later.

Sim::OPTS it a tool for detailed metadesign. It morphs models by propagation of constraints through the ESP-r building performance simulation platform and performs optimization by overlapping block coordinate descent.

A working knowledge of ESP-r is necessary to use OPTS. Information about ESP-r can be found at http://www.esru.strath.ac.uk/Programs/ESP-r.htm.

To install OPTS, the command <cpanm Sim::OPTS> has to be issued. Perl will take care to install all dependencies. OPTS can be loaded through the command <use Sim::OPTS> in Perl. For that purpose, the "Devel::REPL" module can be used. As an alternative, the batch file "opt" (which can be found in the "example" folder in this distribution) may be copied in a work directory and the command <opt> may be issued. That command will activate the OPTS functions, following the settings specified in a previously prepared configuration file. When launched, OPTS will ask the path to that file. Its activity will start after receiving that information. 
The OPTS configuration file has to contain a suitable description of the operations to be accomplished pointing to an existing ESP-r model. The OPTS configuration file is extended by other files in which the search structures to be searched into or to be generated are specified. Those files are designated with the "$casefile", "$chancefile", "$caseed" and "$chanceseed" variables. But if wanted the variables contained in those files can be written directly in the main configuration file.

In this distribution there is a set of commented template files and an example of OPTS configuration file. The example has been written for a previous version of OPTS and will probably not work with the present one due to minor changes in the header variables. The complete set of files linked to that configuration file may be downloaded athttp://figshare.com/articles/Dataset_of_a_computational_research_on_block_coordinate_search_based_on_building_performance_simulations/1158993 .

To run OPTS without making it act on model files, the setting <$exeonfiles = "n";> should be specified in the configuration file. By setting the variable "$toshell" to the chosen path, the path for the text file that will receive the commands in place of the shell should be specified.

OPTS will give instruction to ESP-r via shell to make it modify the building model in different copies. Then, if asked, it will run simulations, retrieve the results, extract some information from them and order it as requested.

Besides an OPTS configuration file, also configuration files for propagation of constraints may be created. This will give to the morphing operations much greater flexibility. Propagation of constraints can regard the geometry of a model, solar shadings, mass/flow network, and/or controls; and also, how those pieces of information affect each other and daylighting (calculated through the Radiance lighting simulation program). Example of configuration files for propagation of constraints are included in this distribution.

The ESP-r model folders and the result files that will be created in a parametric search will be named as the root model, followed by a "_" character, followed by a variable number referred to the first morphing phase, followed by a "-" character, followed by an iteration number for the variable in question, and so on for all morphing phases. For example, the model instance produced in the first iteration for a root model named "model" in a search constituted by 3 morphing phases and 5 iteration steps each will be named "model_1-1_2-1_3-1"; and the last one "model_1-5_2-5_3-5".

To describe a block search, the most important variables to be taken into account in a configuration file are "@varn" - which represents the sequence of design variables - and "@casegroup" - which represent the sequence of decompositions to be taken into account. After joining "@varn" with two copies of itself, OPTS will work in the middle of the so-obtained sequence, but the user is not required to be aware of that. How "@varn" and "@casegroup" should be specified is more quickly described with a couple of examples.

1) If brute force optimization is sought for a case composed by 4 parameters, the following settings should be specified: <@varn = (1, 2, 3, 4);> and <@casegroup = ( [ [0, 4] ] ) ;>.

2) If optimization is sought for two cases (brute force, again, for instance, with a different set of parameters), the two sets of parameters in questions has to be specificied as sublists of the general parameter list: <@varn = (1, 2, 3, 4, 6, 7, 8);> and <@casegroup = ( [ [0, 4] , [5, 8] ] ) ;>.

3) If a block search is sought on the basis of 5 parameters, with 4 overlapping active blocks composed by 3 parameters each having the leftmost parameters in position 0, 1, 2 and 4, and two search sweeps have to be performed, with the second sweep having the parameters in inverted order and the leftmost parameters in position 2, 4, 3 and 1, the following settings should be specified: <@varn = ( [ [1, 2, 3, 4, 5], [1, 2, 3, 4, 5], [1, 2, 3, 4, 5], [1, 2, 3, 4, 5], [5, 4, 3, 2, 1], [5, 4, 3, 2, 1], [5, 4, 3, 2, 1], [5, 4, 3, 2, 1]] );> and <@casegroup = ( [ [0, 3], [1, 3], [2, 3], [4, 3] ], [2, 3], [4, 3], [3, 3], [1, 3] ] );>.

4) By playing with the order of the parameters' sequence, blocks with non-contiguous parameters can be modelled. Example: <@varn = ( [ [1, 2, 3, 4, 5], [1, 2, 3, 4, 5], [1, 2, 3, 4, 5], [1, 2, 3, 4, 5], [5, 2, 4, 1, 3], [2, 4, 1, 5, 2], [5, 1, 4, 2, 3], [5, 1, 4, 2, 3] ] );> and <@casegroup = ( [ [0, 3], [1, 3], [2, 3], [4, 3] ], [2, 3], [4, 3], [3, 3], [1, 3] ] );>.

5) Nothing prevents that the blocks are of different size (i.e. each composed by a different number of parameters). Example: <@varn = ( [ [1, 2, 3, 4, 5], [1, 2, 3, 4, 5], [1, 2, 3, 4, 5], [1, 2, 3, 4, 5], [5, 2, 4, 1, 3], [2, 4, 1, 5, 2], [5, 1, 4, 2, 3], [5, 1, 4, 2, 3] ] );> and <@casegroup = ( [ [0, 3], [1, 3], [2, 3], [4, 3] ], [2, 2], [4, 2], [3, 4], [1, 4] ] );>.

OPTS is a program I have written as a side project since 2008 with no funding. It was the first real program I attempted to write. From time to time I add some parts to it. The parts of it that have been written earlier are the ones that are coded in the strangest manner.

Gian Luca Brunetti, Politecnico di Milano
gianluca.brunetti@polimi.it