PyTrace

PyTrace

PyTrace offers a collection of python classes to interact with TRACE data structures. Cython is used to create a library which can be imported in a python script.

Usage

You have to add the pytracesuite folder to your PYTHONPATH. Then you are able to import the TRACE module to set up and control a TRACE simulation from within a python script.

Example usage in a python script:

from tracesuite.trace import TRACE

if __name__ == '__main__':

    command_line = "-cgns TRACE.cgns"

    trace = TRACE(command_line)
    trace.run()

Note

When the script is executed in parallel with MPI, it is advisable to start it using the mpi4py.run:

mpirun -np <np> python -m mpi4py <script>

Otherwise, MPI deadlocks can occur if single processes raise Python exceptions.

Another way is, to start TRACE with the usual command line and an additional option for the python script.

Classes

trace.py

Contains general classes and enums to manage simulations and turbomachinery setups. Classes and methods defined in here are part of the user interface if they are not prefixed with any underscore.

class tracesuite.trace.trace.TRACE(commandLine, traceMPICommWorld=<mpi4py.MPI.Intracomm object>, traceCntl=None, stopBeforeMetaData=False, externalCntl=None)

Main Trace simulation handle. This class is used to control one Trace simulation that would be started via a console command for one cgns-file. Currently only one simulation can exist in a python context. A simulation can be initialized, configured and started in distinct steps using the given methods. It further provides functionality to focus the communication context on subsets of e.g. panel or block groups to reduce communication overhead. Developers should note that this class essentially uses trace_prototypes.SolverCntl as interfacing class to interact with the underlying Trace c-struct SolverCntl.

applyChangedMetadata()

Execute Trace meta data setup with input parameters changed by previous user commands.

property blockGroups

Returns dictionary of all blocks groups in this Trace simulation.

property eigenmodes

Returns list of all eigenmodes in this Trace simulation.

focusOn(*args)

Select TRACE entities (block or panel groups) to focus on to improve parallel execution of the python script. This method can only be used in a ‘with’ context, e.g.:

with trace.focusOn(inlet, outlet) as focus:
    if focus:
        CODEBLOCK

Here, only the MPI ranks that are owning parts of the inlet or outlet panel groups will execute the CODEBLOCK. Note that due to restrictions in the python language the return value ‘focus’ must be checked explicitly, i.e. the CODEBLOCK must be executed only if ‘focus’ is True. ‘focusOn’ can be nested, but inner nests can focus on a subset of the focused entities of the outer nests.

getBlock(zoneID)

Return the block with the given zoneID as python class Block.

Parameters

zoneID (int) – ID of the block (i.e zone) as specified in the cgns file.

Returns

Reference to the Trace block with the zoneID zoneID.

Return type

Block

getCGNSOutputDataFile(outputType)

Return the path of the cgns output file for the given output type as string.

increaseMaximumTimestepByAddingValue(nTimesteps)

Add ‘nTimesteps’ to the current number of maximum (pseudo) time steps.

static initialize()

Named constructor to wrap an already initialized simulation. Note that this function is meant to be used in a TRACE-calls-python context and should be avoided when implementing python-calls-TRACE functionality.

Returns

New instance of python class TRACE wrapping an already existing Simulation.

Return type

TRACE

kill()

Cleanup TRACE object by disposing all allocated memory and decrement the number of TRACE instances.

message(*args, **kwargs)

Print a unique message to stdout, i.e. only one rank will print in an MPI environment.

property outlets

Return a list containing panel groups of type Outlet

property panelGroups

Returns dictionary of all panel groups in this Trace simulation.

property pseudoTimeStep

Returns the number of the current Trace pseudo time step.

resetFinishedFlags()

Reset (multiple) Trace solver finish flags to suppress an immediate stop in a (new) call to traceRun().

resetMaximumTimestep(nTimesteps)

Set the number of maximum time steps to nTimesteps

run(nIterations=- 1)

Perform nIterations Trace solver steps and return the status as enum SimulationState.

setAsciiOutput(asciiOutputType, path, isActive=True, interleave=1, subIterationOutputOn=False, binaryHDF5=False)

Set output for the given output ascii type.

setCGNSOutputDataFile(outputType, path, isActive=True, interleave=None)

Set cgns output for the given output type.

setReynoldsStressUQ(uqMethod, limitStateTurbulence=None, deltaB=0.0, tkeProductionUpdate=True)

Setup uncertainty quantification method in order to disturb reynolds stresses

property simulationStatus

Returns the current status of the simulation as python enum SimulationState

property solverStep

Returns the number of the current Trace (pseudo) time step.

