Interfaces and methods for running a non-sequential ray trace. This interface can be accessed via the IOpticalSystemTools interface. NOTE - due to architectural limitations, currently only one INSCRayTrace instance can be used at a time, across all IOpticalSystem instances. The first call to IOpticalSystemTools.OpenNSCRayTrace will succeed, while all further calls will return null until the the single INSCRayTrace instance is closed. It is anticipated that this limiation will be removed in future versions of the API. More...

Inheritance diagram for ZOSAPI.Tools.RayTrace.INSCRayTrace:

[legend]

Public Member Functions
ErrorType	ClearDetectors (int DetectorNumber)
	Clears the specified detectors.

ErrorType	ClearDetectorObject (int ObjectNumber)
	Clears the detector data on the specified object.

double	GetTotalRayEnergy ()

void	SetRandomSeed (int seed)
	Usually the NSC Ray Trace uses a new random seed each time it is run. This function allows the user to explicitly set the random seed that is used, in order to trace a reproducible set of rays.

void	ResetRandomSeed ()
	Clear any previously set random seed, so that each new ray trace uses a new random seed value.

void	SetPartialRTMode (int seed, int group)

bool	EstimateHPCTime ()

Public Member Functions inherited from ZOSAPI.Tools.ISystemTool
bool	Run ()
	Start the tool. Note that for synchronous tools (see IsAsynchronous), this call will block until completion. If it is asynchronous it will start running but return immediately.

bool	RunAndWaitForCompletion ()
	Sames as calling Run followed by WaitForCompletion.

bool	WaitForCompletion ()
	Waits for the asynchronous tool to complete.

bool	Cancel ()
	Cancels the currently running asynchronous tool.

bool	Close ()
	Closes this tool and frees up and associated resources.

RunStatus	WaitWithTimeout (double timeOutSeconds)
	Waits for the currently running tool to complete, with a specified time out value. Note that if the timeout is exceeded this method will return, however the tool will continue to run. Also note that this method will not start the tool running if it is not already.

RunStatus	RunAndWaitWithTimeout (double timeOutSeconds)
	Starts the tool running, and waits for it to complete with the specified timeout value. Note that if the timeout is exceeded this method will return, however the tool will continue to run.

Properties
bool	AutoUpdate `[get, set]`

int	NumberOfCores `[get, set]`

bool	UsePolarization `[get, set]`

bool	IgnoreErrors `[get, set]`

bool	SplitNSCRays `[get, set]`

bool	ScatterNSCRays `[get, set]`

bool	SaveRays `[get, set]`

string	SaveRaysFile `[get, set]`
	Gets or sets the save rays filename (only used when SaveRays is `true`).

bool	SavePaths `[get, set]`

string	SavePathsFile `[get, set]`
	Gets or sets the save rays filename (only used when SavePaths is `true`).

ZRDFormatType	ZRDFormat `[get, set]`

string	Filter `[get, set]`

double	DeadRayErrors `[get]`

double	DeadRayThreshold `[get]`

bool	IsHPCEnabled `[get]`

double	HPCEstimatedTimeS `[get]`

double	HPCRemainingTimeS `[get]`

double	HPCTimeToStartS `[get]`

int	HPCQueuePosition `[get]`

HPCRunState	HPCState `[get]`

bool	HPCHasTimeEstimate `[get]`

double	RayMultiplier `[get, set]`

bool	HasHPCUnsupportedDetectors `[get]`

Properties inherited from ZOSAPI.Tools.ISystemTool
int	Progress `[get]`
	Gets the progress of the current tool, if supported.

string	Status `[get]`
	Gets the status of the current tool, if supporoted.

bool	IsRunning `[get]`
	Gets a value indicating whether the tool is currently running asynchronously.

bool	CanCancel `[get]`
	Gets a value indicating whether the tool can be cancelled.

bool	IsAsynchronous `[get]`
	Gets a value indicating whether the tool runs asynchronously (i.e. on a thread).

bool	IsFiniteDuration `[get]`
	Gets a value indicating whether this tool will complete on its own.

bool	IsValid `[get]`
	Gets a value indicating whether the input settings are valid.

bool	Succeeded `[get]`
	Gets a value indicating whether the tool execution succeeded.

string	ErrorMessage `[get]`
	If Succeeded is `false`, get the error messages; otherwise, `null`.

