Documentation

The `Boolean` class

class cst_python_api.Boolean(MWS)

Bases: object

This class allows to perform boolean operations between objects of the project.

add(object1: str, object2: str)

Performs the boolean addition of two solids.

object2 is added to object1, so the resulting solid will have the name of object1.

For each of the solids their full name (including the name of the component where they belong) must be specified. A slash (/) must be used to separate nested components, and a colon (:) to separate the names of components and objects (e.g. “component1/sub-component1:solid1”).

Parameters:

object1 (str) – Solid on which the addition will be performed.
object2 (str) – Solid to add.

Raises:

TypeError – If object1 is not of type str.
TypeError – If object2 is not of type str.
RuntimeError – If the VBA code generated by this method is not successfully executed by CST.

insert(object1: str, object2: str)

Performs the boolean insertion of one solid into another.

object2 is inserted into object1.

For each of the solids their full name (including the name of the component where they belong) must be specified. A slash (/) must be used to separate nested components, and a colon (:) to separate the names of components and objects (e.g. “component1/sub-component1:solid1”).

Parameters:

object1 (str) – Solid where the insertion will occur.
object2 (str) – Solid to insert.

Raises:

TypeError – If object1 is not of type str.
TypeError – If object2 is not of type str.
RuntimeError – If the VBA code generated by this method is not successfully executed by CST.

intersect(object1: str, object2: str)

Performs the boolean intersection between two solids.

object1 is considered as the main one, so the resulting solid will have the name of object1.

For each of the solids their full name (including the name of the component where they belong) must be specified. A slash (/) must be used to separate nested components, and a colon (:) to separate the names of components and objects (e.g. “component1/sub-component1:solid1”).

Parameters:

object1 (str) – Main solid for the intersection.
object2 (str) – Secondary solid for the intersection.

Raises:

TypeError – If object1 is not of type str.
TypeError – If object2 is not of type str.
RuntimeError – If the VBA code generated by this method is not successfully executed by CST.

mergeCommonMaterials(component: str)

Performs the boolean addition of all solids of the same material at the specified component.

In case of specifying a subcomponent, its name must be indicated using a slash (/) (e.g. “component1/sub-component1”).

Parameters:

component (str) – Component for which the addition will be performed.

Raises:

TypeError – If component is not of type str.
RuntimeError – If the VBA code generated by this method is not successfully executed by CST.

subtract(object1: str, object2: str)

Performs the boolean subtraction between two solids.

object2 is subtracted from object1, so the resulting solid will have the name of object1.

For each of the solids their full name (including the name of the component where they belong) must be specified. A slash (/) must be used to separate nested components, and a colon (:) to separate the names of components and objects (e.g. “component1/sub-component1:solid1”).

Parameters:

object1 (str) – Solid from which the subtraction will be performed.
object2 (str) – Solid to subtract.

Raises:

TypeError – If object1 is not of type str.
TypeError – If object2 is not of type str.
RuntimeError – If the VBA code generated by this method is not successfully executed by CST.

The `Build` class

class cst_python_api.Build(MWS)

Bases: object

This class allows to perform operations related to the creation of components and shapes of the project.

This class integrates instances of the classes: - Boolean - Component - Material - Shape - Transform

deleteObject(objectName: str, objectType: str)

Delete a component or a shape from the project

Parameters:

objectName (str) – Name of the component or shape to be deleted.
objectType (str) – Type of object to be deleted. Possible values are “Component” and “Solid”.

Raises:

TypeError – If objectName is not of type str.
TypeError – If objectType is not of type str.
ValueError – If objectType does not take a valid value.

The `CST_MicrowaveStudio` class

class cst_python_api.CST_MicrowaveStudio(folder='', filename='')

Bases: object

This class allows to control CST Microwave Studio on a Windows operating system from a Python program.

closeFile(): Closes the currently open Microwave Studio project.

quit(): Closes the CST application.

saveFile(folder='', filename='', includeResults=True)

Save the current project.

If no folder and filename are specified, save the project at its current location.

If a folder and filename are specified, save a copy of the project at this new path. Whether or not the results are also copied to this new project, can be controlled by the flag includeResults.

Parameters:

folder (str, optional) – Folder (absolute path) where the project must be saved, by default “”.
filename (str, optional) – Filename under which save the project, by default “”.
includeResults (bool, optional) – Flag for controlling if the results must also be saved, by default True.

Raises:

Exception – If a filename is indicated but not a folder.
Exception – If a folder is indicated but not a filename.

The `CheckParam` class

class cst_python_api.CheckParam(MWS)

Bases: object

doCheck(paramValue)

Checks a value to be assigned to a parameter when generating a VBA macro.

If paramValue is of type float, it is casted to str and returned. However, if it is of type str, it is verified whether a parameter with name paramValue does exist in the project or not. In an affirmative case, paramValue is returned. Otherwise, an exception is raised.

Parameters:

paramValue (float or str) – Parameter to check.

Returns:

String to be used in the VBA macro.

Return type:

str

Raises:

RuntimeError – If paramValue is of type str and there is not a parameter with name paramValue in the current CST project.
TypeError – If paramValue is not of type float or str.

The `Component` class

class cst_python_api.Component(MWS)

Bases: object

This class allows to perform operations on the components list of the project.

delete(name: str)

Delete a component of the current project.

A subcomponent can be specified by using a slash (/) (e.g. name = “component/subcomponent”).

Parameters:

name (str) – Name of the component to delete.

Raises:

TypeError – If name is not of type str.
ValueError – If name does not match any component in the project.
RuntimeError – If the VBA code generated by this method is not successfully executed by CST.

ensureExistence(name: str)

Check if a component called name does exist in the project. If it does not, create it.

Parameters:

name (str) – Name of the component to check.

Raises:

TypeError – If name is not of type str.
RuntimeError – If calling self.new() raises a RuntimeError.

exist(name: str)

Check if a component does exist in the current project.

A subcomponent can be specified by using a slash (/) (e.g. name = “component/subcomponent”).

Parameters:: name (str) – Name of the component to check.
Returns:: True if the component exists, False otherwise.
Return type:: bool
Raises:: TypeError – If name is not of type str.

new(name: str)

Create a new component in the current project.

A subcomponent can be specified by using a slash (/) (e.g. name = “component/subcomponent”).

