4.1.1. Main Block for Coupled Mode

pyHS2MF6 is designed for coupled mode simulation. This mode is expected to be the primary use case. For coupled mode simulation, the coupledMain module provides the coupled model controller and queue server functionality.

It will start independent mHSP2 and pyMF6 processes and will create, serve, and manage three message passing queues for interprocess communications.

4.1.1.1. coupledMain.py

pyHS2MF6 main block for running coupled simulations.

Provides custom multiprocessing, message passing interface queue manager or queue server. This needs to be executed as an independent process and then it will launch a queue server that manages three queues.

  1. From mHSP2 queue

  2. From pyMF6 queue

  3. Program control/termination queue

Each queue is associated with a socket and has an authorization key. The authorization key and correct socket/port are required for access from another client.

To run the coupled program, open an Anaconda prompt

  1. conda activate py3

  2. cd to the model main directory where the coupled input file is located

  3. python {path to this file} {coupled input file}

  4. python {path to this file} -h

    • will provide command line help

Typical usage example

python ..\LOCA\coupledMain.py LOCA_In.dat

coupledMain.AUTHKEY = b'authkey'

Authorization key for queue access.

This is not currently setup in a secure manner. If you plan on using pyHS2MF6 across a public or partially public network, then you should give some thought to the AUTHKEY and a means of securing this value. AUTHKEY needs to be encoded to a byte string.

coupledMain.CLIENTHOST = '127.0.0.1'

Host machine for queue clients.

Clients are on the same ‘machine’ as the queue server when local descriptors like ‘localhost’ or ‘127.0.0.1’ are used.

coupledMain.CreateQueueServer(ThisHost, Porter, CustomAuth, name=None, description=None)

Create and start the message passing queues.

Needs to be called 2 times, one for each queue. The “register” settings provide the basic method structure for our queues.

See the following links for more information.

Parameters

  • ThisHost (str) – host name. Should be ‘localhost’ for the same machine

  • Porter (int) – the port number to listen on

  • CustomAuth (str) – the custom authorization string

  • name (str) – the queue name

  • description (str) – the queue description

Returns

reference to the queue manager

Return type

coupledMain.QueueManager

coupledMain.HOST = 'localhost'

Host machine for queue server.

Localhost means that the process are set-up to be on all the same machine. The queue server and the clients are in different processes on the same ‘machine’.

coupledMain.HSP2_DESCRIPTION = 'HSP2 Queue Server'

Queue server description for from mHSP2 queue.

coupledMain.MF6_DESCRIPTION = 'MODFLOW 6 Queue Server'

Queue server description for from pyMF6 queue.

coupledMain.NAME_FROM_HSPF = 'qmHSP2'

Queue name for the from mHSP2 queue.

coupledMain.NAME_FROM_MF6 = 'qmMF6'

Queue name for the from pyMF6 queue.

coupledMain.NAME_FROM_TERM = 'qmTERM'

Queue name for the error handling queue.

coupledMain.PORT0 = 45492

Port number for the HSP2 queue.

Port numbers for queues need to be the same for each independent process for connection. Additionally, ports need to be opened in any firewall software even for local simulation.

coupledMain.PORT1 = 45493

Port number for the MODFLOW 6 queue.

Port numbers for queues need to be the same for each independent process for connection. Additionally, ports need to be opened in any firewall software even for local simulation.

coupledMain.PORT2 = 45494

Port number for global error handling and communications queue.

Port numbers for queues need to be the same for each independent process for connection. Additionally, ports need to be opened in any firewall software even for local simulation.

coupledMain.QEND_MSG = ['End']

End of simulation message

coupledMain.QINIT_MSG = ['Hello']

Queue intialization and check in message

coupledMain.QREADY_MSG = ['Ready']

Queue ready to start message

coupledMain.QUEUE_ERROR = ['Error']

Error message to put on queues for program termination

coupledMain.QUEUE_TIMEOUT = 3600.0

End of simulation wait time in seconds

class coupledMain.QueueManager(address=None, authkey=None, serializer='pickle', ctx=None)

Create the queue manager class.

Needs to be at top level of the module so that is pickleable. Do not need anything here except to subclass SyncManager.

coupledMain.QueueServerClient(ThisHost, Porter, CustomAuth)

Get a client connection a queue.

The connection is bidirectional and can use this connection for both get and put.

Parameters

  • ThisHost (str) – host name. Should be ‘127.0.0.1’ for the same machine

  • Porter (int) – the port number to listen on

  • CustomAuth (str) – the custom authorization string

Returns

the client connection

Return type

coupledMain.QueueManager

coupledMain.SHELL_CAPTURE = 'MF6_ShellOut.txt'

Text file name for capturing standard MODFLOW simulation output

coupledMain.START_QUEUE_TO = 300.0

Queue wait timeout before error in seconds.

This is for program startup communications.

coupledMain.TERM_DESCRIPTION = 'Termination Queue Server'

Queue server description for error handling queue.

coupledMain.WriteQueueCheckToLog(qHSP2, qMF6, qTERM)

Write queue checks to log file.

Parameters

  • qHSP2 (Queue) – the from HSP2 queue

  • qMF6 (Queue) – the from MODFLOW 6 queue

  • qTERM (Queue) – error handling queue

Returns

function status, success == 0

Return type

int

coupledMain.get_q(q)

Main level definition of the get function for queue definition.

This needs to be at this level so that pickle can find it.

Parameters

q (Queue) – queue to be returned

Returns

queue reference (i.e. return itself)

Return type

Queue

coupledMain.mHSP2_MAIN = 'locaMain.py'

Location of the standalone execution block for mHSP2.

coupledMain.processEndComm(StringList)

Process the end simulation communication with external processes.

Each external process, mHSP2 or pyMF6 will send an independent end of simulation message.

Parameters

StringList (list) – list of string items

Returns

function status, success == 0

Return type

int

coupledMain.processInitComm(StringList)

Process the initial communication with external processes.

The external processes are mHSP2 and pyMF6.

Parameters

StringList (list) – list of string items

Returns

function status, success == 0

Return type

int

coupledMain.processReadyComm(StringList)

Process the ready communication with an external processes.

Parameters

StringList (list) – list of string items

Returns

function status, success == 0

Return type

int

coupledMain.pyMF6_MAIN = 'pyMF6py.py'

Location of the standalone execution block for pyMF6.