Detailed Description

Interfaces and methods for running a non-sequential ray trace. This interface can be accessed via the IOpticalSystemTools interface. NOTE - due to architectural limitations, currently only one INSCRayTrace instance can be used at a time, across all IOpticalSystem instances. The first call to IOpticalSystemTools.OpenNSCRayTrace will succeed, while all further calls will return null until the the single INSCRayTrace instance is closed. It is anticipated that this limiation will be removed in future versions of the API.

Usage (see Example 17 for a full sample)

C#

            //Run a ray trace
            INSCRayTrace NSCRayTrace = TheSystem.Tools.OpenNSCRayTrace();
            NSCRayTrace.SplitNSCRays = false;
            NSCRayTrace.ScatterNSCRays = true;
            NSCRayTrace.UsePolarization = false;
            NSCRayTrace.IgnoreErrors = true;
            NSCRayTrace.SaveRays = false;
 
            NSCRayTrace.ClearDetectors(0);
            NSCRayTrace.RunAndWaitForCompletion();
            NSCRayTrace.Close();

C++

    //Run a ray trace
    INSCRayTracePtr  NSCRayTrace = TheSystem->Tools->OpenNSCRayTrace();
    NSCRayTrace->SplitNSCRays = false;
    NSCRayTrace->ScatterNSCRays = true;
    NSCRayTrace->UsePolarization = false;
    NSCRayTrace->IgnoreErrors = true;
    NSCRayTrace->SaveRays = false;
 
    NSCRayTrace->ClearDetectors(0);
    // The method RunAndWaitForCompletion() and Close() are inehrited from base interface ISystemToolPtr. To use these methods, first cast to ISystemTool.
    ISystemToolPtr baseTool = NSCRayTrace;
    baseTool->RunAndWaitForCompletion();
    baseTool->Close();

Matlab

    % Run a ray trace
    NSCRayTrace = TheSystem.Tools.OpenNSCRayTrace();
    NSCRayTrace.SplitNSCRays = false;
    NSCRayTrace.ScatterNSCRays = true;
    NSCRayTrace.UsePolarization = false;
    NSCRayTrace.IgnoreErrors = true;
    NSCRayTrace.SaveRays = false;
    NSCRayTrace.ClearDetectors(0);
    NSCRayTrace.RunAndWaitForCompletion();
    NSCRayTrace.Close();

Python

    # Run a ray trace
    NSCRayTrace = TheSystem.Tools.OpenNSCRayTrace()
    NSCRayTrace.SplitNSCRays = False
    NSCRayTrace.ScatterNSCRays = True
    NSCRayTrace.UsePolarization = False
    NSCRayTrace.IgnoreErrors = True
    NSCRayTrace.SaveRays = False
    NSCRayTrace.ClearDetectors(0)
    NSCRayTrace.RunAndWaitForCompletion()
    NSCRayTrace.Close()

Examples: CSharpStandalone_02_NSC_ray_trace.cs, CSharpStandalone_05_Read_ZRD_File.cs, CSharpStandalone_06_nsc_phase.cs, CSharpStandalone_08_NSCEDetectorData.cs, CSharpStandalone_10_NSC_ZRD_filter_string.cs, CSharpStandalone_17_NSC_BulkScatter.cs, CSharpStandalone_21_White_LED_Phosphor.cs, CSharpStandalone_24_nsc_detectors.cs, and CSharpStandalone_25_source_spectrum_diffraction_grating.cs.

Member Function Documentation

◆ ClearDetectorObject()

ErrorType ZOSAPI.Tools.RayTrace.INSCRayTrace.ClearDetectorObject ( int ObjectNumber )

Clears the detector data on the specified object.

Parameters

ObjectNumber object number of the detector to clear. Use 0 for all detectors.

◆ ClearDetectors()

ErrorType ZOSAPI.Tools.RayTrace.INSCRayTrace.ClearDetectors ( int DetectorNumber )

Clears the specified detectors.

Usage (see Example 02 for a full sample)

C#

            // Create ray trace
            INSCRayTrace NSCRayTrace = TheSystem.Tools.OpenNSCRayTrace();
            NSCRayTrace.SplitNSCRays = true;
            NSCRayTrace.ScatterNSCRays = false;
            NSCRayTrace.UsePolarization = true;
            NSCRayTrace.IgnoreErrors = true;
            NSCRayTrace.SaveRays = false;
 
            // Run ray trace
            NSCRayTrace.RunAndWaitForCompletion();
            NSCRayTrace.Close();