Parameters:

name (str) – Name of the component to create.

Raises:

TypeError – If name is not of type str.
RuntimeError – If the VBA code generated by this method is not successfully executed by CST.

rename(name: str, newName: str)

Rename a component of the current project.

A subcomponent can be specified by using a slash (/) (e.g. name = “component/subcomponent”). By doing so, it is possible to move subcomponents from one component to another (or even to make them a component of their own).

Parameters:

name (str) – Current name of the component to rename.
newName (str) – New name to give to the component.

Raises:

TypeError – If name is not of type str.
TypeError – If newName is not of type str.
ValueError – If name does not match any component in the project.
RuntimeError – If the VBA code generated by this method is not successfully executed by CST.

The `Material` class

class cst_python_api.Material(MWS)

Bases: object

This class allows to manipulate the materials of the project

addAnisotropicMaterial(name, eps, mu, colour)

Adds normal material to the project.

The parameters defining electric characteristics of the material (eps and mu) must be of type list with length equal to 3. Each element of the list represents one of the components (X, Y, Z) and it can be either of type float or str. If a float is received it will be directly used as the value for such parameter. In a string is received it will be verified that such string corresponds to a parameter already defined in the project. In an affirmative case, the string will be used in the material definition and the material will depend on this project parameter. However, if the received string does not correspond with a parameter already existing in the project an exception will be raised.

The colour of the material is defined by a list representing the desired RGB colour code. Each colour component is indicated as a floating number between 0 and 1.

Parameters:

name (str) – Name to give to the material.
eps (list of float or str) – Relative electric permittivity (X, Y and Z components).
mu (list of float or str) – Relative magnetic permeability (X, Y and Z components).
colour (list of float) – List representing the RGB colour for the material.

Raises:

TypeError – If name is not of type str.
TypeError – If eps is not of type list.
ValueError – If length of eps is different of 3.
TypeError – If mu is not of type list.
ValueError – If length of mu is different of 3.
TypeError – If any of the eps or mu components is not of type float or str.
RuntimeError – If any of the eps or mu components is of type string but it does not match any parameter already defined in the project.
TypeError – If colour is not of type list.
ValueError – If length of colour is different of 3.
TypeError – If any of the elements in colour is not of type float.
RunTimeError – If the VBA code generated by this method is not successfully executed by CST.

addNormalMaterial(name, eps, mu, colour, tanD=0.0, sigma=0.0, tanDM=0.0, sigmaM=0.0)

Adds normal material to the project.

The parameters defining electric characteristics of the material can be either of type float or str. If a float is received it will be directly used as the value for such parameter. In a string is received it will be verified that such string corresponds to a parameter already defined in the project. In an affirmative case, the string will be used in the material definition and the material will depend on this project parameter. However, if the received string does not correspond with a parameter already existing in the project an exception will be raised.

The colour of the material is defined by a list representing the desired RGB colour code. Each colour component is indicated as a floating number between 0 and 1.

Parameters:

name (str) – Name to give to the material.
eps (float or str) – Relative electric permittivity.
mu (float or str) – Relative magnetic permeability.
colour (list of float) – List representing the RGB colour for the material.
tanD (float or str, optional) – Electric tangent loss, by default 0.0
sigma (float or str, optional) – Electric conductivity, by default 0.0
tanDM (float or str, optional) – Magnetic tangent loss, by default 0.0
sigmaM (float or str, optional) – Magnetic conductivity, by default 0.0

Raises:

TypeError – If name is not of type str.
TypeError – If any of the parameters describing the EM characteristics of the material is not of type float or str.
RuntimeError – If any of the parameters describing the EM characteristics of the material is of type string but it does not match any parameter already defined in the project.
TypeError – If colour is not of type list.
ValueError – If length of colour is different of 3.
TypeError – If any of the elements in colour is not of type float.
RunTimeError – If the VBA code generated by this method is not successfully executed by CST.

The `Parameter` class

class cst_python_api.Parameter(MWS)

Bases: object

This class allows to perform operations on the parameters of the CST project.

add(paramName, paramValue, checkParamExistence=True)

Adds a new parameter to the project.

The value of the parameter can be a float, a string representing the name of another existing parameter, or even a mathematical operation between parameters (e.g. paramValue = “lambda0/2”).

The method is designed to avoid overwriting an already existing parameter. For modifying an already existing parameter it is preferred to use the “change” method. However, this functionality can be overridden by setting the checkParamExistence flag to False.

Parameters:

paramName (str) – Name of the parameter to add.
paramValue (str or float) – Value for the parameter.
checkParamExistence (bool, optional) – If set to False, allows to overwrite an already existing parameter, by default True

Raises:

TypeError – If paramName is not of type str.
TypeError – If paramValue is not of type float or str.
RuntimeError – If the parameter does already exist in the project and checkParamExistence has not been set to False.
RuntimeError – If paramValue is not of type float or str but somehow the code arrived to the final else of the if-elif-else structure checking the type of paramValue. In principle this should never happen since the type of paramValue is checked at the beginning of the method.

addDescription(paramName, description)

Adds a description to an already existing parameter.

It must be noted that the length of the string containing the description cannot exceed MAX_LENGTH_PARAMETER_DESCRIPTION.

Parameters:

paramName (str) – Name of the parameter to which the description must be added.
description (str) – Text of the description.

Raises:

TypeError – If paramName is not of type str.
TypeError – If description is not of type str.
RuntimeError – If the specified parameter does not exist in the project.
ValueError – If the length of description exceeds MAX_LENGTH_PARAMETER_DESCRIPTION.

change(paramName, paramValue)

Modify the value of parameter that already exists in the project.

The new value of the parameter can be a float, a string representing the name of another existing parameter, or even a mathematical operation between parameters (e.g. paramValue = “lambda0/2”).

It should be noted that if paramName refers to a parameter which does not exist in the project, then a new parameter will be created with the specified name and value. However, in this case it would be preferable to use the add method in order to favour the readability of the code.

Parameters:

paramName (str) – Name of the parameter to modify.
paramValue (str or float) – New value for the parameter.

Raises:

TypeError – If paramName is not of type str.
TypeError – If paramValue is not of type float or str.

delete(paramName)

Suppress a parameter already existing in the project.

Parameters:

