WSE Interface Module

The WSE Inference Module is a singleton class which is instantiated in every other class within the WSE_Package. It was created this way to provide flexibility to users and to maintain key program sequences and memory wherever it is used. The WSE provides several key features to the API:

  1. Maintains program sequences

  2. Handles memory spaces with no need for user input

  3. Handles controller specific operations as well as global operations (Looping, conditionals, global reductions, controller arithmetic)

  4. Handles code optimization

  5. Enables compiler directives

  6. Compiles into WSE images and maps

  7. Handles validation in NumPy

Almost all of this functionality is handled automatically and is not a necessary concern for end users.

class WFA.WSE_Interface.WSE_Interface(*args, **kwargs)

Singleton class that keeps track of program sequence for the WFA package See WSE_Interface_Singleton for available methods

class WFA.WSE_Interface.WSE_Interface_Singleton

DO NOT INSTANTIATE DIRECTLY This class is the singleton base of WSE_Interface Contains all methods available in WSE_Interface

create_coded_position_array(x_dim, y_dim)

Creates a single precision coded array that contains a 10 bit representation of x and y position. This allows one to represent x and y position up to 1024 cells and leave 12 bits to represent up to 4096 cells in z. This is intended to be used with the WSE_Local_Scalar class and the push_coded_index method to push a 3d tensor off the wafer for reconstructing data that streams off the wafer on the high speed interfaces.

Parameters:

  • x_dim (int) – The number of cells in the x direction

  • y_dim (int) – The number of cells in the y direction

Returns:

coded_xy_data – A Float32 array that contains the coded bits of x and y position

Return type:

np.array

debug_message(message, active=True)

Enables debug message when compiled with the -dl 3 option. Very useful for determining position in a large program. To use, add into the graph construction wherever needed.

def _calc_shear_and_P(self, debug_active=False):
    self._wse.debug_message('FD_Stokes._calc_shear_and_P: Start of _calc_shear_and_P', active=debug_active)
    with ASM() as cs_asm:
        eta_two = cs_asm.malloc_array()
        self._wse.debug_message('FD_Stokes._calc_shear_and_P: calc eta_two', active=debug_active)
        eta_two[1:-1,0,0] = self.eta0*(2.0 - 2.0*self.deta_dT*(self.T[1:-1,0,0] + self.deltaT/2.0))

The message will show up in the validation.txt file

----------------------------------
Debug Message: FD_Stokes._calc_shear_and_P: Start of _calc_shear_and_P
Debug Message ID: 0x0
Debug Task ID: 0xf
----------------------------------

Each time debug_message gets called, it increments the Debug Message ID, ensuring that each message has a unique ID number. The Debug Task ID shows which task to search for in the source window in portrait:

     task debug_task entry(0xf) {
009c     block ctrl_color;
009d     gpr_R6 = gpr_R2;
009e     arguments_recv.length = gpr_c_6;
00a0     UNBLOCK ctrl_color;}

The move instruction gpr_R6 = gpr_R2 got tagged with an instruction address of 009d by the compiler in this case. The 009d address is searchable in the pipeline window if the ADDR option is enabled at the top. Clicking on the line with that address will display the details of the instruction in the Instruction window. The value involved in the move will be displayed in the s1 and dst values in the Instruction window. When the s1 or dst value matches that in the Debug Message ID, the point in the graph where the debug_message was inserted has been found.

Parameters:

  • message (str) – descriptive string.

  • active (bool, optional) – Enable debug message. The default is True.

Return type:

None.

get_available_cmd_args()

WSE_Interface creates a default set of command line arguments through the argparse library. This function allows users to retrieve all command line arguments. To add more domain specific arguments see get_cmd_line_parser.

from WFA.WSE_Interface import WSE_Interface

wse = WSE_Interface()
args = wse.get_available_cmd_args()

#use args in further code
Returns:

The WSE_Interface args member variable.

Return type:

argparse.arguments

get_cmd_line_parser()

WSE_Interface creates a default set of command line arguments through the argparse library. This function allows users to get the parser created in the WSE_Interface so that domain specific arguments can be added as command line arguments.

from WFA.WSE_Interface import WSE_Interface

wse = WSE_Interface()
parser = wse.get_cmd_line_parser()

#Add CFD Specific command line arguments
parser.add_argument("-x","--x", help="specify x dimension",
                    type=int, default=10)
