Table of Contents

Class StandardMaterial

Namespace
VirtualLabAPI.Core.Materials
Assembly
VirtualLabAPI.dll

Represents a standard material for absorption and different dispersion formulas including a constant Wavelength independent refractive index. This class is inherited from the abstract base class MaterialAbsorption that implements the absorption of most materials.

[Serializable]
public class StandardMaterial : MaterialAbsorptionBase, IDeserializationCallback, IEquatable<IObjectBase>, ICloneable, ISerializable
Inheritance
ObjectBase
SerializableObjectBase
ManualSerialization
StandardMaterial
Implements
IEquatable<IObjectBase>
Inherited Members

Constructors

StandardMaterial()

Default constructor, creates an empty material which means vacuum

public StandardMaterial()

StandardMaterial(double, bool)

Constructor that creates a material with constant real refractive index (absolutely defined) and no absorption

public StandardMaterial(double realRefractiveIndex, bool alwaysConstantRefractiveIndex = false)

Parameters

realRefractiveIndex double

Constant real refractive index

alwaysConstantRefractiveIndex bool

If this optional parameter is set to true the material is fixed to a constant refractive index. This only influences how it can be edited in the GUI.

StandardMaterial(string, double)

Constructor that creates a material with constant real refractive index (absolutely defined) and no absorption

public StandardMaterial(string name, double realRefractiveIndex)

Parameters

name string

Name of the material to instantiate

realRefractiveIndex double

Constant real refractive index

StandardMaterial(string, Complex)

Constructor that creates a material with constant real refractive index and constant absorption coefficient which is calculated from the imaginary part of the refractive index.

public StandardMaterial(string name, Complex refractiveIndex)

Parameters

name string

Name of the material to instantiate

refractiveIndex Complex

The refractive index of the material.

StandardMaterial(Complex, bool)

Constructor that creates a material with constant complex refractive index (absolutely defined)

public StandardMaterial(Complex refractiveIndex, bool alwaysConstantRefractiveIndex = false)

Parameters

refractiveIndex Complex

Constant complex refractive index

alwaysConstantRefractiveIndex bool

If this optional parameter is set to true the material is fixed to a constant refractive index. This only influences how it can be edited in the GUI.

Fields

DefaultMaximumWavelength