paramName (str) – Name of the parameter to delete.

Raises:

TypeError – If paramName is not of type str.
RuntimeError – If the parameter does not exist in the project.

exist(paramName)

Checks if a certain parameter does exist in the project.

Parameters:: paramName (str) – Name of the parameter to check.
Returns:: True if the parameter exists, False otherwise.
Return type:: bool
Raises:: TypeError – If paramName is not of type str.

rebuild()

Rebuilds the project after a parametric update.

This method must be used after modifying one or more parameters on which the project does depend.

retrieve(paramName, paramFormat)

Reads the value of a parameter.

The format for the parameter must be specified using paramFormat. The two possible options are “float” and “str”. With “float”, the floating point number value of the parameter will be returned. With “str”, the result will depend on whether the parameter is defined as a number or as a mathematical expression. In the former case, a string representation of the number will be returned; while in the latter, the expression will be returned.

Example

Parameters in the CST project:

Name	Expression	Value
param1	21	21
param2	2*param1	42

>>> retrieve("param1", "float")
21.0
>>> retrieve("param1", "str")
'21'

>>> retrieve("param2", "float")
42.0
>>> retrieve("param2", "str")
'2*param1'

Parameters:

paramName (str) – Name of the parameter to read.
paramFormat (str) – Used to indicate if the parameter should be read as a string or as a floating point number. Possible values: “str”, “float”.

Returns:

Value of the parameter indicated by paramName

Return type:

str or float

Raises:

TypeError – If paramName is not of type str.
TypeError – If paramFormat is not of type str.
RuntimeError – If the specified parameter does not exist in the project.
ValueError – If the value of paramFormat is not “str” or “float”.

retrieveDescription(paramName)

Reads the description of an already existing parameter.

Parameters:

paramName (str) – Name of the parameter from which the description must be read.

Returns:

Text of the description.

Return type:

str

Raises:

TypeError – If paramName is not of type str.
RuntimeError – If the specified parameter does not exist in the project.

The `Port` class

class cst_python_api.Port(MWS)

Bases: object

This class allows to perform operations on the ports of the project.

Adds a discrete port to the current project.

Three different excitation types can be considered: S-Parameters, Voltage and current.

Parameters:

xMin (Union[float, str]) – X coordinate of the first point of the port.
xMax (Union[float, str]) – X coordinate of the second point of the port.
yMin (Union[float, str]) – Y coordinate of the first point of the port.
yMax (Union[float, str]) – Y coordinate of the second point of the port.
zMin (Union[float, str]) – Z coordinate of the first point of the port.
zMax (Union[float, str]) – Z coordinate of the second point of the port.
type (str, optional) – String indicating the type of excitation. Possible values are “SParameter”, “Voltage” and “Current”, by default “SParameter”
impedance (float, optional) – Impedance value of the port. Only takes effect when type is “SParameter”, by default 50.0
voltage (float, optional) – Voltage to apply at the port. Only takes effect when type is “Voltage”, by default 1.0
current (float, optional) – Current to apply at the port. Only takes effect when type is “Current”, by default 1.0
radius (float, optional) – Radius of the port, by default 0.0

Raises:

TypeError – If type is not of type str.
ValueError – If type is different of ‘SParameter’, ‘Voltage’ or ‘Current’.
TypeError – If impedance is not of type float.
ValueError – If impedance is not greater than zero.
TypeError – If voltage is not of type float.
TypeError – If current is not of type float.
TypeError – If radius is not of type float.
TypeError – If any of the parameters (xMin, xMax, yMin, yMax, zMin, zMax) describing the port position is not of type float or str.
RuntimeError – If any of the parameters describing the port position is of type str but it does not match any parameter already defined in the project.
RuntimeError – If the VBA code generated by this method is not successfully executed by CST.

Adds a waveguide port to the current project.

The orientation of the port is indicated by specifying its normal vector (X, Y or Z). It must be noted that for each of these directions, the port can produce an excitation towards negative or positive values. This is specified with the “min” and “max” suffixes. However, it should be noted that the sense of this normal vector is the contrary of that of the waveguide excitation. This means that “xmin” specifies a port that produces an excitation propagating towards the direction +X. In this case, the boundaries of the port would be defined by yMin, yMax, zMin and zMax, while xMin would indicate the position along the X axis where the port would be placed. Please note that it would still be necessary to assign a value to xMax in this case, although this value will be unused. Conversely, “xmax” indicates a waveguide port producing an excitation in the -X direction.

Parameters:

xMin (Union[float, str]) – Smallest value of the X coordinate in the area of the port.
xMax (Union[float, str]) – Greatest value of the X coordinate in the area of the port.
yMin (Union[float, str]) – Smallest value of the Y coordinate in the area of the port.
yMax (Union[float, str]) – Greatest value of the Y coordinate in the area of the port.
zMin (Union[float, str]) – Smallest value of the Z coordinate in the area of the port.
zMax (Union[float, str]) – Greatest value of the Z coordinate in the area of the port.
orientation (str) – Orientation of the port. Please note that the sense of this vector is contrary to the sense of the excitation produced by the port. This means that “xmin” indicates “towards +X” and “xmax” indicates “towards -X”. Analogous definitions for Y and Z.
nModes (int, optional) – Number of modes to consider at the port. Must be equal or greater than 1, by default 1
enforcePolar (bool, optional) – Flag indicating whether a specific polarization angle must be enforced. Useful when there are degenerate modes, by default False
polarAngle (float, optional) – Polarization angle to enforce. It is necessary to activate the flag enforcePolar, by default 0.0
refPlaneDist (float, optional) – Distance between the port and the reference plane for the phase of the S-Parameters. A negative value shifts the reference plane towards the direction indicated by orientation, by default 0.0

Raises:

TypeError – If orientation is not of type str.
ValueError – If orientation does not present a valid value.
TypeError – If nModes is not of type int.
ValueError – If nModes is smaller than one.
TypeError – If enforcePolar is not of type bool.
TypeError – If any of the parameters (xMin, xMax, yMin, yMax, zMin, zMax, polarAngle, refPlaneDist) describing the port position is not of type float or str.
RuntimeError – If any of the parameters describing the port position is of type str but it does not match any parameter already defined in the project.
RuntimeError – If the VBA code generated by this method is not successfully executed by CST.

The `Project` class

