The CSTResultReader.dll offers an interface for accessing CST MICROWAVE STUDIO / CST EM STUDIO / CST PARTICLE STUDIO / CST MPHYSICS STUDIO results without the need of opening the project in one of the CST STUDIO SUITE programs.
The DLL can be used for instance in Matlab® or in any custom written program for Microsoft Windows®.
All necessary files can be found in "<Installation path>\ResultReaderDLL".
Functions:
Accessing 3D-Field results for Hexahedral grids
Accessing symmetries / boundaries
Examples:
Using CSTResultReader.dll from within Matlab
Using CSTResultReader.dll from within a Windows based C/C++ program
Before being able to access a specific CST STUDIO result via one of the DLL functions, a "CST project handle" needs to be created. All functions that return information/data of a CST project take such a handle as an argument. Whenever a project handle is no longer needed it must be closed.
A second very common argument is the name of a result tree item. This name specifies the type of result being returned. It is the same name as seen in the result tree of CST MICROWAVE STUDIO / CST EM STUDIO / CST PARTICLE STUDIO / CST MPHYSICS STUDIO. In some cases, only the "root" tree item name must be given. If, for instance, the values of an electric field monitor are in question, its corresponding folder must be given, not its child entries such as "X", "Y", "Z" or "Abs".
Since some result tree entries may hold multiple results, the desired result must be further specified by an integer. There is a function to obtain the total number of results available in one tree item.
None of the functions allocates memory. All pointers that are given as [out] arguments to a function must point to a valid memory block of proper size.
All functions return zero if the call has been successful.
A value greater 0 corresponds to one of the following error codes:
|
1 |
Unknown |
|
2 |
File not found. |
|
3 |
The given project file is not a valid .cst file |
|
4 |
The given result tree item could not be found. |
|
5 |
The requested result does not correspond to the result stored in the given result tree item name. |
|
6 |
Error in one of the given function arguments. |
|
7 |
Requested result type is incompatible with this DLL. |
|
8 |
Memory error. |
|
9 |
Unsupported mesh type. |
|
10 |
Version conflict. |
|
int CST_GetDLLVersion( |
[out] int* nVersion ) |
Description: Returns the version number of the DLL. Corresponds to the version number of the CST STUDIO SUITE it was delivered with.
Arguments (input):
-
Arguments (output):
|
nVersion: |
Version number of the DLL. |
|
int CST_OpenProject( |
[in] char const *cProjPath, |
|
|
[in] CSTProjHandle *projHandle ) |
Description: Opens the specified CST project for further operation in the result reader DLL under the given handle and returns zero in case of no error.
Arguments (input):
|
cProjPath: |
Name of the CST file including path that should be opened by the DLL. |
|
projHandle: |
Handle to which the specified CST project should be assigned. |
Arguments (output):
-
|
int CST_CloseProject( |
[in] CSTProjHandle *projHandle ) |
Description: Closes the CST project under the given handle and resets the handle.
Arguments (input):
|
cProjPath: |
Handle of the CST project to be closed. |
Arguments (output):
-
|
int CST_GetNumberOfResults( |
[in] CSTProjHandle const *projHandle, |
|
|
[in] char const *cTreePathName, |
|
|
[out] int *nResultNumber ) |
Description: Returns the total number of results available for the selected result tree item.
Arguments (input):
|
projHandle: |
Handle to the desired CST project. |
|
cTreePathName: |
Name of the result tree item of the desired result. |
Arguments (output):
|
nResultNumber: |
Total number of available results. Will be 1 in most cases. |
|
int CST_Get1DResultInfo( |
[in] CSTProjHandle const *projHandle, |
|
|
[in] char const *cTreePathName, |
|
|
[in] int iResultNumber, |
|
|
[in] infoArraySize, |
|
|
[in] charBufferSize, |
|
|
[out] char *cInfo, |
|
|
[out] int *iInfo, |
|
|
[out] double *dInfo ) |
Description: Returns additional info of the selected 1D result.
Arguments (input):
|
projHandle: |
Handle to the desired CST project. |
|
cTreePathName: |
Name of the result tree item of the desired result. |
|
iResultNumber: |
A number identifying the desired result |
|
infoArraySize: |
Size of the given info array. All available information will be copied into the info arrays up to this number. Currently not used. |
|
charBufferSize: |
Size of the given "char" buffer in the cInfo array. All characters of an available info strings will be copied to cInfo up to this number. Currently not used |
Arguments (output):
|
cInfo: |
Currently not used. |
|
iInfo: |
Currently not used. |
|
dInfo: |
Currently not used. |
|
int CST_Get1DResultSize( |
[in] CSTProjHandle const *projHandle, |
|
|
[in] char const *cTreePathName, |
|
|
[in] int iResultNumber, |
|
|
[out] int *nDataSize ) |
Description: Returns the size of the selected 1D result. If a 2 component result is selected, the returned size will be
twice as large as for a 1 component result.
Arguments (input):
|
projHandle: |
Handle to the desired CST project. |
|
cTreePathName: |
Name of the result tree item of the desired result. |
|
iResultNumber: |
A number identifying the desired result. |
Arguments (output):
|
nDataSize: |
Size of the requested result vector. |
|
int CST_Get1DRealDataAbszissa( |
[in] CSTProjHandle const *projHandle, |
|
|
[in] char const *cTreePathName, |
|
|
[in] int iResultNumber, |
|
|
[out] double *dData ) |
Description: Returns the abszissa values of a 1D-function.
Arguments (input):
|
projHandle: |
Handle to the desired CST project. |
|
cTreePathName: |
Name of the result tree item of the desired result. |
|
iResultNumber: |
A number identifying the desired result. Some tree result entries may contain more than one result like tables for instance. |
Arguments (output):
|
dData: |
Pointer to a memory block to be filled with the result values. |
|
int CST_Get1DRealDataOrdinate( |
[in] CSTProjHandle const *projHandle, |
|
|
[in] char const *cTreePathName, |
|
|
[in] int iResultNumber, |
|
|
[out] double *dData ) |
Description: Returns ordinate values of a real 1D-function.
Arguments (input):
|
projHandle: |
Handle to the desired CST project. |
|
cTreePathName: |
Name of the result tree item of the desired result. |
|
iResultNumber: |
A number identifying the desired result. Some tree result entries may contain more than one result like tables for instance. |
Arguments (output):
|
dData: |
Pointer to a memory block to be filled with the result values. |
|
int CST_Get1D_2Comp_DataOrdinate( |
[in] CSTProjHandle const *projHandle, |
|
|
[in] char const *cTreePathName, |
|
|
[in] int iResultNumber, |
|
|
[out] double *dData ) |
Description: Returns ordinate values of a two component 1D-function. Use this function for polar plot result items.
Arguments (input):
|
projHandle: |
Handle to the desired CST project. |
|
cTreePathName: |
Name of the result tree item of the desired result. |
|
iResultNumber: |
A number identifying the desired result. Some tree result entries may contain more than one result like tables for instance. |
Arguments (output):
|
dData: |
Pointer to a memory block to be filled with the result values. The data structure is the following: dData[0] = value1_Comp1 dData[1] = value1_Comp2 dData[2] = value2_Comp1 dData[3] = value2_Comp2 . . |
|
int CST_GetPortImpedance( |
[in] CSTProjHandle const *projHandle, |
|
|
[in] int iPortNumber, |
|
|
[in] int iModeNumber, |
|
|
[in] int nFreq, |
|
|
[in] double const *freq, |
|
|
[out] double *dPortImpData ) |
Description: Returns port impedances for a given list of frequencies.
Arguments (input):
|
projHandle: |
Handle to the desired CST project. |
|
iPortNumber: |
The desired port. |
|
iModeNumber: |
The desired mode name, if the port is a wave guide port |
|
nFreq: |
The total number of given frequencies. |
|
freq: |
Frequency values for which the port impedance is to be returned. |
Arguments (output):
|
dPortImpData: |
Pointer to a memory block to be filled with the port impedances. The data structure is the following: dData[0] = real_part_for_freq1 dData[1] = imaginary_part_for_freq1 dData[2] = real_part_for_freq2 dData[3] = imaginary_part_for_freq2 . . |
Subgrids and TST are not supported. Also, 3D-Field monitors on a 2D-Plane are currently not supported.
|
int CST_Get3DHexResultInfo( |
[in] CSTProjHandle const *projHandle, |
|
|
[in] char const *cTreePathName, |
|
|
[in] int iResultNumber, |
|
|
[in] infoArraySize, |
|
|
[in] charBufferSize, |
|
|
[out] char *cInfo, |
|
|
[out] int *iInfo, |
|
|
[out] double *dInfo ) |
Description: Returns additional info of the selected 3D result.
Arguments (input):
|
projHandle: |
Handle to the desired CST project. |
|
cTreePathName: |
Name of the result tree item of the desired result. |
|
iResultNumber: |
A number identifying the desired result. |
|
infoArraySize: |
Size of the given info array. All available information will be copied into the info arrays up to this number. |
|
charBufferSize: |
Size of the given "char" buffer in the cInfo array. All characters of an available info strings will be copied to cInfo up to this number. |
Arguments (output):
|
cInfo: |
Currently not used. |
|
iInfo[0] : |
Monitor type. 1: Result is a 3D complex vector field 2: Result is a 3D real vector field 3: Result is a 3D complex scalar field 4: Result is a 3D real scalar field |
|
dInfo: |
Currently not used. |
|
int CST_Get3DHexResultSize( |
[in] CSTProjHandle const *projHandle, |
|
|
[in] char const *cTreePathName, |
|
|
[in] int iResultNumber, |
|
|
[out] int *nDataSize ) |
Description: Returns the size of the selected 3D result.
Arguments (input):
|
projHandle: |
Handle to the desired CST project. |
|
cTreePathName: |
Name of the result tree item of the desired result. |
|
iResultNumber: |
A number identifying the desired result. |
Arguments (output):
|
nDataSize: |
Size of the requested result vector. |
|
int CST_Get3DHexResult( |
[in] CSTProjHandle const *projHandle, |
|
|
[in] char const *cTreePathName, |
|
|
[in] int iResultNumber, |
|
|
[out] float *dData ) |
Description: Returns the values of a 3D-result.
Arguments (input):
|
projHandle: |
Handle to the desired CST project. |
|
cTreePathName: |
Name of the result tree item of the desired result. |
|
iResultNumber: |
A number identifying the desired result. |
Arguments (output):
|
dData: |
Pointer to a memory block to be filled with the result values. Depending on the result type, the organization of dData is slightly different. Scalar results:
Real dData[0] = val1; dData[1] = val2; . .
Complex dData[0] = real_part_val1; dData[1] = imaginary_part_val1; dData[2] = real_part_val2; dData[3] = imaginary_part_val2; . .
Vector results: In general vectorial results are organized as follows: first the x-components, followed by the y- and z-components.
Real dData[0] = valX1 dData[1] = valX2 . . dData[nXVals] = valY1 dData[nXVals+1] = valY2 . . dData[nXVals+nYVals] = valZ1 dData[nXVals+nYVals+1] = valZ2 . . Complex dData[0] = real_part_valX1 dData[1] = imaginary_part_valX1 dData[2] = real_part_valX2 dData[3] = imaginary_part_valX2 . . dData[2*nXVals] = real_part_valY1 dData[2*nXVals+1] = imaginary_part_valY1 . . dData[2*nXVals+2*nYVals] = real_part_valZ1 dData[2*nXVals+2*nYVals+1] = imaginary_part_valZ1 . . . |
Only 2D farfields are currently supported.
|
int CST_GetFarfieldResultSize( |
[in] CSTProjHandle const *projHandle, |
|
|
[in] char const *cTreePathName, |
|
|
[in] int isApprox, |
|
|
[in] int Dimension, |
|
|
[out] int *nDataSizeTheta |
|
|
[out] int *nDataSizePhi ) |
Description: Returns the size of the farfield data table.
Arguments (input):
|
projHandle: |
Handle to the desired CST project. |
|
cTreePathName: |
Name of the result tree item of the desired result. |
|
isApprox: |
isApprox = 1: Use the farfield approximation. |
|
Dimension: |
Dimension of the farfield result. Currently only Dimension=2 is supported. |
Arguments (output)
|
nDataSizeTheta: |
Number of theta data points. |
|
nDataSizePhi: |
Number of phi data points. |
|
int CST_GetFarfieldResultDirections( |
[in] CSTProjHandle const *projHandle, |
|
|
[in] char const *cTreePathName, |
|
|
[in] int isApprox, |
|
|
[in] int Dimension, |
|
|
[out] double *Directions ) |
Description: Returns a list of (theta,phi) coordinates associated with the data grid.
Arguments (input):
|
projHandle: |
Handle to the desired CST project. |
|
cTreePathName: |
Name of the result tree item of the desired result. |
|
isApprox: |
isApprox = 1: Use the farfield approximation. |
|
Dimension: |
Dimension of the farfield result. Currently only Dimension=2 is supported. |
Arguments (output)
|
Directions: |
Pointer to a memory block containing the farfield directions. The farfield directions are stored as a consecutive list of (theta,phi) values. In total, the list contains 2 * nDataSizeTheta * nDataSizePhi values. |
|
int CST_GetFarfieldResultField( |
[in] CSTProjHandle const *projHandle, |
|
|
[in] char const *cTreePathName, |
|
|
[in] int isApprox, |
|
|
[in] int Dimension, |
|
|
[out] double *Field_Real |
|
|
[out] double *Field_Imag ) |
Description: Returns a list of farfield values.
Arguments (input):
|
projHandle: |
Handle to the desired CST project. |
|
cTreePathName: |
Name of the result tree item of the desired result. |
|
isApprox: |
isApprox = 1: Use the farfield approximation. |
|
Dimension: |
Dimension of the farfield result. Currently only Dimension=2 is supported. |
Arguments (output)
|
Field_Real: |
Pointer to a memory block containing the real part of the farfield values in V/m. The field values are stored as a consecutive list of (theta, phi, radial) components. In total, the list contains 3 * nDataSizeTheta * nDataSizePhi values. The radial component is omitted if isApprox = 1. |
|
Field_Imag: |
The same as Field_Real for the imaginary part. |
|
int CST_GetFarfieldResultGaindB( |
[in] CSTProjHandle const *projHandle, |
|
|
[in] char const *cTreePathName, |
|
|
[in] int isApprox, |
|
|
[in] int Dimension, |
|
|
[out] double *GaindB ) |
Description: Returns a list of farfield gain values.
Arguments (input):
|
projHandle: |
Handle to the desired CST project. |
|
cTreePathName: |
Name of the result tree item of the desired result. |
|
isApprox: |
isApprox = 1: Use the farfield approximation. |
|
Dimension: |
Dimension of the farfield result. Currently only Dimension=2 is supported. |
Arguments (output)
|
GaindB: |
Pointer to a memory block containing the (theta, phi) components of the farfield gain in dB. The field values are stored as a consecutive list of (theta, phi) components. In total, the list contains 2 * nDataSizeTheta * nDataSizePhi values. |
|
int CST_GetSymmetries( |
[in] CSTProjHandle const *projHandle, |
|
|
[out] int *nSymmetries ) |
Description: Returns the defined symmetry condition of the selected project.
Arguments (input)
|
projHandle: |
Handle to the desired CST project. |
Arguments (output)
|
nSymmetries: |
An array of size 3 that holds symmetry information Meaning of returned integers: See "CST_GetBoundaries" |
|
nSymmetries[0]: |
Symmetry in x-direction. |
|
nSymmetries[1]: |
Symmetry in y-direction. |
|
nSymmetries[2]: |
Symmetry in z-direction. |
|
int CST_GetBoundaries( |
[in] CSTProjHandle const *projHandle, |
|
|
[out] int *nBoundary ) |
Description: Returns the defined boundary condition of the selected project.
Arguments (input):
|
projHandle: |
Handle to the desired CST project. |
Arguments (output):
|
nBoundary: |
An array of size 6 that holds boundary information. The meaning of ther returned integers are the following: 10: Electric 11: Magnetic 12: PML 13: PML expanded 14: Periodic 15: Tangential 16: Normal 17: No boundary/symmetry defined 18: Impedance 19: Unitcell 21: Open low frequency expanded |
|
nBoundary[0]: |
Boundary at x min. |
|
nBoundary[1]: |
Boundary at x max. |
|
nBoundary[2]: |
Boundary at y min. |
|
nBoundary[3]: |
Boundary at y max. |
|
nBoundary[4]: |
Boundary at z min. |
|
nBoundary[5]: |
Boundary at z max. |
|
int CST_GetFrequencyScale ( |
[in] CSTProjHandle const *projHandle, |
|
|
[out] double *FScale ) |
Description: Returns the scale of the frequency unit in Hz.
Arguments (input):
|
projHandle: |
Handle to the desired CST project. |
Arguments (output):
|
FScale: |
Scale of the frequency unit in Hz. |
Only regular grids, no subgrids, no TST.
|
int CST_GetHexMeshInfo ( |
[in] CSTProjHandle const *projHandle, |
|
|
[out] int *nxyz ) |
Description: Returns the number of planes that define the hexahedral grid.
Arguments (input):
|
projHandle: |
Handle to the desired CST project. |
Arguments (output):
|
nxyz: |
An array of 3, containing the number of planes that define the hexahedral grid in x, y and z direction. |
|
int CST_GetHexMesh ( |
[in] CSTProjHandle const *projHandle, |
|
|
[out] double *nxyzLines ) |
Description: Returns the positions of the grid planes in meter, independent of the project units defined by the user.
Arguments (input):
|
projHandle: |
Handle to the desired CST project. |
Arguments (output):
|
nxyzLines: |
An array of size nxyz[0]+nxyz[1]+nxyz[2] containing the positions of the grid planes in x, y, and z direction. |
Only regular grids, no subgrids, no TST.
|
int CST_GetMaterialMatrixHexMesh ( |
[in] CSTProjHandle const *projHandle, |
|
|
[in] int Type, |
|
|
[out] float *fMatrix ) |
Description: Returns the specified material matrix.
Arguments (input):
|
projHandle: |
Handle to the desired CST project. |
|
Type: |
Integer, specifying the matrix type (0 - eps, 1 - mue, 2 - kappa, 3 - rho). Matrix corresponding to last solver type is returned. Add 100 to enforce high frequency matrix. |
Arguments (output):
|
fMatrix: |
Float array of dimension Np * 3, with Np = nxyz[0]*nxyz[1]*nxyz[2], arranged in the order [mat_x[0]..mat_x[Np-1], mat_y[0]..mat_y[Np-1], mat_z[0]..mat_z[Np-1]]. |
To use the CST Result Reader DLL with some older Matlab versions (i.e. Matlab 2008a), it may be necessary that you generate the environment variable KMP_DUPLICATE_LIB_OK and set it to TRUE in your system settings, then restart your computer.
Detailed example Matlab scripts which also show support for 64 bit systems are available in "<Installation path>\ResultReaderDLL" and can be started directly from there with Matlab. On 64 bit systems, Matlab requires a specific C compiler to be installed in order to load DLLs and hence to use the CST Result Reader DLL. Refer to your Matlab documentation fo further information.
Tested configurations:
|
Operating System |
Matlab version |
C compiler |
Other requirements |
|
Windows XP 32 Bit |
R2008a (7.6.0) 32 Bit |
not required |
Env. variable KMP_DUPLICATE_LIB_OK=TRUE |
|
Windows 7 64 Bit |
R2010a (7.10) 32 Bit |
not required |
- |
|
Windows 7 64 Bit |
R2010a (7.10) 64 Bit |
Microsoft Visual Studio 2005 SP2 |
- |
|
Windows Server 2003 SP2 64 Bit |
R2011b 64 Bit |
Microsoft Visual Studio Express 2010 |
|
|
Windows 7 64 Bit SP1 |
R2011b 64 Bit |
Microsoft Visual Studio Express 2010 |
// read out the 3D magnetic field stored in the result tree item "2D/3D Results\H-Field\h-field (f=2) [1]"
#include "CSTResultReaderInterf.h"
.
.
.
CString sLibrary = "CSTResultReader.dll";
HMODULE oModule = LoadLibrary(sLibrary);
ASSERT(oModule != NULL);
UINT uReturnVal;
CST_OpenProject_PTR fOpenProj =
(CST_OpenProject_PTR)GetProcAddress(oModule, "_CST_OpenProject@8");
CST_CloseProject_PTR fCloseProj =
(CST_CloseProject_PTR)GetProcAddress(oModule, "_CST_CloseProject@4");
CST_GetNumberOfResults_PTR fNumberOfRes =
(CST_GetNumberOfResults_PTR) GetProcAddress(oModule, "_CST_GetNumberOfResults@12");
CST_Get3DHexResultSize_PTR f3DHexResSize =
(CST_Get3DHexResultSize_PTR) GetProcAddress(oModule, "_CST_Get3DHexResultSize@16");
CST_Get3DHexResultInfo_PTR f3DHexResInfo =
(CST_Get3DHexResultInfo_PTR) GetProcAddress(oModule, "_CST_Get3DHexResultInfo@32");
CST_Get3DHexResult_PTR f3DFieldResult =
(CST_Get3DHexResult_PTR)GetProcAddress(oModule, "_CST_Get3DHexResult@16");
CString sMWSProjName = "C:\\Program Files\\CST STUDIO SUITE 2012\\Examples\\MWS\\Tutorials\\coaxial\\coaxial connector td-hex.cst";
CString sTree3DEField = "2D/3D Results\\H-Field\\h-field (f=2) [1]";
CSTProjHandle pHandle;
pHandle.m_pProj = NULL;
uReturnVal = fOpenProj(sMWSProjName, &pHandle);
ASSERT(!uReturnVal);
int n3DDataSize = 0;
int infoSize = 1;
int charBufSize = 0;
int intInfo = 0;
// get the size of the expected vector
uReturnVal = f3DHexResSize(&pHandle, sTree3DEField, 0, &n3DDataSize);
ASSERT(!uReturnVal);
// get the type of field result (this is the first entry in "intInfo")
uReturnVal = f3DHexResInfo(&pHandle, sTree3DEField, 0, infoSize, charBufSize, NULL, &intInfo, NULL);
ASSERT(!uReturnVal);
// allocate memory
float *p3DData = new float[n3DDataSize];
// get the field vector
uReturnVal = f3DFieldResult(&pHandle, sTree3DEField, 0, p3DData);
ASSERT(!uReturnVal);
// free the memory
delete [] p3DData;
p3DData = NULL;
// close the project handle
uReturnVal = fCloseProj(&pHandle);
ASSERT(!uReturnVal);
// free the DLL module.
FreeLibrary(oModule);
// NOTES:
// To know the proper function names used by "GetProcAddress" you need to use a DLL analyzing program
// such as "Dependency Walker" from Microsoft.
//
// Instead of using "LoadLibrary", "GetProcAddress" and "FreeLibrary" it is also possible to include the DLL
// as a linker directive. Then the functions are directly available within your program.