parser.add_argument("-y","--y", help="specify y dimension",
                    type=int, default=10)
parser.add_argument("-z", "--z", help="specify z dimension",
                    type=int, default=10)
args = wse.get_available_cmd_args()

#use args in further code
Returns:

The WSE_Interface parser member variable.

Return type:

argparse.parser

get_named_array(name)

Returns a python reference to an existing WSE_Array with name. When instantiating a WSE_Array object, an optional name parameter can be supplied. This tag is stored in a dictionary for later retrieval.

class MyCFDClass():
    def __init__(self, u_center, v_center, w_center):
        WSE_Array(name='u_center', initData=u_center)
        WSE_Array(name='v_center', initData=v_center)
        WSE_Array(name='w_center', initData=w_center)
        WSE_Array(name='press', initData=press)

Somewhere else in the code, a python object can be created which references the original WSE_Array by the name supplied. It can even be in a completely different class as long as the WSE_Interface singleton is instantiated.

def initialize_face_velocity(self, cell_type, debug_active=False):

    u = self._wse.get_named_array('u_center')
    v = self._wse.get_named_array('v_center')
    w = self._wse.get_named_array('w_center')

    # use u,v,w in further code
Parameters:

name (str) – The name given to the WSE_Array object to retrieve.

Raises:

ValueError – Name does not exist.

Returns:

The python reference to the WSE_Array with the unique name.

Return type:

WSE_Array

make_WSE(answer=None)

Compiles the code for the Wafer Scale Engine. Several command line options set compilation behavior. Any python script calls this script will have default command line arguments enabled. Use the -h option behind the python call to launch the script to get a listing of the available options.

Must be called once at the end of a program to compile the graph.

# problem setup

with WSE_For_Loop('time_loop', ts):
    if benchmark_iterations is not None:
        wse.record_timestamp()

    # Update T from current values
    T_n[1:-1, 0, 0] = center * T_n[1:-1, 0, 0]
        + c * (T_n[2:, 0, 0] + T_n[:-2, 0, 0]
               + T_n[1:-1, 1, 0] + T_n[1:-1, 0, -1]
               + T_n[1:-1, -1, 0] + T_n[1:-1, 0, 1])

# graph construction is now complete, so we can call make_wse
wse.make_WSE(answer=T_n)
Parameters:

answer (WSE_Array, WSE_Global_Scalar, optional) – A WSE_array or WSE_Global_Scalar that holds the answer for validation. The default is None.

Return type:

None.

print(*args, **kwargs)

calls python’s default print with flush=True if -dl <1,2,3> is set. Useful for debugging and following the python code during graph construction.

self._wse.print('------------------')
self._wse.print('WSE_Array.__add__')
self._wse.print('self:', self, id(self))
self._wse.print('other:', other, id(other))
self._wse.print('result:', result, id(result))
self._wse.print('------------------')
Parameters:

  • *args (args) – args to print in __builtin__.

  • **kwargs (kwargs) – kwargs to print in __builtin__.

Returns:

DESCRIPTION.

Return type:

TYPE

push_coded_index(coded_xy_array, length=None)

Commands the WSE to push a x-y-z position coded in an SP with 10 bit representation of x and y position and 12 bit representation of z position.

This is useful as the position data should come off the wafer in the same order as any SP data. It is useful for debugging and decoding the data. This function can be called once at the head of the simulation and the position data will be saved for the simulation.

Parameters:

  • coded_xy_array (WSE_Local_scalar) – A WSE_Local_Scalar that

  • length (int, optional) – override for specifying z to code into the data. If not specified, z is set to the default array size.

record_timestamp()

Records the cycle number in a defined symbol on the worker tiles for benchmarking. The symbol is set up to record 100 values in a circular buffer. In order to activate the timestamp recording, the -pcc 1 command line option must be set and one of -ts16 1 or -ts32 1 must be set.

with for_loop('max_outer_iters', max_outer_iters) as max_outer_iters_loop:
    with for_loop('reduction_limited_iters', num_reduction_lim_its):
        if self._benchmark_fluid_solver:
            self._wse.record_timestamp()
        self.ErrV[2:-2,0,0] = self.Vz[2:-2,0,0]
        self.ErrP[2:-2,0,0] = self.P[2:-2,0,0]
        self._calc_shear_and_P()
        self._calc_dV()
        self._update_V()
        self._bc_xyz(self.Vx, self.Vy, self.Vz)

        # more code
Return type:

None.