class cst_python_api.Project(MWS)

Bases: object

setUnits(leng: str = 'mm', freq: str = 'GHz', time: str = 's', temp: str = 'K')

Sets the units for the current project.

CST Microwave Studio only allows to change the units for the following magnitudes: length, frequency, time and temperature. For other magnitudes like voltage, current or capacitance it is not possible to modify the units from their default value.

Possible values for each of the modifiable units are as follows: - Length: “m”, “cm”, “mm”, “um”, “nm”, “ft”, “mil”, “in” - Frequency: “Hz”, “kHz”, “MHz”, “GHz”, “THz”, “pHz” - Time: “s”, “ms”, “us”, “ns”, “ps”, “fs” - Temperature: “K”, “degC”, “degF” (Kelvin, Celsius, Fahrenheit)

Parameters:

leng (str, optional) – Units for lenght, by default “mm”
freq (str, optional) – Units for frequency, by default “GHz”
time (str, optional) – Units for time, by default “s”
temp (str, optional) – Units for temperature, by default “K”

Raises:

TypeError – If leng is not of type str.
ValueError – If leng does not take a valid value.
TypeError – If freq is not of type str.
ValueError – If freq does not take a valid value.
TypeError – If time is not of type str.
ValueError – If time does not take a valid value.
TypeError – If temp is not of type str.
ValueError – If temp does not take a valid value.
RuntimeError – If the VBA code generated by this method is not successfully executed by CST.

The `Results` class

class cst_python_api.Results(MWS)

Bases: object

This class allows to perform operations relative to the results of the project.

getFarField(freq: float | str, theta: ndarray[Any, dtype[Any]], phi: ndarray[Any, dtype[Any]], port: int, mode: int = 0, plotMode: str = 'directivity', coordSys: str = 'spherical', polarization: str = 'linear', component: list = ['theta', 'phi'], complexComp: list = ['abs', 'abs'], linearScale: bool = False)

Retrieve farfield monitor results from the project.

Two arrays of theta and phi values (in degrees) must be provided. The method generates a matrix with the farfield evaluated at these points. Each row of the matrix corresponds to a theta point, and each column to a phi point.

By using the optional parameters, it is possible to adjust several features like the magnitude represented by the farfield (directivity, gain, radiated field…), the coordinate system, the polarization…

The results are returned as a list containing several of the aforementioned matrices. Each of these matrices corresponds to a vector component of the farfield. In order to reduce the use of computational resources, only the components specified by the user are generated. The desired components can be specified using the input parameter component.

In addition, it is also necessary to define the list complexComp, which must have the same length as the list component. Since the farfield results are complex numbers, the list complexComp defines (for each of the specified farfield components) how these numbers must be represented (magnitude, phase, real part, imaginary part…). It should be noted that each entry of the component list can have a different value of complexComp. For obtaining the magnitude and phase of a certain farfield component, it is necessary to have two identical entries in the component list with corresponding entries in complexComp taking one of them the value “abs” and the other the value “phase”.

Parameters:

freq (Union[float, str]) – Frequency of the farfield monitor from which the results must be retrieved. Can be a number or a string, since it is possible to use a project parameter to specify the frequency of the monitor.
theta (NDArray[Any]) – Vector of theta points (in degrees) for which the farfield must be calculated.
phi (NDArray[Any]) – Vector of phi points (in degrees) for which the farfield must be calculated.
port (int) – Excitation port corresponding to the desired farfield.
mode (int, optional) – Mode (of the port) corresponding to the desired farfield. Must be used if at least one of the ports in the project supports several modes (even if the port of interest does present a single mode). If all the ports in the project present a single mode, then this input parameter must take a value of 0, by default 0
plotMode (str, optional) – Magnitude to be represented by the farfield pattern. Possible options are: “directivity”, “gain”, “realized gain”, “efield”, “hfield”, “pfield”, “rcs”, “rcsunits”, “rcssw”, by default “directivity”
coordSys (str, optional) – Coordinate system used for expressing the results. Allows to change between a spherical coordinate system and the Ludwig definitions. Possible options are: “spherical”, “ludwig2ae”, “ludwig2ea”, “ludwig3”, by default “spherical”
polarization (str, optional) – Polarization used for expressing the results. Possible options are: “linear”, “circular”, “slant”, “abs”, by default “linear”
component (list, optional) – List of field components for which the farfield must be returned. Each case is expressed by a str. Possible values: “radial”, “theta”, “azimuth”, “left”, “alpha”, “horizontal”, “crosspolar”, “phi”, “elevation”, “right”, “epsilon”, “vertical”, “copolar”, by default [“theta”, “phi”]
complexComp (list, optional) – List indicating the format in which the complex number corresponding to each of the components is represented. Must have the same length as component, by default [“abs”, “abs”]
linearScale (bool, optional) – If se to True, the results are provided in a linear scale. Otherwise, a logarithmic scale is used, by default False

Returns:

List containing len(component) elements. Each of these elements is a numpy array of len(theta) rows and len(phi) columns, containing the farfield results corresponding to one of the components indicated by the component list.

Return type:

list

Raises:

TypeError – If freq is not of type float or str.
RuntimeError – If freq is of type str but it does not make reference to a parameter already defined in the project.
TypeError – If theta is not of type NDArray.
ValueError – If theta is not a one-dimensional array.
TypeError – If phi is not of type NDArray.
ValueError – If phi is not a one-dimensional array.
TypeError – If port is not of type int.
ValueError – If port is smaller than 1.
TypeError – If mode is not of type int.
ValueError – If mode is smaller than 0.
TypeError – If plotMode is not of type str.
ValueError – If the plotMode value does not correspond to a valid plot type.
TypeError – If coordSys is not of type str.
ValueError – If the coordSys value does not correspond to a valid coordinate system.
TypeError – If polarization is not of type str.
ValueError – If the polarization value does not correspond to a valid polarization.
TypeError – If component is not of type list.
TypeError – If complexComp is not of type list.
ValueError – If the lengths of component and complexComp are not the same.
TypeError – If any of the elements in component is not of type str.
TypeError – If any of the elements in complexComp is not of type str.
ValueError – If the value of any of the component elements does not correspond to a valid field component.
ValueError – If the value of any of the complexComp elements does not correspond to a valid field component.
TypeError – If linearScale is not of type bool.
RuntimeError – If the specified farfield result is not present in the project.

