cst.results module

Module Contents

This module allows reading one-dimensional result curves and data points of CST project files. These results are referred to as “0D/1D Results”.

No running instance of CST Studio Suite is required for data access.

Supported are unpacked and unprotected project files generated with CST Studio Suite 2019 or CST Studio Suite 2020.

To understand how this module can be used, see the Examples section of the documentation.

cst.results.print_version_info()

Print version information of this module

cst.results.get_version_info()

Get a dictionary containing version information of the files used by this module

class cst.results.ProjectFile

This class allows loading a CST file to access its results.

__init__(*args, **kwargs)

Overloaded function.

  1. __init__(self: _cst_results.ProjectFile) -> None

Initialize an empty ProjectFile.

  1. __init__(self: _cst_results.ProjectFile, filepath: str, allow_interactive: bool=False) -> None

Initialize a ProjectFile with a filepath to a CST file. See method ‘init’ for more details about the setting ‘allow_interactive’.

filename

The filename of the CST project.

get_3d(self: _cst_results.ProjectFile) → ResultModule

Get the 3D submodule of a CST project.

get_schematic(self: _cst_results.ProjectFile) → ResultModule

Get the Schematic submodule of a CST project.

init(self: _cst_results.ProjectFile, filepath: str, allow_interactive: bool=False) → None

Initialize a ProjectFile with a filepath to a CST file. The setting ‘allow_interactive=True’ allows accessing a project which can be simultaneously opened in CST Studio Suite. In this interactive mode, data access can be done after ‘Save’ was triggered in CST Studio Suite. If any changes are made in CST Studio Suite to the project without saving (e.g. a solver is started), the retrieved data will be outdated or ill-formed. It is up to the user to ensure that the project is not in an intermediate state.

list_subprojects(self: _cst_results.ProjectFile) → List[str]

List tree paths which represent subprojects (i.e. Simulation Projects Tasks or Block Simulation Tasks).

load_subproject(self: _cst_results.ProjectFile, treepath: str) → _cst_results.ProjectFile

Load a subproject from a tree path.

class cst.results.ResultModule

This class provides an interface to access the 3D or Schematic results submodule of a of a CST project.

get_all_run_ids(self: _cst_results.ResultModule, max_mesh_passes_only: bool=True) → List[int]
Get all existing run ids (independent of a tree path).
In case of a mesh adaptation, max_mesh_passes_only=True yields only results with the highest mesh pass.
get_parameter_combination(self: _cst_results.ResultModule, run_id: int) → dict

Return the parameter combination which corresponds to the provided run id.

get_result_item(self: _cst_results.ResultModule, treepath: str, run_id: int=0, load_impedances: bool=True) → _cst_results.ResultItem

Get result of a navigation tree item.

get_run_ids(self: _cst_results.ResultModule, treepath: str, skip_nonparametric: bool=False) → List[int]

Get all existing run ids for a tree item. The setting ‘skip_nonparametric=True’ enforces run id = 0 to be excluded from the list.

get_tree_items(self: _cst_results.ResultModule, filter: str='0D/1D') → List[str]

List navigation tree items.

class cst.results.ResultItem

This class represents the result data of a navigation tree item of a CST project for a single parameter combination.

get_data(self: _cst_results.ResultItem) → list

The data as list of tuples, or a double value.

get_parameter_combination(self: _cst_results.ResultItem) → dict

The parameter combination which was used to generate the result.

get_ref_imp_data(self: _cst_results.ResultItem) → object

The reference impedance of the result.

get_xdata(self: _cst_results.ResultItem) → object

The x-axis of the result.

get_ydata(self: _cst_results.ResultItem) → object

The y-axis of the result.

length

The number of points returned by ‘get_ydata’.

run_id

The run id of the result.

title

The title of the result.

treepath

The navigation tree path of the result.

xlabel

The x-label of the result.

ylabel

The y-label of the result.

General Notes

This module supports only access to unpacked CST files. A packed CST project file (generated via “Archive As”) can be extracted by opening it with CST Studio Suite. Protected project files are not supported.

Please also note that access to projects which are being simulated in an open CST Studio Suite is not supported.

Examples

Introduction

The CST Studio Suite installation comes with Python 3.6, so there is no need to additionally install Python to follow the examples.

Note

For simplicity, the following examples assume a Windows OS. However, Linux is supported as well.

To open a Python console, browse for the \AMD64\python subfolder of the CST Studio Suite installation (e.g. C:\Program Files (x86)\CST STUDIO SUITE 2020\AMD64\python) and run python.exe. This console is already configured to have the include paths for the cst python extensions.

If you want to use another Python 3.6, you need to add the cst python extensions to the include path. Please refer to the Setup section for details.

For the educational purpose of the following examples, you can temporarily add the path via the sys module.

