This manual is still a rough draft..... what you see is what you get.
I have attempted to make STARt as flexible as possible, allowing the user to try out a wide variety of different telescope configurations without having to recompile the program. Once a configuration is decided on it should be straightforward to use STARt to as simply a link in the chain of a larger study. All of the telescope parameters are handled through a parameter file and possibly a file giving the positions of the heliostats. Shower dependent information (like where the shower hits the ground relative to the telescope) is stored in environmental variables so that they can be easily manipulated at runtime.
All of this is handled by a central command file. This command file needs toa ssign to the appropriate logical names the various input and output files, create a few system variables to control the behavior of STARt, as well as actually run the executable.
Installing the package will be a matter of deciding where you want to put the executable code and where you want to put your various parameter and data files and then writing a command file to pull this all together. Then you will want to compile the source, select your parameters, generate some showers and get started.
The STARt program was written to run on a DEC Alpha workstation, I use VMS command files to provide links between the various components and to handle the actual execution of the files.
The core program is written using VMS FORTRAN 77 and doesn't call any external libraries. However the display programs that I have included call functions from the VAX GKS graphics library. The code does use structures, which may not be supported by other versions of FORTRAN 77. I have not looked to see if my structures would be compatible with the structures in FORTAN 95.
A collaborator at UCR is working on a UNIX port of the code. I will post this as soon as it becomes available.
The distribution of this package contains several different types of files and we will be creating others. Here is a list of the various types that we will be working with.
I would recommend that you organize your files as follows. Place all of the FORTRAN files in one directory. Then for each project create a directory for your parameter files and one for your data files. I would probably place my parameter files in a working directory and my data files in a subdirectory off of that one. The command files can be placed anywhere, I would place them with the parameter files.
The parameter file is a text file containing the values of most of the variables that describe the telescope. Parameters are organized in categories as follows:
Heliostat Field Information
Segment Information
Targeting Information
Secondary Optics
Instrument Information
Lines beginning with an exclamation mark are ignored by the computer and are usedto remind the user what input values represent. I was not particularly elegant in writing this input routine therefore it is important that the parameters match the format given in the example. All parameters need to be specified with the appropriate type in the correct order for STARt to operate correctly.
All lengths should be given in meters.
a hypertext example of a parameter file:
! basic STARt Solar Tower Array Ray-tracer parameter file! do not put any tabs into these lines, no line can be more than ! 80 characters long. ! lines starting with a bang "!" are comments and are ignored in the code!______________ Basic Array Characteristics!INTERNAL PAR: number of heliostats up to 2000!Heliostat Size , two by three-4.0, 4.0, -4.0, 4.0, -1.0E-12, 1.0E-12!Heliostat Placement Technique, 1=grid, 2=File (x,y), 3=file (x,y,z,HA)1!Grid Columns, integer11!Grid Rows, integer11!Grid Spacing, float20.0!center of heliostat field, 3 vector, float100.0,100.0,0.0!______________ Segment Information!Number of segments9!Segment Layout-2.0,-2.0,0.0-2.0,0.0,0.0-2.0,2.0,0.00.0,-2.0,0.00.0,0.0,0.00.0,2.0,0.02.0,-2.0,0.02.0,0.0,0.02.0,2.0,0.0!Segment type for the field, int 1=planar 2=cyl 3=parab1!Planar Segment Size, two by three -1.0, 1.0, -1.0, 1.0, -1.0E-12, 1.0E-8!Segment Focal Length, float150.0!Segment Allignment Technique, 1=flat, 2=cantered, 3=manual3!Location of Manual Cantering Target, vector100.0, 100.0, 10000.0!______________ Target:!Pointing Target, vector100.0,100.0,10000.0!Pointing Technique, int, 0 = infinity 1= at target1!Recieving position for heliostat array, vector100.0,-50.0,50.0!______________ Secondary Optics:!Secondary Position, vector100.0,-50.0,50.0!Secondary Normal, vector75.82, 128.98, -50.8!Secondary Diameter, float2.0!Secondary Focal Length, float2.0!______________ Detector Information!Detector Type, int, 0=no sec, 1=basic plane1!Detector Positioning, int 1=auto 2=manual1!Detector Position, vector100.0, -50.0, 50.0!Detector Normal, vector-1.0, -1.0, 1.0!Detector Size, 2 by 3 array, reals-1.0, 1.0, -1.0, 1.0, -1.0E-12, 1.0E-12The individual parameters might bear some explaining.. Heliostat Parameters
Heliostat Size
A two by three array of reals.
Heliostat size is the size array that defines the approximate size of the heliostat. This is used within a routine which assumes all of the heliostats are simple planes to determine if they might be hit by a photon. Since this is only to determine if the heliostat might be hit, you should set this size several centimeters larger than the actual surface of your heliostat. The overestimate won't slow your runtime down much and an underestimate will cause you to loose photons. Also given any canting or curvature of segments it is important to make sure you don't loose photons that might just graze one edge of your outermost segments.
Heliostat Placement Technique
integer
You have several options in how you specify the layout of the heliostats on the ground. In any case these positions need to be in the "global" coordinate system.
Grid Columns, Rows, Spacing
Single values, integer for the number of columns and rows, real for the spacing.
If heliostat placement technique is "grid" then these three parameters define the grid size and spacing. Spacing should be in meters and goes for both x and y spacing. This grid will always place the first heliostat at 0,0,0 and will extend out intothe first quadrant in the x,y plane. These parameters are unusedunder the remaining heliostat placement techniques.
Center of Heliostat Field
real vector
This is the location that STARt uses for the center of the heliostat field. Thiscomes into play in two places. If the heliostat field is focused towards the source then this variable is used to calculate the vector from the telescope to the source.This value is also used to orient the secondary mirror in the autofocus option.
Segement Parameters
Number of Segments
integer
This is the number of segments on each heliostat. The data structures in the codecontain space for up to 25 segments so this number should range from 1-25. Ifnecessary it is a trivial task to enlarge the array in the code. Simplychange max_segments parameter in STARt_struct.inc.
Segment Layout
One line for each segment, each a real vector.
This section requires one line per segment. Each line is used to specify the position (in heliostat coordinates) of the center of a single segment.
Segment Type
integer
This number determines what shape is used for the segments.
Segment Size
A two by three array of reals.
This Size Array defines the bounds on each individual array.Note that for parabolic and cylindrical segments the "max z" componentis recalculated from the focal length and extent of the segment, so a rough approximation is all that is needed here.
This value is used as the focal length of each segment if cylindrical or parabolic segments are selected.
If -1.0 is specified the segements will each be given a focal length equal to their heliostat-receiver distance.
Segment Alignment Technique
integer
This number determines how the individual segments are canted (aligned).
Location of Manual Cantering Target
real vector
This is used only with the manual cantering technique to specify the location of the source of the rays used to set the cant on the individual segments in each heliostat.
Targeting Parameters
Pointing Target
real vector
This parameter specifies the estimated shower center position used to align the heliostats during the actual raytracing. Depending on the pointing technique this parameter is used in different ways. For example if the heliostatfield is set to look towards the shower center the heliostatsare each oriented such that a ray would travel from this point through the center of each heliostat (point 0,0,0 in the heliostat coordinate system)and be reflected up to the receiving position on the central tower.
Alternately if the pointing technique chosen is to have the heliostats look at the source then this location is still used to define what direction the heliostat field is pointing towards. Pointing Technique
integer
This switch allows you to select one of two targeting modes for the heliostats.
This is the position to which the heliostat field will direct light. In general this should correspond with either the secondary mirror position or the detector position. It might however turn out to be advantageous when working with an off axis secondary configuration to move this point slightly from the center of the secondary.
Secondary Optics Parameters
Secondary Position
real vector
This is the position of the center of the secondary coordinate system in terms of the global coordinate system. This also corresponds to the center of the secondary mirror.Secondary Normal
real vector
This is the initial direction of the secondary mirror. If using the auto positioning routine this value will be superseded.
This sets the diameter of the secondary mirror.
This sets the focal length of the secondary.
Instrument Parameters
Detector Type
integer
There are currently two detector types available:
Detector Positioning
integer
This switch turns on or off the autofocus option.
Detector Position
real vector
This gives the position for the center of the detector coordinate system. Overridden by the use of the autofocus option.
Detector Normal
real vector
This gives the direction of the vector normal to the surface of the detector plane. Superseded by the use of the autofocus option.
Detector size
A two by three array of reals.
This is the size array that defines the extent of the detector surface.
I have written STARt to rely on the use of a command file primarily because command files make it very easy to keep records and to eventually automate the creation of the sort of databases that will be necessary to get any science done.
The command file has to do two things at the system environment level for STARt to run properly. First it has to set the values of the system variables that STARt looks for to determine its runtime behavior. Secondly it has to establish logical links connecting the actual files used for input and output to rather generic names that STARt actually attempts to access. Both of these could be done manually by the user however this would be a tedious job.
As of version 1.2 this was all that was required of the command file. However in version 1.3 I introduced another requirement on the commandfile. It now must also create the logfile which will be appended to (rather than created) by STARt. This was done to allow the logfileto contain information about which files STARt was directed to read and write to.
An example of the command file used to run STARt.
!necessary when submitting as batch jobs$ assign xxx sys$print ! set the working directory$ dir_shower = "dka100:[chrisg.shower]"$ dir_exec = "dka0:[chrisg.working.start]"$ dir_traces = "dka100:[chrisg.start]"$ dir_config = "dka100:[chrisg.start]"$ dir_hstat = "dka100:[chrisg.start]"! configuration$ iconf_root="test"$ fconfig = iconf_root + ".par"$ fhstat="example.hstat2"! shower characteristics$ fshower = "G50GEV0VPES.D04"$ pshx=0 $ pshy=0$ pshtype=1 ! runtime charactersitics$ psummary=0$ pshortfield=0 !for raytraceing $ fullfilename = dir_config + fconfig$ assign 'fullfilename' for031$ fullfilename = dir_shower + fshower$ assign 'fullfilename' for032 $ fullfilename = dir_hstat + fhstat$ assign 'fullfilename' for033$ fullfilename = dir_traces + iconf_root + ".DAT"$ assign 'fullfilename' for037$ fullfilename = dir_traces + iconf_root + ".LOG"$ assign 'fullfilename' for038$ fullfilename = dir_traces + iconf_root + ".SUM"$ assign 'fullfilename' for039!!! create and open the logfile$ DEFINE SYS$OUTPUT for038$ WRITE SYS$OUTPUT "Shower Logfile:" $ SHOW TIME $ WRITE SYS$OUTPUT "Executing binary files located in ''dir_exec'." $ WRITE SYS$OUTPUT "Config File Read in:"$ SHOW LOGICAL for031 $ WRITE SYS$OUTPUT "Shower File Read in:"$ SHOW LOGICAL for032 $ WRITE SYS$OUTPUT "Heliostat file read in:"$ SHOW LOGICAL for033 $ WRITE SYS$OUTPUT "Output DATA file:"$ SHOW LOGICAL for037 $ WRITE SYS$OUTPUT "Output LOG file:"$ SHOW LOGICAL for038 $ WRITE SYS$OUTPUT "Output SUM file:"$ SHOW LOGICAL for039$ DEASSIGN SYS$OUTPUT! run the raytracer$ run 'dir_exec'start$ exitSince STARt only accesses files through the vax fortran default filename of FORXXX it would be confusing not to arrive at a convention of what type of file is assigned what unit number.
In calculating the behavior of the ray as it bounces from one surface to the next inside the telescope the code deals with the ray from a variety of rotated and translated coordinate systems. It might help to take a moment to clarify which coordinate systems are used where. Whenever you specify a size array the size box is given in the local coordinates that you wish the computer to use on that component. When being positioned the component is allowed to rotate around the origin of this system.
Two coordinate systems are used in the output datafile. The ray reflection points are specified in the global telescope reference frame (the same set of coordinates used to specify the heliostat, secondary, and detector positions). The final output position is in terms of the detector coordinate system.
In addition to these a coordinate system is defined for each heliostat, each segment, and the secondary mirror. The heliostat coordinate system is always oriented such that y is in the plane that contains both the z (or mirror normal) and up vectors. So when you are looking at a heliostat deployed x is along the plane of the heliostat to the right, y is up the plane of the heliostat and z extends out of the face of the heliostat roughly towards the receiver tower.
Size arrays are used by STARt in several places. They derive from the techniques used to determine if a ray hits a given reflecting surface of the telescope. The surface in question is seen as the union between an abstract surface of the appropriate shape and a box which defines the actual extent of the surface in question. For example, when the code is asked to determine if an incoming photon hits a cylindrical mirror it first calculates the intersection point between that photon and an unbounded cylinder appropriately positioned so that the actual surface is some section of the cylinder. These intersection points are then compared with a box which defines that subsection of the array that actually exists. If the intersection point lies within the box then the ray would actually find a surface to reflect off of, otherwise the ray doesn't interact.
Size arrays are used to define these boxes. The box is defined in terms of a Cartesian coordinate system. If the box extends from coordinate a to coordinate bin the x direction and from c to d in the y direction and from e to f in the z direction then it is defined by the array (a,b,c,d,e,f). Generally speaking the origin of this coordinate system is the pivot point of the optical surface in question.
This page written July 18th 1997
(Last edited Oct. 13th 2005)