getSParameters(portA: int, portB: int, modeA: int = 0, modeB: int = 0, runID: int = 0)

Read the specified port parameter.

A pair of port numbers must be specified. The parameter S_{a,b} will be read. If the project contains multimode ports, it will be necessary to specify the desired mode number for each of the ports. If single-mode ports are used in the project, modeA and modeB must be set to 0.

The method also supports Floquet ports. For this, a port number equal to 0 can be specified to indicate the port Zmax, and a port number equal to -1 can be used for the port number Zmin.

It is possible to pass a specified runID number to retrieve the S-parameter corresponding to that runID. The runID=0 (default) corresponds to the last run of the solver.

Parameters:

portA (int) – Output port.
portB (int) – Input port.
modeA (int, optional) – Mode number at the output port, by default 0
modeB (int, optional) – Mode number at the input port, by default 0
runID (int, optional) – runID for which the results must be retrieved, by default 0

Returns:

List of frequency values (float) and list of S-parameter values (complex).

Return type:

list

Raises:

TypeError – If portA or portB are not of type int.
ValueError – If portA or portB are smaller than -1.
TypeError – If modeA or modeB are not of type int.
ValueError – If modeA or modeB are smaller than 0.
ValueError – If either modeA or modeB are equal to 0, but the other mode number is not equal to 0.
TypeError – If runID is not of type int.
ValueError – If runID is smaller than 0.
RuntimeError – If CST throws an error while retrieving the list of runIDs.
RuntimeError – If the specified runID is not present in the project results.
RuntimeError – If there CST throws an error while retrieving the S-Parameter.

The `Shape` class

class cst_python_api.Shape(MWS)

Bases: object

This class allows to add 3D bodies to the project

Add a brick to the 3D model.

x, y and z are lists of two elements indicating the ends (minimum and maximum) of the brick at each of these coordinates. These lists can contain either a float value, or a string referencing a parameter already existing in the project.

Parameters:

xMin (float or str) – xMin limit of the brick.
xMax (float or str) – xMax limit of the brick.
yMin (float or str) – yMin limit of the brick.
yMax (float or str) – yMax limit of the brick.
zMin (float or str) – zMin limit of the brick.
zMax (float or str) – zMax limit of the brick.
name (str) – Name to give to the brick.
component (str) – Component where the brick must be created.
material (str) – Material to use for the brick.

Raises:

TypeError – If name is not of type str.
TypeError – If component is not of type str.
TypeError – If material is not of type str.
TypeError – If any of the geometric parameters (xMin, xMax, yMin, yMax, zMin, zMax) describing the brick is not of type float or str.
RuntimeError – If any of the geometric parameters describing the brick is of type str but it does not match any parameter already defined in the project.
RuntimeError – If the VBA code generated by this method is not successfully executed by CST.

Add a cylinder to the 3D model.

The cylinder can have three different orientations: Along X, along Y and along Z. This is denoted by the parameter orientation.

The xMin/xMax, yMin/yMax and zMin/zMax parameters are interpreted in a different way depending on the value of orientation. For orientation=’x’, xMin and and xMax will serve to determine the position of the bottom and top faces along the X axis, while yMin and zMin will define the center of the bottom face on the YZ plane and yMax and zMax will be ignored. For the other two orientations the code proceeds analogously.

nSegments can be used to control the number of sides of the polygon generating the cylinder. The possible smallest value is 3. However, a value of 0 can be used to denote a polygon with infinite sides (i.e. a circle).

Parameters:

xMin (float or str) – Used to define the position of the bottom face.
yMin (float or str) – Used to define the position of the top face, only when orientation=’x’.
zMin (float or str) – Used to define the position of the bottom face.
extRad (float or str) – External radius of the cylinder.
intRad (float or str) – Internal radius of the cylinder.
name (str) – Name to give to the cylinder.
component (str) – Component where the cylinder must be created.
material (str) – Material to use for the cylinder.
orientation (str) – Orientation of the cylinder. Only possible values are ‘x’, ‘y’ and ‘z’.
xMax (float or str, optional) – Used to define the position of the top face, only when orientation=’x’, by default 0.0
yMax (float or str, optional) – Used to define the position of the top face, only when orientation=’y’, by default 0.0
zMax (float or str, optional) – Used to define the position of the top face, only when orientation=’z’, by default 0.0
nSegments (int, optional) – Number of sides of the polygon that generates the cylinder, by default 0

Raises:

TypeError – If name is not of type str.
TypeError – If component is not of type str.
TypeError – If material is not of type str.
ValueError – If orientation is different of ‘x’, ‘y’ and ‘z’.
ValueError – If nSegments is of type int and takes a value smaller than 3 and different of 0.
TypeError – If nSegments is not of type int.
TypeError – If any of the geometric parameters (xMin, xMax, yMin, yMax, zMin, zMax, extRad, intRad) describing the cylinder is not of type float or str.
RuntimeError – If any of the geometric parameters describing the cylinder is of type str but it does not match any parameter already defined in the project.
RuntimeError – If the VBA code generated by this method is not successfully executed by CST.

addPolygonBlock(points: ndarray, height: float | str, name: str, component: str, material: str, zMin: float | str = 0.0)

Adds a block generated by the extrusion of a polygon to the 3D model.

Parameters:

points (np.ndarray of float) – Vertices of the polygon to be extruded.
height (float or str) – Height for the extrusion process.
name (str) – Name to give to the block.
component (str) – Component where the block must be created.
material (str) – Material to use for the block.
zMin (float or str, optional) – Z plane at which the polygon will be defined, by default 0.0

Raises:

TypeError – If name is not of type str.
TypeError – If component is not of type str.
TypeError – If material is not of type str.
TypeError – If points is not of type numpy array.
TypeError – If elements of points are not of type float.
ValueError – If points contains less than three vertices.
ValueError – If the number of coordinates of each point is different of 2.
ValueError – If the first and last points are not the same.
TypeError – If any of the geometric parameters (height, zMin) describing the block is not of type float or str.
RuntimeError – If any of the geometric parameters describing the block is of type str but it does not match any parameter already defined in the project.
RuntimeError – If the VBA code generated by this method is not successfully executed by CST.