>>> import sys
>>> sys.path.append(r"C:\Program Files (x86)\CST STUDIO SUITE 2020\AMD64\python_cst_libraries")

However, this approach should not be used for production code.

Example 1 - Access S-Parameter data

The following code loads S-Parameter data of a 3D project.

For this example, take any 3D project which contains an S-Parameter S1,1, or create one from scratch. Open the project in CST Studio Suite, save it to an appropriate path (e.g. “C:\demo\project.cst”) and close CST Studio Suite.

Then load the project and address S1,1 via its navigation tree path:

>>> import cst.results
>>> project = cst.results.ProjectFile(r"C:\demo\project.cst")
>>> s11 = project.get_3d().get_result_item(r"1D Results\S-Parameters\S1,1")

The returned object is of the class ResultItem, which offers a variety of functions and properties to have a fine-grained data access to a 0D/1D Result. To get the x-axis data, use get_xdata() and xlabel. The function get_data() returns the data as list of tuples with varying number of entries, or a double value.

>>> s11.get_xdata()
[8.0, 9.0, 10.0]
>>> s11.xlabel
'Frequency / GHz'
>>> s11.get_data()
[(8.0, (0.011821912601590157+0.26499754190444946j), (1066.824324690301+0j)),
(9.0, (0.10851031541824341-0.052459076046943665j), (678.7112974398144+0j)),
(10.0, (-0.007742199115455151-0.06290644407272339j), (568.406116209625+0j))]

In this case, the first tuple entry in the list represents the frequency of the S-Parameter, the second tuple entry represents the complex-valued S-Parameter and the third entry represents the complex-valued Reference Impedance of the S-Parameter.

The returned object type of get_data() depends on the type of the loaded result. For 1D Results without Reference Impedance, this will be a list of tuples with two entries, where the second tuple entry may be complex-valued or not. For 0D Results, the method’s return value will not be a list, but a single double value.

Set up a demo example project

In case you want to set up a demo example project from scratch, open an empty CST Studio Suite and select the New and Recent tab. From the Modules/Tools section, pick 3D Simulation-> High Frequency. This will open an empty 3D project. From the Home Ribbon, select Macros->Construct->Demo Examples->Waveguide T Splitter. This will run a construction VBA macro. Start the simulation run to obtain 0D/1D Results. Save it and close CST Studio Suite.

Example 2 - Access subproject data

The following example shows how subproject data of a Schematic Task can be accessed.

To set up the example project, please open CST Studio Suite, go to the Component Library and use the search bar in the top right corner to find the “Antenna Reflector Assembly” example. Open it, save it to an appropriate path (e.g. “C:\demo\Antenna Reflector Assembly.cst”) and close CST Studio Suite.

To get the treepaths of all existing 0D/1D Results, the method get_tree_items() of the project’s Schematic ResultModule can be used.

>>> import cst.results
>>> project = cst.results.ProjectFile(r"C:\demo\Antenna Reflector Assembly.cst")
>>> cst.results.get_schematic().get_tree_items()
['Tasks\\HS1\\1D Results\\Convergence\\Excitation [[Source2]1]\\Frequency = 5 GHz',
 'Tasks\\HS1\\1D Results\\Efficiencies\\Rad. Efficiency [[Source2]1]',
 'Tasks\\HS1\\1D Results\\Efficiencies\\Tot. Efficiency [[Source2]1]',
 'Tasks\\HS1\\1D Results\\Power\\Excitation [[Source2]1]\\Power Accepted',
 'Tasks\\HS1\\1D Results\\Power\\Excitation [[Source2]1]\\Power Radiated',
 'Tasks\\HS1\\1D Results\\Power\\Excitation [[Source2]1]\\Power Stimulated',
 'Tasks\\HS1\\1D Results\\S-Parameters\\S[Source2]1,[Source2]1']

However, you may notice that the project has more tree items which are not listed here, e.g. below Tasks\\SP1. These results are part of subprojects and need to be opened explicitly. Subprojects are represented by some Generalized Simulation Tasks in the Schematic, e.g. Simulation Project Tasks, Electrical Machine Tasks, Block Simulation Tasks or Hybrid Solver Tasks.

To get the treepaths of all existing subprojects, use the command list_subprojects().

>>> project.list_subprojects()
['Tasks\\HS-UniDir1\\Platform1',
 'Tasks\\HS-UniDir1\\Source1',
 'Tasks\\HS1\\Platform2',
 'Tasks\\HS1\\Source2',
 'Tasks\\SP1']

Using one of the obtained tree paths, the data of the corresponding subproject can be loaded by via load_subproject(). The returned object is again a ProjectFile which can be accessed like any other CST project. To show the tree items of the subproject, call get_tree_items() of the project’s 3D ResultModule.

