Example1: Changing the North Angle

This example changes the North Angle for the following simple zone, in order to try to maximise the daylight factor:

This zone has a single window of arbitrary dimension.

1. Testing the Model

Before we start writing a script to change the North Angle and calculate the daylight factor, it is a very good idea to try and perform a simple daylight calculation in the 3D modeller to make sure there are no errors with the file.

If there are any errors performing the daylight calculation, your script will not run and it may be hard to diagnose the problem!

2. Input Variables

We only have one input variable in this situation, and that is the North Angle.

To add the North Angle as a variable, right click in the Variables window and click Add:

Set the initial variable value to 0, the minimum value the variable is allowed to be to 0 and the maximum value the variable is allowed to be as 360. The Step property gives the optimisation program guidance on how much to change the variable by each time the script runs.

3. Output Variables

The only value we are interested in calculating in this example is the daylight factor for the zone in the model. We can add an output variable in a similar way to how we added an input variable:

4. The Script

We start our script by opening the Tas 3D modeller ‘behind the scenes’ on our machine:

//Open the 3D modeller (hidden)
TAS3D.T3DDocument my3DDocument = new TAS3D.T3DDocument();

On the left of the equals sign, we are creating a variable called my3DDocument, and the variable can only ever refer to instances of the Tas 3D modeller. On the right of the equals sign, we are setting our variable to a new instance of the 3D modeller.

Before we can open our T3D file, we need to tell the 3D modeller where to find the file we want to open. We can create a variable to store the file path, then create another variable to store a file path that corresponds to a copy of the file that exists in our working directory. We can then copy the file to this directory:

//Make a variable to store the path to our file and copy the file to our current working directory
string pathToFile =TasFiles.getFiles(TasGenComm.TasFiles.TasExtension.T3D)["MyT3D.t3d"].FullPath;
string newPathToFile = TasExtensions.CopyToCurrentDirectory(pathToFile,true);

Note

We can find out the path to our T3D file by double clicking on the file in the Tas Files window:

A small section of code will be added to the project that corresponds to the path to the file:

TasFiles.getFiles(TasGenComm.TasFiles.TasExtension.T3D)["MyT3D.t3d"].FullPath

See also

For more information regarding Multithreading considerations, please see Multithreading.

It is a good idea to copy the file to the current working directory because GenOpt is multithreaded, and sometimes the script will run several times simultaneously. If multiple instances of the script try to access the same resources at the same time, an error will occur.

Now we’re ready to open the T3D file:

//Open our file
bool fileOpenedOK = my3DDocument.Open(pathToFile);

We can check if the file opened successfully by checking the value of the variable fileOpenedOK:

//Check the file opened successfully
if(!fileOpenedOK) throw new Exception("The file could not be opened!");

If the file does not open properly, we can throw an exception. This tells the TasGenOpt program that something went wrong, and we’ll be able to see this message in our Errors window on the Simulate tab.

We’re now ready to set the North Angle of our building, like so:

//Set the north angle
my3DDocument.Building.northAngle = Variables["NorthAngle"].VariableValue;

Note

We can refer to one of our input variables automatically by right clicking on the variable in the Variables window, and clicking Insert Reference:

Our daylight calculation can be performed as follows:

//Initialise and perform daylight calculation
my3DDocument.DaylightInitCalculation(1,1,1,0);
my3DDocument.DaylightSkyCloudiness(TAS3D.DaylightSkyCloudiness.t3dClear);
my3DDocument.DaylightSkyandSun(TAS3D.DaylightSunSky.t3dSunAndSky);
my3DDocument.DaylightAccuracy(TAS3D.DaylightAccuracyType.t3dPreview,0);
my3DDocument.DaylightCalculationTime(212,14,30);
my3DDocument.DaylightCalculation(0);
my3DDocument.DaylightSaveCalculation();

There are many different options that can be changed for the daylight calculation, but in this case we are mostly using default values.

Once the daylight calculation has finished, we can obtain the daylight factor for the first zone in the file as follows:

//Get the daylight factor for the first zone
TAS3D.Zone FirstZone = my3DDocument.Building.GetZone(1);
double daylightFactor = my3DDocument.GetDaylightFactor(FirstZone);

We should now close our T3D file as we are no longer using it:

//Close our t3d file
System.Runtime.InteropServices.Marshal.ReleaseComObject(my3DDocument);

We can now set our output variable we set up previously:

//Set our output variables
ScriptOutput.SetValue("DaylightFactor",daylightFactor);
ScriptOutput.SetValue("Result",1.0/daylightFactor);

Remember, TasGenOpt tries to minimise the value of Result, so we need an increase in daylight factor to make the value of Result smaller in order to maximise daylight factor. For more information about cost functions, please see Writing a Good Cost Function.

Our full script is now as follows:

//Open the 3D modeller (hidden)
TAS3D.T3DDocument my3DDocument = new TAS3D.T3DDocument();

//Make a variable to store the path to our file
string pathToFile =TasFiles.getFiles(TasGenComm.TasFiles.TasExtension.T3D)["MyT3D.t3d"].FullPath;
string newPathToFile = TasExtensions.CopyToCurrentDirectory(pathToFile,true);

//Open our file
bool fileOpenedOK = my3DDocument.Open(newPathToFile);

//Check the file opened successfully
if(!fileOpenedOK) throw new Exception("The file could not be opened!");

//Set the north angle
my3DDocument.Building.northAngle = Variables["NorthAngle"].VariableValue;

//Initialise and perform daylight calculation
my3DDocument.DaylightInitCalculation(1,1,1,0);
my3DDocument.DaylightSkyCloudiness(TAS3D.DaylightSkyCloudiness.t3dClear);
my3DDocument.DaylightSkyandSun(TAS3D.DaylightSunSky.t3dSunAndSky);
my3DDocument.DaylightAccuracy(TAS3D.DaylightAccuracyType.t3dPreview,0);
my3DDocument.DaylightCalculationTime(212,14,30);
my3DDocument.DaylightCalculation(0);
my3DDocument.DaylightSaveCalculation();

//Get the daylight factor for the first zone
TAS3D.Zone FirstZone = my3DDocument.Building.GetZone(1);
double daylightFactor = my3DDocument.GetDaylightFactor(FirstZone);

//Close our t3d file
System.Runtime.InteropServices.Marshal.ReleaseComObject(my3DDocument);

//Set our output variables
ScriptOutput.SetValue("DaylightFactor",daylightFactor);
ScriptOutput.SetValue("Result",1.0/daylightFactor);

Press Build to check our script for errors:

5. Simulating & Results

We can now switch to the Simulate tab and prepare to run our script. As we have only one input variable, we can use the Golden Section algorithm:

The AbsDiff value of 0.1 is related to how accurate we want our result to be; for a detailed explanation, please see the GenOpt manual.

When we press simulate, our script is executed and our results are plotted:

The Optimisation Results window summarises the results:

We have determined that in this case, for this model, a North Angle of 278° will maximise the daylight factor in the space at 2:30pm on day 212 of the year. It’s generally a good idea to open the file now and consider whether this result is reasonable; if it seems unreasonable, there is likely a mistake somewhere in the assumptions made or in the script file!