.. highlight:: C#

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:
	.. image:: images/onezone.png
		:scale: 50 %

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.
	.. image:: images/dfcalc_t3d.png
		:scale: 50 %

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**:
	.. image:: images/example1/add_var.png
		:scale: 75 %

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:
	.. image:: images/example1/add_output.png
		:scale: 75 %

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:
		.. image:: images/example1/doubleclickfile.png
			:scale: 75 %
	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

.. seealso::
	For more information regarding Multithreading considerations, please see :ref:`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**:
		.. image:: images/example1/insert_var_ref.png
			:scale: 75 %

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 :ref:`CostFunctions`.

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:
	.. image:: images/example1/buildok.png
		:scale: 75 %

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:
	.. image:: images/example1/AlgorithmOptions.png
		:scale: 75 %

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:
	.. image:: images/example1/resultgraph.png
		:scale: 75 %

The *Optimisation Results* window summarises the results:
	.. image:: images/example1/optresults.png
		:scale: 75 %

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!