Add a sphere to the 3D model.

The sphere can have three different orientations: Along X, along Y and along Z. This is denoted by the parameter orientation. The orientation of the sphere is only relevant if a truncation of its ends is performed via the parameters topRad/botRad, or if a value other than 0 is passed to nSegments.

nSegments can be used to control the number of sides of the polygon generating the sphere. This polygon in defined on the plane perpendicular to the direction defined by orientation. The possible smallest value is 3. However, a value of 0 can be used to denote a polygon with infinite sides (i.e. a circle).

Parameters:

xCen (float or str) – X coordinate of the sphere center
yCen (float or str) – Y coordinate of the sphere center
zCen (float or str) – Z coordinate of the sphere center
cenRad (float or str) – Radius of the sphere.
name (str) – Name to give to the sphere.
component (str) – Component where the sphere must be created.
material (str) – Material to use for the sphere.
topRad (float or str, optional) – Radius for the truncation of the sphere on its top end (defined by the orientation parameter), by default 0.0
botRad (float or str, optional) – Radius for the truncation of the sphere on its bottom end (defined by the orientation parameter), by default 0.0
orientation (str, optional) – Axis on which the truncations defined topRad and botRad will be applied, by default “z”
nSegments (int, optional) – Number of sides of the polygon that generates the sphere, by default 0

Raises:

TypeError – If name is not of type str.
TypeError – If component is not of type str.
TypeError – If material is not of type str.
ValueError – If orientation is different of ‘x’, ‘y’ and ‘z’.
ValueError – If nSegments is of type int and takes a value smaller than 3 and different of 0.
TypeError – If nSegments is not of type int.
TypeError – If any of the geometric parameters (xCen, yCen, zCen, cenRad, topRad, botRad) describing the sphere is not of type float or str.
RuntimeError – If any of the geometric parameters describing the sphere is of type str but it does not match any parameter already defined in the project.
RuntimeError – If the VBA code generated by this method is not successfully executed by CST.

The `Solver` class

class cst_python_api.Solver(MWS)

Bases: object

This class allows to perform operations relatives to the solver.

addFieldMonitor(type: str, freq: float | str)

Add a field monitor to the project.

Only frequency type monitors are supported.

Supported field types: “Efield”, “Hfield”, “Farfield”, “Fieldsource”, “Surfacecurrent”, “Powerflow”, “Current”, “Powerloss”, “Eenergy”, “Henergy”

Parameters:

type (str) – Type of field to be monitored.
freq (Union[float, str]) – Frequency at which the field is monitored.

Raises:

TypeError – If type is not of type str.
ValueError – If type contains a non valid value.
TypeError – If freq not of type float or str.
RuntimeError – If freq is of type str but it does not make reference to a parameter already defined in the project.
RuntimeError – If the VBA code generated by this method is not successfully executed by CST.

addSymmetryPlane(xSym: str, ySym: str, zSym: str)

Adjusts the symmetry planes for the project.

Possible values are “none”, “electric” and “magnetic”.

Parameters:

xSym (str) – Symmetry type of the YZ plane.
ySym (str) – Symmetry type of the XZ plane.
zSym (str) – Symmetry type of the XY plane.

Raises:

TypeError – If any of the input parameters is not of type str.
ValueError – If any of the input parameters contains a non valid value.
RuntimeError – If the VBA code generated by this method is not successfully executed by CST.

changeSolverType(type: str)

Change the solver type used in the project.

Possible solver identifiers are “HF Time Domain”, “HF Eigenmode”, “HF Frequency Domain”, “HF IntegralEq”, “HF Multilayer”, “HF Asymptotic”.

Parameters:

type (str) – Name of the solver to use.

Raises:

TypeError – If type is not of type str.
ValueError – If type is of type str but does not correspond to a valid solver identifier.
RuntimeError – If the VBA code generated by this method is not successfully executed by CST.

defineFloquetModes(nModes: int, theta: float | str = 0.0, phi: float | str = 0.0, forcePolar: bool = False, polarAngle: float | str = 0.0)

Defines a Floquet modes excitation for the project.

It is necessary to set first unit cell boundaries for the X and Y limits.

Parameters:

nModes (int) – Number of Floquet modes. The same number is used for both ports. Must be greater than zero.
theta (Union[float, str], optional) – Elevation angle for the incident modes. In degrees, by default 0.0
phi (Union[float, str], optional) – Azimuth angle for the incident modes. In degrees, by default 0.0
forcePolar (bool, optional) – Flag for overriding the variation of the polarization angle with phi. If set to true, the polarization will be force along the angle indicated by polarAngle, by default False
polarAngle (Union[float, str], optional) – Polarization reference to be used for defining the Floquet modes it forcePolar is set to True. In degrees, by default 0.0

Raises:

TypeError – If nModes is not of type int.
ValueError – If nModes is not greater than zero.
TypeError – If forcePolar is not of type bool.
TypeError – If any of the portParams is not of type float or str.
RuntimeError – If any of the portParams is of type str but it does not correspond to a parameter already defined in the project.
RuntimeError – If the VBA code generated by this method is not successfully executed by CST.

getSolverType()

Get the current solver for the project.

Returns:: Name of the current solver.
Return type:: str

runSimulation(): Run the currently active solver.

Define the background limits of the project.

These limits are defined as an increment of the surrounding space over the minimum bounding box containing all the solids of the project. I.e., if all the input parameters are set to zero, then the bounding box of the project will be the smallest possible. By giving to any of the input parameters a positive value, this bounding box can be enlarged in the desired direction.

It should be noted that it is not possible to specify a negative value since the bounding box must contain all the solid in the project.

Parameters:

xMin (Union[float, str]) – Distance from objects to boundary in the +X direction.
xMax (Union[float, str]) – Distance from objects to boundary in the -X direction.
yMin (Union[float, str]) – Distance from objects to boundary in the +Y direction.
yMax (Union[float, str]) – Distance from objects to boundary in the -Y direction.
zMin (Union[float, str]) – Distance from objects to boundary in the +Z direction.
zMax (Union[float, str]) – Distance from objects to boundary in the -Z direction.

Raises:

TypeError – If any of the input parameters is not of type float or str.
RuntimeError – If any of the input parameters is of type str but it does not correspond to a parameter already defined in the project.
RuntimeError – If the VBA code generated by this method is not successfully executed by CST.