C++

    // Creat ray trace
    INSCRayTracePtr NSCRayTrace = TheSystem->Tools->OpenNSCRayTrace();
    NSCRayTrace->SplitNSCRays = true;
    NSCRayTrace->ScatterNSCRays = false;
    NSCRayTrace->UsePolarization = true;
    NSCRayTrace->IgnoreErrors = true;
    NSCRayTrace->SaveRays = false;
    NSCRayTrace->ClearDetectors(0);
 
    // Run ray trace
    // Methods RunAndWaitForCompletion() and Close is in base interface ISystemTool.
    // To use these two methods, cast to ISystemTool first.
    ISystemToolPtr baseTool = NSCRayTrace;
    baseTool->RunAndWaitForCompletion();
    baseTool->Close();

Matlab

    % Create ray trace
    NSCRayTrace = TheSystem.Tools.OpenNSCRayTrace();
    NSCRayTrace.SplitNSCRays = true;
    NSCRayTrace.ScatterNSCRays = false;
    NSCRayTrace.UsePolarization = true;
    NSCRayTrace.IgnoreErrors = true;
    NSCRayTrace.SaveRays = false;
    NSCRayTrace.ClearDetectors(0);
  
    % Run ray trace
    NSCRayTrace.RunAndWaitForCompletion();
    NSCRayTrace.Close();

Python

    # Create ray trace
    NSCRayTrace = TheSystem.Tools.OpenNSCRayTrace()
    NSCRayTrace.SplitNSCRays = True
    NSCRayTrace.ScatterNSCRays = False
    NSCRayTrace.UsePolarization = True
    NSCRayTrace.IgnoreErrors = True
    NSCRayTrace.SaveRays = False
    NSCRayTrace.Run()

Parameters

DetectorNumber number of the detector to clear. Use 0 for all detectors. Note that detector number 1 is the first object that functions as a detector, not object number 1. To clear a specific object, use ClearDetectorObject.///

Examples: CSharpStandalone_05_Read_ZRD_File.cs, CSharpStandalone_06_nsc_phase.cs, CSharpStandalone_10_NSC_ZRD_filter_string.cs, CSharpStandalone_17_NSC_BulkScatter.cs, CSharpStandalone_21_White_LED_Phosphor.cs, CSharpStandalone_24_nsc_detectors.cs, and CSharpStandalone_25_source_spectrum_diffraction_grating.cs.

◆ EstimateHPCTime()

bool ZOSAPI.Tools.RayTrace.INSCRayTrace.EstimateHPCTime ( )

◆ GetTotalRayEnergy()

double ZOSAPI.Tools.RayTrace.INSCRayTrace.GetTotalRayEnergy ( )

◆ ResetRandomSeed()

void ZOSAPI.Tools.RayTrace.INSCRayTrace.ResetRandomSeed ( )

Clear any previously set random seed, so that each new ray trace uses a new random seed value.

◆ SetPartialRTMode()

void ZOSAPI.Tools.RayTrace.INSCRayTrace.SetPartialRTMode	(	int	seed,
		int	group
	)

◆ SetRandomSeed()

void ZOSAPI.Tools.RayTrace.INSCRayTrace.SetRandomSeed ( int seed )

Usually the NSC Ray Trace uses a new random seed each time it is run. This function allows the user to explicitly set the random seed that is used, in order to trace a reproducible set of rays.

Parameters

seed	Any non-zero seed value

Property Documentation

◆ AutoUpdate

bool ZOSAPI.Tools.RayTrace.INSCRayTrace.AutoUpdate

getset

◆ DeadRayErrors

double ZOSAPI.Tools.RayTrace.INSCRayTrace.DeadRayErrors

get

◆ DeadRayThreshold

double ZOSAPI.Tools.RayTrace.INSCRayTrace.DeadRayThreshold

get

◆ Filter

string ZOSAPI.Tools.RayTrace.INSCRayTrace.Filter

getset

◆ HasHPCUnsupportedDetectors

bool ZOSAPI.Tools.RayTrace.INSCRayTrace.HasHPCUnsupportedDetectors