>>> sub_project = project.load_subproject("Tasks\\SP1")
>>> sub_project.get_3d().get_tree_items()
['1D Results\\Balance\\Balance [1]',
 '1D Results\\Efficiencies\\Rad. Efficiency [1]',
 '1D Results\\Efficiencies\\Tot. Efficiency [1]',
 '1D Results\\Energy\\Energy [1]',
...]
Example 3 - Access parametric data

The following example shows how existing parametric 0D/1D Results can be accessed.

To set up the example project, please open CST Studio Suite, go to the Component Library and use the search bar in the top right corner to find the “VCO Parameter Sweep” example. Open it, save it to an appropriate path (e.g. “C:\demo\VCO Parameter Sweep.cst”) and close CST Studio Suite.

Typically, CST Studio Suite stores all 0D/1D Results which are calculated during a parameter sweep of simulation runs. This allows studying the relationship of parameters and results. In CST Studio Suite, a parameter combination is represented by an identifier called run id. A detailed description about parametric data handling can be found in the Parametric Results Overview.

In Python, the run id is depicted by an integer.

Note that this is a Circuits & Systems project, therefore the Schematic ResultModule needs to be queried. To list all existing run ids, use get_all_run_ids().

>>> import cst.results
>>> project = cst.results.ProjectFile(r"C:\demo\VCO Parameter Sweep.cst")
>>> schematic = project.get_schematic()
>>> schematic.get_all_run_ids()
[0, 1, 2, 3, 4, 5, 6]

This show all run ids which were created in the Schematic submodule of the project. However, not all tree entries necessarily have results for all existing run ids, since the project setup allows a fine-grained control about which results are stored during a parameter sweep.

Let’s first query the existing run ids of a Postprocessing Task result item via get_run_ids().

>>> schematic.get_run_ids('Tasks\\Sweep Tuning Voltage\\Tran1\\PP1\\0D\\Oscillation Frequency')
[0, 1, 2, 3, 4, 5, 6]

In this case, for all runs there is also a result. Now let’s query the existing runs of the Port1 item in the Transient Task.

>>> schematic.get_run_ids('Tasks\\Sweep Tuning Voltage\\Tran1\\TD Currents\\Port1')
[0]

For this tree item, only results are stored which correspond to run id=0. If we try to get the ResultItem for a non-existing run id, we get an error. Note that the method get_result_item() has an argument for the queried run id which defaults to 0.

>>> port1 = schematic.get_result_item('Tasks\\Sweep Tuning Voltage\\Tran1\\TD Currents\\Port1',5)
ValueError: ResultItem does not exist for run id=5.

Querying the existing result with run id=0 works.

>>> port1 = schematic.get_result_item('Tasks\\Sweep Tuning Voltage\\Tran1\\TD Currents\\Port1',0)
>>> port1.length
10001

To resolve a run id to its parameter combination, use get_parameter_combination(). This method returns a dictionary which contains the parameter names and values.

>>> schematic.get_parameter_combination(4)
{'VTUNE': 1.5,
 'VBIAS': 2.7,
 'LE': 0.25, ...}
>>> schematic.get_parameter_combination(5)
{'VTUNE': 2.0,
 'VBIAS': 2.7,
 'LE': 0.25, ...}

For convenience, a loaded ResultItem also has a notion about its parameter combination. It offers run_id and get_parameter_combination().

>>> f = schematic.get_result_item('Tasks\\Sweep Tuning Voltage\\Tran1\\PP1\\0D\\Oscillation Frequency',5)
>>> f.run_id
5
>>> f.get_parameter_combination()
{'VTUNE': 2.0,
 'VBIAS': 2.7,
 'LE': 0.25, ...}

In case one is interested in the relationship of parameter “VTUNE” to the result value “Oscillation Frequency”, one can read the data as follows:

>>> tree_item = 'Tasks\\Sweep Tuning Voltage\\Tran1\\PP1\\0D\\Oscillation Frequency'
>>> x = []
>>> y = []
>>> run_ids = schematic.get_run_ids(tree_item,skip_nonparametric=True)
>>> for run in run_ids:
>>>     result = schematic.get_result_item(tree_item,run)
>>>     x.append(result.get_parameter_combination()['VTUNE'])
>>>     y.append(result.get_ydata())
>>>
>>> for i in range(len(x)):
>>>     print (x[i], y[i])
0.0 0.957278481012658
0.5 0.974766822118588
1.0 0.988507661558961
1.5 0.99975016655563
2.0 1.01140906062625
2.5 1.01973684210526

Note that the loaded result “Oscillation Frequency” is a 0D Result, therefore the function get_ydata() returns a single double value. Since run id=0 plays a special role (in particular, a copy of its results may exist with a different run id), we use the function get_run_ids() with the argument skip_nonparametric=True to exclude it from the list to avoid a potential result duplicate. The obtained x-y data now can be used for further processing or plotting.