Adjust the background material of the project.

Three types of materials can be chosen: “Vacuum”, “PEC” and “Dielectric”.

All the optional arguments must be used only if a dielectric background is chosen.

Parameters:

type (str) – Type of material to be used.
epsR (Union[float, str], optional) – Relative electric permittivity, by default 1.0
muR (Union[float, str], optional) – Relative magnetic permeability, by default 1.0
tanD (Union[float, str], optional) – Electric loss tangent, by default 0.0
tanDFreq (Union[float, str], optional) – Frequency (in Hz) at which the electric loss tangent is given, by default 0.0
tanDGiven (bool, optional) – Flag to indicate whether the electric losses of the material are specified by the electric loss tangent (True) or the electric conductivity (False), by default False
sigma (Union[float, str], optional) – Electric conductivity, by default 0.0
tanDM (Union[float, str], optional) – Magnetic loss tangent, by default 0.0
tanDFreq – Frequency (in Hz) at which the magnetic loss tangent is given, by default 0.0
tanDMGiven (bool, optional) – Flag to indicate whether the magnetic losses of the material are specified by the magnetic loss tangent (True) or the magnetic conductivity (False), by default False
sigmaM (Union[float, str], optional) – Magnetic conductivity, by default 0.0

Raises:

TypeError – If type is not of type str.
ValueError – If type contains a non-valid value.
TypeError – If either tanDGiven or tanDMGiven are not of type bool.
TypeError – If any of the bkgrParams is not of type float or str.
RuntimeError – If any of the bkgrParams is of type str but it does not correspond to a parameter already defined in the project.
RuntimeError – If the VBA code generated by this method is not successfully executed by CST.

setBoundaryCondition(xMin: str, xMax: str, yMin: str, yMax: str, zMin: str, zMax: str, wallCond: float | str = 1000.0)

Sets the boundary conditions for the project.

Possible values are: “electric”, “magnetic”, “open”, “expanded open” (called “open add space” in CST GUI), “periodic”, “conducting wall”, “unit cell”.

“unit cell” can only be used for X and Y boundaries. In addition, if “unit cell” is used for any of the X or Y boundaries, then it must be used for all of them.

“wallCond” can be either a numeric value or a string representing a parameter of the project.

Parameters:

xMin (str) – Boundary type for the -X boundary.
xMax (str) – Boundary type for the +X boundary.
yMin (str) – Boundary type for the -Y boundary.
yMax (str) – Boundary type for the +Y boundary.
zMin (str) – Boundary type for the -Z boundary.
zMax (str) – Boundary type for the +Z boundary.
wallCond (Union[float, str], optional) – Conductivity value of the boundaries of type “conducting wall”, by default 1000.0

Raises:

TypeError – If any of the parameters defining the boundary types is not of type str.
ValueError – If any of the parameters defining the boundary types contains a string that does not correspond to a valid boundary type.
ValueError – If “unit cell” is specified for either zMin or zMax.
ValueError – If “unit cell” is specified for only some of the X and Y boundaries.
TypeError – If wallCond is not of type float or str.
RuntimeError – If wallCond is of type str but it does not match any parameter already defined in the project.
RuntimeError – If the VBA code generated by this method is not successfully executed by CST.

setFrequencyRange(fMin: float | str, fMax: float | str)

Adjust the frequency range for the simulation.

Parameters:

fMin (Union[float, str]) – Lowest frequency of the range.
fMax (Union[float, str]) – Highest frequency of the range.

Raises:

TypeError – If any of the parameters (fMin, fMax) describing the frequency range is not of type float or str.
RuntimeError – If any of the parameters describing the frequency range is of type str but it does not match any parameter already defined in the project.
RuntimeError – If the VBA code generated by this method is not successfully executed by CST.

The `Transform` class

class cst_python_api.Transform(MWS)

Bases: object

This class allows to perform transformations on objects of the project.

Mirrors an object.

Parameters:

object (str) – Name of the object on which to perform the operation.
x (Union[float, str]) – X component of mirror plane normal.
y (Union[float, str]) – Y component of mirror plane normal.
z (Union[str, float]) – Z component of mirror plane normal.
x0 (Union[float, str], optional) – X coordinate of mirror plane origin, by default 0.0
y0 (Union[float, str], optional) – Y coordinate of mirror plane origin, by default 0.0
z0 (Union[float, str], optional) – Z coordinate of mirror plane origin, by default 0.0
origin (str, optional) – Indicates whether the origin of the mirror plane is at the the center of the object (“object”) or at the point indicated by x0, y0 and z0 (“free”), by default “object”
copy (bool, optional) – Flag to indicate if the operation must be applied to a duplicate of the object, by default False
repetitions (int, optional) – Number of times that the operation must be applied, by default 1
group (bool, optional) – In case of copy=True, if this flag is set to True, the original objects and its replica(s) will be joined, by default False
destination (str, optional) – In case of copy=True, indicates the destination name for the copy. If nothing is specified the default value will be used, by default “”
material (str, optional) – In case of copy=True, indicates the material to be used for the copy. If nothing is specified the same material as in the original value will be used, by default “”

Raises:

TypeError – If object is not of type str.
TypeError – If origin is not of type str.
ValueError – If origin is different of ‘object’ or ‘free’.
TypeError – If copy is not of type bool.
TypeError – If repetitions is not of type int.
ValueError – If repetitions is smaller than 1.
TypeError – If group is not of type bool.
TypeError – If destination is not of type str.
TypeError – If material is not of type str.
ValueError – If group is True but copy is False.
ValueError – If destination is not empty but copy is False.
ValueError – If material is not empty but copy is False.
TypeError – If any of the transformation parameters (x, y, z, x0, y0, z0) describing the mirroring is not of type float or str.
RuntimeError – If any of the transformation parameters describing the rotation is of type str but it does not match any parameter already defined in the project.
RuntimeError – If calling to the ensureExistence() method raises a RuntimeError.
RuntimeError – If the VBA code generated by this method is not successfully executed by CST.

Rotates an object.

Parameters:

object (str) – Name of the object on which to perform the operation.
x (Union[float, str]) – Rotating angle (in degrees) around axis X.
y (Union[float, str]) – Rotating angle (in degrees) around axis Y.
z (Union[str, float]) – Rotating angle (in degrees) around axis Z.
x0 (Union[float, str], optional) – X coordinate of origin for rotation, by default 0.0
y0 (Union[float, str], optional) – Y coordinate of origin for rotation, by default 0.0
z0 (Union[float, str], optional) – Z coordinate of origin for rotation, by default 0.0
origin (str, optional) – Indicates whether the origin for the rotation operation is the center of the object (“object”) or the point indicated by x0, y0 and z0 (“free”), by default “object”
copy (bool, optional) – Flag to indicate if the operation must be applied to a duplicate of the object, by default False
repetitions (int, optional) – Number of times that the operation must be applied, by default 1
group (bool, optional) – In case of copy=True, if this flag is set to True, the original objects and its replica(s) will be joined, by default False
destination (str, optional) – In case of copy=True, indicates the destination name for the copy. If nothing is specified the default value will be used, by default “”
material (str, optional) – In case of copy=True, indicates the material to be used for the copy. If nothing is specified the same material as in the original value will be used, by default “”

Raises:

TypeError – If object is not of type str.
TypeError – If origin is not of type str.
ValueError – If origin is different of ‘object’ or ‘free’.
TypeError – If copy is not of type bool.
TypeError – If repetitions is not of type int.
ValueError – If repetitions is smaller than 1.
TypeError – If group is not of type bool.
TypeError – If destination is not of type str.
TypeError – If material is not of type str.
ValueError – If group is True but copy is False.
ValueError – If destination is not empty but copy is False.
ValueError – If material is not empty but copy is False.
TypeError – If any of the transformation parameters (x, y, z, x0, y0, z0) describing the rotation is not of type float or str.
RuntimeError – If any of the transformation parameters describing the rotation is of type str but it does not match any parameter already defined in the project.
RuntimeError – If calling to the ensureExistence() method raises a RuntimeError.
RuntimeError – If the VBA code generated by this method is not successfully executed by CST.

Scales an object.

Parameters:

object (str) – Name of the object on which to perform the operation.
x (Union[float, str]) – Scaling factor along axis X.
y (Union[float, str]) – Scaling factor along axis Y.
z (Union[str, float]) – Scaling factor along axis Z.
x0 (Union[float, str], optional) – X coordinate of origin for scaling, by default 0.0
y0 (Union[float, str], optional) – Y coordinate of origin for scaling, by default 0.0
z0 (Union[float, str], optional) – Z coordinate of origin for scaling, by default 0.0
origin (str, optional) – Indicates whether the origin for the scaling operation is the center of the object (“object”) or the point indicated by x0, y0 and z0 (“free”), by default “object”
copy (bool, optional) – Flag to indicate if the operation must be applied to a duplicate of the object, by default False
repetitions (int, optional) – Number of times that the operation must be applied, by default 1
group (bool, optional) – In case of copy=True, if this flag is set to True, the original objects and its replica(s) will be joined, by default False
destination (str, optional) – In case of copy=True, indicates the destination name for the copy. If nothing is specified the default value will be used, by default “”
material (str, optional) – In case of copy=True, indicates the material to be used for the copy. If nothing is specified the same material as in the original value will be used, by default “”

Raises:

TypeError – If object is not of type str.
TypeError – If origin is not of type str.
ValueError – If origin is different of ‘object’ or ‘free’.
TypeError – If copy is not of type bool.
TypeError – If repetitions is not of type int.
ValueError – If repetitions is smaller than 1.
TypeError – If group is not of type bool.
TypeError – If destination is not of type str.
TypeError – If material is not of type str.
ValueError – If group is True but copy is False.
ValueError – If destination is not empty but copy is False.
ValueError – If material is not empty but copy is False.
TypeError – If any of the transformation parameters (x, y, z, x0, y0, z0) describing the scaling is not of type float or str.
RuntimeError – If any of the transformation parameters describing the scaling is of type str but it does not match any parameter already defined in the project.
RuntimeError – If calling to the ensureExistence() method raises a RuntimeError.
RuntimeError – If the VBA code generated by this method is not successfully executed by CST.

translate(object: str, x: float | str, y: float | str, z: str | float, copy: bool = False, repetitions: int = 1, group=False, destination: str = '', material: str = '')

Translates an object.

Parameters:

object (str) – Name of the object on which to perform the operation.
x (Union[float, str]) – Translation distance along axis X.
y (Union[float, str]) – Translation distance along axis Y.
z (Union[str, float]) – Translation distance along axis Z.
copy (bool, optional) – Flag to indicate if the operation must be applied to a duplicate of the object, by default False
repetitions (int, optional) – Number of times that the operation must be applied, by default 1
group (bool, optional) – In case of copy=True, if this flag is set to True, the original objects and its replica(s) will be joined, by default False
destination (str, optional) – In case of copy=True, indicates the destination name for the copy. If nothing is specified the default value will be used, by default “”
material (str, optional) – In case of copy=True, indicates the material to be used for the copy. If nothing is specified the same material as in the original value will be used, by default “”

Raises:

TypeError – If object is not of type str.
TypeError – If copy is not of type bool.
TypeError – If repetitions is not of type int.
ValueError – If repetitions is smaller than 1.
TypeError – If group is not of type bool.
TypeError – If destination is not of type str.
TypeError – If material is not of type str.
ValueError – If group is True but copy is False.
ValueError – If destination is not empty but copy is False.
ValueError – If material is not empty but copy is False.
TypeError – If any of the transformation parameters (x, y, z) describing the translation is not of type float or str.
RuntimeError – If any of the transformation parameters describing the translation is of type str but it does not match any parameter already defined in the project.
RuntimeError – If calling to the ensureExistence() method raises a RuntimeError.
RuntimeError – If the VBA code generated by this method is not successfully executed by CST.

Documentation

The Boolean class

The Build class

The CST_MicrowaveStudio class

The CheckParam class

The Component class

The Material class

The Parameter class

The Port class

The Project class

The Results class

The Shape class

The Solver class

The Transform class

The `Boolean` class

The `Build` class

The `CST_MicrowaveStudio` class

The `CheckParam` class

The `Component` class

The `Material` class

The `Parameter` class

The `Port` class

The `Project` class

The `Results` class

The `Shape` class

The `Solver` class

The `Transform` class