get

◆ HPCEstimatedTimeS

double ZOSAPI.Tools.RayTrace.INSCRayTrace.HPCEstimatedTimeS

get

◆ HPCHasTimeEstimate

bool ZOSAPI.Tools.RayTrace.INSCRayTrace.HPCHasTimeEstimate

get

◆ HPCQueuePosition

int ZOSAPI.Tools.RayTrace.INSCRayTrace.HPCQueuePosition

get

◆ HPCRemainingTimeS

double ZOSAPI.Tools.RayTrace.INSCRayTrace.HPCRemainingTimeS

get

◆ HPCState

HPCRunState ZOSAPI.Tools.RayTrace.INSCRayTrace.HPCState

get

◆ HPCTimeToStartS

double ZOSAPI.Tools.RayTrace.INSCRayTrace.HPCTimeToStartS

get

◆ IgnoreErrors

bool ZOSAPI.Tools.RayTrace.INSCRayTrace.IgnoreErrors

getset

Usage (see Example 02 for a full sample)

C#

            // Create ray trace
            INSCRayTrace NSCRayTrace = TheSystem.Tools.OpenNSCRayTrace();
            NSCRayTrace.SplitNSCRays = true;
            NSCRayTrace.ScatterNSCRays = false;
            NSCRayTrace.UsePolarization = true;
            NSCRayTrace.IgnoreErrors = true;
            NSCRayTrace.SaveRays = false;
 
            // Run ray trace
            NSCRayTrace.RunAndWaitForCompletion();
            NSCRayTrace.Close();

C++

    // Creat ray trace
    INSCRayTracePtr NSCRayTrace = TheSystem->Tools->OpenNSCRayTrace();
    NSCRayTrace->SplitNSCRays = true;
    NSCRayTrace->ScatterNSCRays = false;
    NSCRayTrace->UsePolarization = true;
    NSCRayTrace->IgnoreErrors = true;
    NSCRayTrace->SaveRays = false;
    NSCRayTrace->ClearDetectors(0);
 
    // Run ray trace
    // Methods RunAndWaitForCompletion() and Close is in base interface ISystemTool.
    // To use these two methods, cast to ISystemTool first.
    ISystemToolPtr baseTool = NSCRayTrace;
    baseTool->RunAndWaitForCompletion();
    baseTool->Close();

Matlab

    % Create ray trace
    NSCRayTrace = TheSystem.Tools.OpenNSCRayTrace();
    NSCRayTrace.SplitNSCRays = true;
    NSCRayTrace.ScatterNSCRays = false;
    NSCRayTrace.UsePolarization = true;
    NSCRayTrace.IgnoreErrors = true;
    NSCRayTrace.SaveRays = false;
    NSCRayTrace.ClearDetectors(0);
  
    % Run ray trace
    NSCRayTrace.RunAndWaitForCompletion();
    NSCRayTrace.Close();

Python

    # Create ray trace
    NSCRayTrace = TheSystem.Tools.OpenNSCRayTrace()
    NSCRayTrace.SplitNSCRays = True
    NSCRayTrace.ScatterNSCRays = False
    NSCRayTrace.UsePolarization = True
    NSCRayTrace.IgnoreErrors = True
    NSCRayTrace.SaveRays = False
    NSCRayTrace.Run()

◆ IsHPCEnabled

bool ZOSAPI.Tools.RayTrace.INSCRayTrace.IsHPCEnabled

get

◆ NumberOfCores

int ZOSAPI.Tools.RayTrace.INSCRayTrace.NumberOfCores

getset

◆ RayMultiplier

double ZOSAPI.Tools.RayTrace.INSCRayTrace.RayMultiplier

getset

◆ SavePaths

bool ZOSAPI.Tools.RayTrace.INSCRayTrace.SavePaths

getset

◆ SavePathsFile

string ZOSAPI.Tools.RayTrace.INSCRayTrace.SavePathsFile

getset

Gets or sets the save rays filename (only used when SavePaths is true).

The save paths filename. Note - only the file name will be used, not any path information; it will be saved in the directory of the lens file.

◆ SaveRays

bool ZOSAPI.Tools.RayTrace.INSCRayTrace.SaveRays

getset

Usage (see Example 06 for a full sample)