writeOutputFiles()

Write the current solution into the output files as specified (before) in the output settings.

class tracesuite.trace.trace.TurboMachine(blockGroupDict)

property componentNames

property components

property rowNames

property rows

property stageNames

property stages

panelGroups.py

Contains the general representation of a Trace PanelGroup, derived classes and related methods. Classes and methods defined in here are part of the user interface if they are not prefixed with any underscore.

class tracesuite.trace.panelGroups.PanelGroup(tracePanelGroup, communicator, cntl)

Base class that represents a general PanelGroup in the Trace context. It uses an instance of the cython c-interfacing class TracePanelGroup to interact with one associated Trace c-struct PanelGroup. Functionality that is specific to a certain group type shall be located into the appropriate derived python classes e.g. Inlet, Outlet or Boundary. Since Panel groups might be located on multiple ranks this class inherits from comm.CommunicatingEntity to allow its usage within a focused communication context.

getAreaAveragedIntegralValues(variableNames)

Return area averaged values for the requested variables either directly or as dictionary. See documentation of getFluxAveragedIntegralValues(…) for detailed usage recommendations.

Parameters

variableNames (str or list(str)) – Variable name string or list of variable name strings.

Returns

The direct value of the averaged variable in case variableNames is one string and not a list. In case of a list the values are returned as dictionary with the variable names as keys.

Type

float or { str : float }

getFluxAveragedIntegralValues(variableNames)

Return flux averaged values for the requested variables either directly or as dictionary. The decorator comm.broadcastFromMaster ensures that the values are broadcasted from the panels master rank to all other ranks of the current focus. To return a value directly rather than a dictionary the user can hand over a single variable name without the list brackets. I.e. panel.getFluxAveragedIntegralValues(“pressure”) is equivalent to panel.getFluxAveragedIntegralValues([“pressure”])[“pressure”] Nevertheless since a call to this function triggers one collective communication it is strongly encouraged to summarize requests for different variables into one single call.

Parameters

variableNames (str or list(str)) – Variable name string or list of variable name strings.

Returns

The direct value of the variable in case variableNames is one string and not a list. In case of a list the values are returned as dictionary with the variable names as keys.

Type

float or { str : float }

getMassAveragedIntegralValues(variableNames)

Return mass averaged values for the requested variables either directly or as dictionary. See documentation of getFluxAveragedIntegralValues(…) for detailed usage recommendations.

Parameters

variableNames (str or list(str)) – Variable name string or list of variable name strings.

Returns

The direct value of the variable in case variableNames is one string and not a list. In case of a list the values are returned as dictionary with the variable names as keys.

Type

float or { str : float }

property massflow

Returns the current massflow through the panel group as floating point value The decorator comm.broadcastFromMaster takes care to broadcast the correct value from the panel group master to all other ranks of the current focus.

Returns

Current value of the panels massflow.

Return type

float

property name

Return the name of the panel group as stored in the Trace c-struct “PanelGroup”

property pressure

(Deprecated) Use getFluxAveragedIntegralValues(“Pressure”) instead.

class tracesuite.trace.panelGroups.Boundary(tracePanelGroup, communicator, cntl)

Specific PanelGroup representing boundaries such as Inlet or Outlet. It provides general functionality to set certain variables to a desired value.

class tracesuite.trace.panelGroups.Inlet(tracePanelGroup, communicator, cntl)

Specific PanelGroup representing an Inlet of a flow domain. It provides (user)functionality to set the total pressure and the total temperature on the Inlet to a desired value.

setTotalPressure(pressure)

Set the total pressure on this inlet. Specify in absolute frame of reference

setTotalTemperature(pressure)

Set the total temperature on this inlet. Specify in absolute frame of reference

class tracesuite.trace.panelGroups.Outlet(tracePanelGroup, communicator, cntl)

Specific PanelGroup representing an Outlet of a flow domain. It provides (user)functionality to set the static pressure on the Outlet and to get the actual pressure.

property boundaryConditionPressure

Get the boundary value for the static pressure. The decorator comm.broadcastFromMaster ensures that the value is communicated from the panel groups master rank to all participating ranks of the current focus.

setStaticPressure(pressure)

Set the boundary value for the static pressure.

communication.py

Contains infrastructure for communication within python. NOT part of the user interface!

blockGroups.py

Contains the general representation of a Trace BlockGroup, derived classes and related methods. Classes and methods defined in here are part of the user interface if they are not prefixed with any underscore.

class tracesuite.trace.blockGroups.BlockGroup(traceBlockGroup, communicator, cntl, allBlocks)