The (default) maximum wavelength for media with constant refractive index. Also used for all kinds of new materials. 100 km at the moment. The old maximum of 100µm was not applicable (see TT#7695 and #7676).

public static double DefaultMaximumWavelength

Field Value

double

DefaultMinimumWavelength

The (default) minimum wavelength for media with constant refractive index. Also used for all kinds of new materials. 1 pm in the moment.

public static double DefaultMinimumWavelength

Field Value

double

NameConstantMaterial

Name for a material having a constant refractive index.

public static string NameConstantMaterial

Field Value

string

NameConstantMaterialTemplate

Name template for a material having a constant refractive index.

public static string NameConstantMaterialTemplate

Field Value

string

_sampledRefractiveIndex

If DispersionFormula is SampledDispersion this DataArray1D contains the sampled dispersion function.

protected DataArray1D? _sampledRefractiveIndex

Field Value

DataArray1D

dispersionFormula

Dispersion formula.

protected DispersionFormula dispersionFormula

Field Value

DispersionFormula

Properties

AdditionalGlassData

Additional materials data like e.g. thermal data.

public AdditionalGlassData AdditionalGlassData { get; set; }

Property Value

AdditionalGlassData

Air

Static property for a quick access to air as material.

public static StandardMaterial Air { get; }

Property Value

StandardMaterial

Air_Zemax

Static property for a quick access to air (as defined in Zemax) as material.

public static StandardMaterial Air_Zemax { get; }

Property Value

StandardMaterial

AlwaysConstantRefractiveIndex

Gets and sets whether this material has always a constant refractive index. This flag influences only how it can be edited in the GUI (via "Constant Refractive Index" instead of as "Catalog Material").

public bool AlwaysConstantRefractiveIndex { get; set; }

Property Value

bool

ConstantRefractiveIndexValue

Gets and sets a constant refractive index for all wavelengths. To get this value the DispersionFormula has to set to ConstantRefractiveIndex or an Exception will be thrown. Setting this value will set the DispersionFormula to ConstantRefractiveIndex.

public double ConstantRefractiveIndexValue { get; set; }

Property Value

double

DataSourceInformationString

Gets and sets the information, where the materials data stem from, e.g. "Imported from 'Zemax OpticStudio®' - Glass Catalog file [file name].agf"

public string DataSourceInformationString { get; set; }

Property Value

string

DispersionFormula

Property to get and set the used dispersion formula for the refractive index calculation.

public DispersionFormula DispersionFormula { get; set; }

Property Value

DispersionFormula

FixedName

A name describing the parameter provider but which doesn't change if its parameters change.

public override string FixedName { get; }

Property Value

string

GlassCode

Determines the glass code of this material. If either nd or Vd cannot be calculated, an empty string will be returned.

public string GlassCode { get; }

Property Value

string

NumberOfParameters

Number of parameters as required for currently selected dispersion formula

public int NumberOfParameters { get; }

Property Value

int

ParameterDescriptions

Description of parameters as required for currently selected dispersion formula

public string[] ParameterDescriptions { get; }

Property Value

string[]

ParameterRunParameters

public property to get the parameters used for parameter run

public override List<Parameter> ParameterRunParameters { get; }

Property Value

List<Parameter>

Parameters

Parameters as required for currently selected dispersion formula

public double[] Parameters { get; set; }

Property Value

double[]

PartialPressureOfWaterVapour

Gets and sets the partial pressure of water vapor to be used with the Edlén formulas.

public double PartialPressureOfWaterVapour { get; set; }

Property Value

double

RefractiveIndexSamplingIsEquidistant

In case of an sampled refractive index this property gets whether the sampling is equidistant.

public bool RefractiveIndexSamplingIsEquidistant { get; }

Property Value

bool

SampledDataRestrictionsForImport

Static property to get those data array restrictions which are needed for a material's import from a text file.

public static DataArray1DRestrictions SampledDataRestrictionsForImport { get; }

Property Value

DataArray1DRestrictions

SampledRefractiveIndex

Gets and sets a DataArray1D containing a sampled dispersion function. Setting this value will set the DispersionFormula to SampledDispersion.

public DataArray1D SampledRefractiveIndex { get; set; }

Property Value

DataArray1D

SourceCodeSegmentRefractiveIndex

public property to set and get the string that represent the internal code segment to execute with the set up material (in case of programmable dispersion formula)

public string SourceCodeSegmentRefractiveIndex { get; set; }

Property Value

string

Methods

Clone()

Create deep copy of object

public override object Clone()

Returns

object

CreateMaterialFrom_AbbeNumber_IndexNd_PartialDispersion(double, double, double, bool)

Method which creates a programmable material where the dispersion is given by the refractive index \(n_d\), the Abbe number \(\nu_d\) and the partial dispersion deviation \(\Delta P_{gF}\). This is needed especially for importing Zemax 'Model Glasses'. Important: The related dispersion formula is not identical to DispersionFormula.AbbeNumber_old nor DispersionFormula.AbbeNumber_new. Those formulas are simpler Cauchy formulas using no partial dispersion term.

public static StandardMaterial CreateMaterialFrom_AbbeNumber_IndexNd_PartialDispersion(double abbeVd, double indexNd, double dPgF, bool useZemaxFormulas)

Parameters

abbeVd double

Abbe number \(\nu_d\).

indexNd double

Refractive index \(n_d\) for Fraunhofer line d.

dPgF double

Partial dispersion deviation \(\Delta P_gF\).

useZemaxFormulas bool

We have two sets of formulas producing slightly different results for the dispersion. Both can be found in Internal Technical Note ITN.059. This flag tells whether to use the set of formulas given to us by Sanjay Gangadhara from Zemax.

Returns

StandardMaterial

A programmable material defined by the given parameters.

Equals(object?, EqualityIntent)

compares two materials

public override bool Equals(object? obj, EqualityIntent equalityIntent)

Parameters

obj object

material to compare with.

equalityIntent EqualityIntent

Defines what kind of equality you want to check when comparing two objects, for example all values or physical equality.

Returns

bool

TRUE if they are equal.

GetHashCode()

Serves as the default hash function.

public override int GetHashCode()

Returns

int

A hash code for the current object. Only those parameters are used which most likely differ between different objects. If hash code is equal, Equals(object?, EqualityIntent) is called anyhow.

GetRealRefractiveIndexAsDefined(double, bool, double, double, double)

Returns the refractive index for the specified wavelength (as measured in reference material).

public override double GetRealRefractiveIndexAsDefined(double wavelengthInReferenceMaterial, bool checkForValidWavelengthRange = true, double vacuumWavelengthIfKnown = 0, double temperatureInDegrees = 20, double pressureInPascal = 101325)

Parameters

wavelengthInReferenceMaterial double

Wavelength (as measured in reference material) for that the refractive index should be returned for.

checkForValidWavelengthRange bool

If false, no check is done whether the wavelength is valid. This option should ever be true, except for the case of calculating the vacuum wavelength, where a stack overflow has to be avoided.

vacuumWavelengthIfKnown double

If known and checkForValidWavelengthRange == true, the vacuum wavelength must not be calculated again for checking the valid wavelength range.

temperatureInDegrees double

Optional temperature in degrees.

pressureInPascal double

Optional pressure in pascals (if the material is a gas).

Returns

double

Refractive index for the given wavelength.

Exceptions

WavelengthOutOfRangeException
WavelengthOutOfRangeException
NoSampledDispersionException
RefractiveIndexNotGreaterZeroException

GetRealRefractiveIndexMinMaxWavelength(out double, out double, bool)

Returns wavelength range for that a refractive index is available. If giveVacuumWavelengths is true, the values are vacuum wavelengths, otherwise they refer to the reference material.

public override void GetRealRefractiveIndexMinMaxWavelength(out double minWavelength, out double maxWavelength, bool giveVacuumWavelengths)

Parameters

minWavelength double

Minimum Wavelength.

maxWavelength double

Maximum Wavelength.

giveVacuumWavelengths bool

If true, the wavelength range of the reference material's refractive index will be considered, and vacuum wavelengths will be returned. If the material is defined absolutely, the parameter will be ignored.

ImportMaterialFromZemaxCatalog(StreamReader, string, string, bool)

Imports a given material from a Zemax glass catalog specified by a StreamReader object. This method should be used if multiple materials are to be imported at once.

public static (ICatalogEntry entry, string warning)? ImportMaterialFromZemaxCatalog(StreamReader glassCatalog, string materialName, string additionalCatalogNameString, bool noSourceString)

Parameters

glassCatalog StreamReader

StreamReader for the Zemax glass catalog.

materialName string

Name of material to be imported

additionalCatalogNameString string

Additional string which will be appended to the material's name in order to mark which glass catalog it stems from

noSourceString bool

If true, no source string will be written to the material.

Returns

(ICatalogEntry entry, string warning)?

The imported material. Null if the material couldn't be found in the glassCatalog.

ImportMaterialFromZemaxCatalog(string, string, string)

Imports a given material from a Zemax glass catalog specified by a file path. This method should be used if only a single material is to be imported.

public static (ICatalogEntry entry, string warning)? ImportMaterialFromZemaxCatalog(string agfFileName, string materialName, string additionalCatalogNameString)

Parameters

agfFileName string

Path to .agf file

materialName string

Name of material to be imported

additionalCatalogNameString string

Additional string which will be appended to the material's name in order to mark which glass catalog it stems from

Returns

(ICatalogEntry entry, string warning)?

The imported material. Null if the material couldn't be found in the glassCatalog.

IsConsistent(out ArrayList)

Check consistency of material

public override bool IsConsistent(out ArrayList messageList)

Parameters

messageList ArrayList

Array of ConsistenyErrorOrWarning objects

Returns

bool

True if there is no error

ParametersValidForDispersionFormula(out bool, out string)

Checks if the parameters are usable with the given dispersion formula

public bool ParametersValidForDispersionFormula(out bool exactCheck, out string errorMessage)

Parameters

exactCheck bool

true if roots can be determined analytically, so the check is 100 percent reliable if the return value of the method is TRUE. If the method's return value is FALSE, this is reliable in every case.

errorMessage string

Out parameter to return a meaningful error message. Can be an empty string if there is no specific error message.

Returns

bool

True, if no error could be found

Exceptions

ArgumentException

Dispersion formula unknown.

SetRefractiveIndexMinMaxWavelength(double, double)

Sets the wavelength range in that the selected dispersion formula gives correct refractive index results. The wavelength parameters have to be medium wavelengths in case of a relatively defined refractive index.

public void SetRefractiveIndexMinMaxWavelength(double minWavelength, double maxWavelength)

Parameters

minWavelength double

Minimum wavelength in reference material.

maxWavelength double

Maximum wavelength in reference material.