C#

            // Setup and run the ray trace
            ZOSAPI.Tools.RayTrace.INSCRayTrace NSCRayTrace = TheSystem.Tools.OpenNSCRayTrace();
            NSCRayTrace.SplitNSCRays = false;
            NSCRayTrace.ScatterNSCRays = true;
            NSCRayTrace.UsePolarization = false;
            NSCRayTrace.IgnoreErrors = true;
            NSCRayTrace.SaveRays = false;
            NSCRayTrace.ClearDetectors(0);
 
            NSCRayTrace.RunAndWaitForCompletion();
            NSCRayTrace.Close();

C++

    // Setup and run the ray trace
    INSCRayTracePtr NSCRayTrace = TheSystem->Tools->OpenNSCRayTrace();
    NSCRayTrace->SplitNSCRays = false;
    NSCRayTrace->ScatterNSCRays = true;
    NSCRayTrace->UsePolarization = false;
    NSCRayTrace->IgnoreErrors = true;
    NSCRayTrace->SaveRays = false;
    NSCRayTrace->ClearDetectors(0);
 
    ((ISystemToolPtr)NSCRayTrace)->RunAndWaitForCompletion();
    ((ISystemToolPtr)NSCRayTrace)->Close();

Matlab

    % Setup and run the ray trace
    NSCRayTrace = TheSystem.Tools.OpenNSCRayTrace();
    NSCRayTrace.SplitNSCRays = false;
    NSCRayTrace.ScatterNSCRays = true;
    NSCRayTrace.UsePolarization = false;
    NSCRayTrace.IgnoreErrors = true;
    NSCRayTrace.SaveRays = false;
    NSCRayTrace.ClearDetectors(0);
    
    NSCRayTrace.RunAndWaitForCompletion();
    NSCRayTrace.Close();

Python

    # Setup and run the ray trace
    NSCRayTrace = TheSystem.Tools.OpenNSCRayTrace()
    NSCRayTrace.SplitNSCRays = False
    NSCRayTrace.ScatterNSCRays = True
    NSCRayTrace.UsePolarization = False
    NSCRayTrace.IgnoreErrors = True
    NSCRayTrace.SaveRays = False
    NSCRayTrace.ClearDetectors(0)
 
    NSCRayTrace.RunAndWaitForCompletion()
    NSCRayTrace.Close()

◆ SaveRaysFile

string ZOSAPI.Tools.RayTrace.INSCRayTrace.SaveRaysFile

getset

Gets or sets the save rays filename (only used when SaveRays is true).

The save rays filename. Note - only the file name will be used, not any path information; it will be saved in the directory of the lens file.

◆ ScatterNSCRays

bool ZOSAPI.Tools.RayTrace.INSCRayTrace.ScatterNSCRays

getset

◆ SplitNSCRays

bool ZOSAPI.Tools.RayTrace.INSCRayTrace.SplitNSCRays

getset

◆ UsePolarization

bool ZOSAPI.Tools.RayTrace.INSCRayTrace.UsePolarization

getset

◆ ZRDFormat

ZRDFormatType ZOSAPI.Tools.RayTrace.INSCRayTrace.ZRDFormat

getset

ZOS-API interface 2024 R1

ZOSAPI.Tools.RayTrace.INSCRayTrace Interface Reference

Public Member Functions

Properties

Detailed Description

Member Function Documentation

◆ ClearDetectorObject()

◆ ClearDetectors()

◆ EstimateHPCTime()

◆ GetTotalRayEnergy()

◆ ResetRandomSeed()

◆ SetPartialRTMode()

◆ SetRandomSeed()

Property Documentation

◆ AutoUpdate

◆ DeadRayErrors

◆ DeadRayThreshold

◆ Filter

◆ HasHPCUnsupportedDetectors

◆ HPCEstimatedTimeS

◆ HPCHasTimeEstimate

◆ HPCQueuePosition

◆ HPCRemainingTimeS

◆ HPCState

◆ HPCTimeToStartS

◆ IgnoreErrors

◆ IsHPCEnabled

◆ NumberOfCores

◆ RayMultiplier

◆ SavePaths

◆ SavePathsFile

◆ SaveRays

◆ SaveRaysFile

◆ ScatterNSCRays

◆ SplitNSCRays

◆ UsePolarization

◆ ZRDFormat

Connect with Ansys