Base class that represents a general BlockGroup in the Trace context. It uses an instance of the cython c-interfacing class TraceBlockGroup to interact with one associated Trace c-struct BlockGroup. Functionality that is specific to a certain group type shall be located into the appropriate derived python classes Row, Stage or Component. Since block groups might be located on multiple ranks this class inherits from comm.CommunicatingEntity to allow its usage within a focused communication context.

property blocks

Return a list of all blocks that are associated to this block group.

property localBlocks

Return a list of only the local blocks that are associated to this block group.

property name

Return the name of the block group as stored in the Trace c-struct “BlockGroup”

class tracesuite.trace.blockGroups.Row(traceBlockGroup, communicator, cntl, allBlocks)

Specific BlockGroup representing a single row in turbomachinery context. As a derivation of CommunicatingEntity, objects of this class can be focused within a focused communication context.

property isRotating

Returns boolean flag indicating whether this row is a rotating entity.

property parentComponentName

Returns the name of the component this row uniquely belongs to as string.

property parentStageName

Returns the name of the stage this row uniquely belongs to as string.

property revolutionsPerMinute

Return the current rotational speed of this row in revolutions per minute.

property type

Returns the type of the row (e.g. rotor or stator) as enum of type RowType.

class tracesuite.trace.blockGroups.Stage(traceBlockGroup, communicator, cntl, allBlocks, memberRows)

Specific BlockGroup representing a single stage in turbomachinery context. It further contains the rows it consists of as dictionary. As derivation of CommunicatingEntity objects of this class can be focused within a focused communication context.

property parentComponentName

Returns the name of the component this row uniquely belongs to as string.

property rowNames

Return the names of the rows this stage consists of as list of strings.

property rows

Return the rows this stage consists of as list.

class tracesuite.trace.blockGroups.Component(traceBlockGroup, communicator, cntl, allBlocks, memberStages, memberRows)

Specific BlockGroup representing a single component in turbomachinery context. It further contains the rows and the stages it consists of as dictionaries. As derivation of CommunicatingEntity objects of this class can be focused within a focused communication context.

property rowNames

Return the names of the rows which belong to this component as list of strings.

property rows

Return the rows which belong to this component as list.

property stageNames

Return the names of the stages which belong to this component as list of strings.

property stages

Return the stages which belong to this component as list.

block.py

Contains the general representation of a Trace Block as well as related classes and methods. Classes and methods defined in here are part of the user interface if they are not prefixed with any underscore.

class tracesuite.trace.block.Block(cntl, traceBlock)

Python class representing a general block in the Trace context, i.e. a structured or unstructured part of the computational domain handled by an instance of SolverCntl. Note that Trace holds meta information of all blocks on each rank but only allocates actual (e.g. solution) data on blocks that are assigned to its own rank (i.e. local blocks). If this is a local block, dimensionalized access to the underlying data fields is provided. Furthermore iterators can be used to loop over all cells in a single loop. All methods and properties are valid on each rank. Nevertheless if the block is not local, fields will be empty and iterators loop length will be zero.

property allCells

Return an iterator that loops only over all cells of a block including ghost cells.

property dim

Returns the dimension of this block including the ghost cell layers as CellIndex.

property innerCells

Return an iterator that loops only over the inner cells of a block omitting the ghost cells.

property isLocal

Returns a boolean flag indicating whether this block is associated to this rank. Note that Trace holds meta information of all blocks on each rank but only allocates actual (e.g. solution) data on blocks that are assigned to its own rank (i.e. local blocks).

property name

Return the name of this block as specified by the cgns-file.

property zoneId

Return the zoneId of this block as specified by the cgns-file. Enumeration starts with 1.

eigenmode.py

Contains the general representation of an Eigenmode as well as related classes and methods. Classes and methods defined in here are part of the user interface if they are not prefixed with any underscore.

class tracesuite.trace.eigenmode.Eigenmode(cntl, traceEigenmode, blockGroups)

Python class representing a general eigenmode in the Trace context, handled by an instance of SolverCntl.

property acceleration

The modal acceleration at the next time step. Is readable and writeable.

property currentAcceleration

The modal acceleration at the current time step. Is only readable.

property currentDisplacement

The modal displacement at the current time step. Is only readable.

property currentForce

The modal force at the current time step. Is only readable.

property currentVelocity

The modal velocity at the current time step. Is only readable.

property displacement

The modal displacement at the next time step. Is readable and writeable.

property force

The modal force at the next time step. Is only readable.

property name

Return the name of this eigenmode.

property velocity

The modal velocity at the next time step. Is readable and writeable.