30.3.1. Using the Provided Python Module

The provided Python module is installed as ANSYS_INSTALL_DIR\v242\aqwa\utils\ExternalForceCalculation\AqwaSocketMgr.py.

An example Python script which makes use of this module is also installed as ANSYS_INSTALL_DIR\v242\aqwa\utils\ExternalForceCalculation\AqwaSocketUserForceExample.py.

You may use your own installation of Python, or the version of the Python interpreter installed with Aqwa, located at ANSYS_INSTALL_DIR\v242\commonfiles\CPython. A .BAT script is also installed that allows you to run Python scripts by dragging and dropping files onto it ( ANSYS_INSTALL_DIR\v242\aqwa\utils\ExternalForceCalculation\StartAqwaPythonUserForceServer.bat).

The AqwaSocketUserForceExample.py script has the following structure:

  • The from AqwaSocketMgr import * command.

  • Several user-defined external force functions:

    • def UF1(Analysis,Mode,Stage,Time,TimeStep,Pos,Vel):

      ...

    • def UF2(Analysis,Mode,Stage,Time,TimeStep,Pos,Vel):

      ...

    • def UF3(Analysis,Mode,Stage,Time,TimeStep,Pos,Vel):

      ...

  • A line which initializes the server: Server = AqwaUserForceServer()

    The server creates a socket, binds it to a free port number, and begins listening on that port.

  • One or more commands of the form: Server.Run(UF1)

    These commands cause the server to wait for a connection from the Aqwa process. When the connection is established, the server receives data from the process, calculates the user-defined external forces, and returns the external forces and added mass using the function UF1. The server iterates this function until instructed to stop by the Aqwa process.

    After being instructed to stop, the server returns to a waiting state. This approach allows you to define several different functions and to select which one to use at runtime, potentially based on runtime information provided by Aqwa itself.

The Python class AqwaUserForceServer is defined in AqwaSocketMgr.py as a subclass of AqwaSocketMgr.

After the connection is established (when executing code in a user-defined external force function), the Server object has several attributes automatically defined:

  • Server.hostname and Server.port: Information about the connection

  • Server.Analysis: An object containing information and tools specific to the currently running analysis:

    • Analysis.InputFileName: the full path of the file currently being run in Aqwa without the .DAT extension

    • Analysis.NOfStruct: number of structures defined in the input file

    • Analysis.I_Control and Analysis.R_Control arrays: user parameters defined in the input file using the IUFC and RUFC data records

    • Analysis.COGs: the position of each structure’s center of gravity in the definition axis system

    • Analysis.Pos: The position of each structure’s center of gravity in the global axis system at the current simulation time

    • Analysis.Vel: The velocity of each structure’s center of gravity in the global axis system at the current simulation time

    • Analysis.Time: The current simulation time

    • Analysis.GetNodeCurrentPosition(Struct,DefAxesX,DefAxesY,DefAxesZ): A function returning the position of a node of the given structure at the current time from its original position in the definition axis

    • Analysis.ApplyForceOnStructureAtPoint(Struct,FX,FY,FZ,AppPtX,AppPtY,AppPtZ): A function returning the Force object (including the moment) applied at the structure’s center of gravity, resulting from the application of a force at a particular point of the structure

These attributes can be used in the Python script for any purpose. For example, it is possible to define a list of user-defined functions and to select one for a particular run by parsing the values of the Analysis.I_Control array. Such a selection could also be made using the Analysis.InputFileName value. Note that the analysis object is accessible within a user-defined function as the first argument in the function: Analysis.

The functions Analysis.GetNodeCurrentPosition and Analysis.ApplyForceOnStructureAtPoint are provided to simplify the process of expressing forces and moments on the COGs of structures. AqwaSocketUserForceExample.py shows an example of their use.

Additionally, the modules provide two classes BlankAddedMass and BlankForce which are used for initializing the Force and Added Mass containers that are returned by the user-defined functions. These classes support basic algebraic operations (sum, difference, scalar multiplication), as shown in the AqwaSocketUserForceExample.py script.