August 2021

Configuration of Simulation Agents for InfoWorks

2

Contents

Introduction .............................................................................................................................................................................................................................3

Configuration of a Standalone Machine.................................................................................................................................................4

Default installation settings............................................................................................................................................................................4

Advanced settings – Use of network drives for Standalone databases....................................................4

Advanced settings – Storing results on a file server ........................................................................................................4

Configuration of a Workgroup environment.................................................................................................................................... 6

Setting up a Coordinator .................................................................................................................................................................................. 6

Configuration of the Remote Results Root ................................................................................................................................. 9

Setting Up the Remote Agent(s) ...........................................................................................................................................................10

Scheduling Remote Simulations ..........................................................................................................................................................10

Configuration of a Workgroup for a CITRIX environment................................................................................................ 11

Configuring Agent Groups .................................................................................................................................................................................. 12

Managing different ICM versions ................................................................................................................................................................ 14

Appendix A: Changing the Agent service account................................................................................................................. 15

Appendix B: The Manage Job Agents window........................................................................................................................... 17

Appendix C: Agent options.................................................................................................................................................................................19

Appendix D: Special measures for specific ICM versions............................................................................................... 21

Permissions issues for v6.5 and earlier.......................................................................................................................................... 21

Licence issues for v6.5 and earlier ..................................................................................................................................................... 21

Soft Licence issues for v7.0, v7.0.1 and v7.0.2 ....................................................................................................................... 22

3

Introduction

This document describes recommended configuration options for InfoWorks ICM Simulation Agents within different environments. As well as recommended configuration options, it describes some of the alternative configuration options which could be considered when tailoring a system to the user’s precise needs.

It is assumed that the user is already familiar with the key concepts from the Innovyze Workgroup Client as outlined in the document “Innovyze Workgroup Products IT Architecture”. It is recommended that reader should familiarise themselves with these concepts before attempting to change the configuration of any existing installation.

The list of possible factors which could affect the configuration of an ICM simulation environments is very long and this document is not intended to be exhaustive in describing these. The aim is to provide some standard advice, which should work effectively for most users – and some warnings of potential pitfalls to be avoided.

Some of factors to consider are listed below:

• Type & location of the master database

• Account settings & permissions for the agent

• Location of the simulation agent service

• Location of agent working storage

• Location & permissions for results storage

• Side by side installation of multiple ICM versions

• Licence configuration

• 64-bit vs 32-bit installations

• Use of GPUs for 2D simulations

Not all of these factors need to be considered in all circumstances, but an awareness of the potential impact of these factors is important when preparing an ICM configuration.

The recommendations made in this document apply to versions 7.0 onwards InfoWorks ICM. The reader should be aware that earlier versions of the software may behave slightly differently as the software has been enhanced from release to release. Where there are significant differences, these will be noted in the text.

Note that this document does not cover the configuration requirements for ICM Live, which has its own configuration needs.

4

Configuration of a Standalone Machine

Default installation settings When InfoWorks ICM is installed on to a PC, it will automatically install the Workgroup Client software and an ICM Agent service. The Agent service will be set up to run using the SYSTEM account on the PC. This allows simulations to run, even when the user is logged off from the PC. This configuration should allow the user to carry out simulations on the local machine without the need for any changes whether working with a Standalone database or a Workgroup database.

See Appendix B for information on how to inspect and modify the Agent settings for the Local Agent.

Advanced settings – Use of network drives for Standalone databases In ICM versions prior to v7.0, working with a Standalone database stored on a network file share could lead to problems, where the Agent (running as the SYSTEM user) did not have permission to access the required database files. Note that storage of a Standalone database on a network drive is not a recommended option (see the Workgroup Products IT Architecture document). In this case, the options were (in order of preference):

1) Move the Standalone database to the local machine (always recommended).

2) Change the permissions on the file share to allow the SYSTEM account access.

3) Change the Agent service to run as a different user (with the necessary permissions).

In ICM v7.0 the agent can run simulations using the permissions of the user who started the job. This allows simulations and meshing jobs to access any file share locations which are available to the user.

Advanced settings – Storing results on a file server When a simulation is run on a standalone machine, the results are usually stored in the user’s Local Results Folder. By default, this is a location on the local machine, which can be modified by the user (Tools->Options->Local Folders).

Since results files can take up a lot of space, users often have a wish to store results on a file server to provide additional storage space and provide a backup capability. In this case, there are two options available to the user.

5

1) Configure the Remote Results Root for the database (see below).

2) Move the Local Results Folder on to a shared file location.

The use of the Remote Results Root is the most flexible and useful option, but it requires a machine to act as a Coordinator and will almost certainly require administrator privileges to configure correctly (see Configuration of a Workgroup Environment).

For users without administrator privilege, it may be sufficient to specify the Local Results Folder to be a network location specific to that user. This will allow the local agent to put results on the file server, using the user’s (not the agent’s) access privileges.

This folder must not be used by any other user, otherwise serious problems could occur. You should also be aware that whenever the Local Results Root is changed, access to all results in the old location will be lost – unless the files are manually copied to the new location.

This option will require ICM v7.0 to work correctly and is intended purely as a Standalone option – it does not provide a mechanism for sharing of results. Sharing of results with other users requires a Remote Results Root.

Note that this approach only applies to the Local Results Folder. The Local Working Folder should never be configured to reside on a network location.

6

Configuration of a Workgroup environment

One of the key abilities of InfoWorks ICM Agents is to allow simulations to take place within a Workgroup. This means that a team of modellers can run simulations on machines other that the local PC. For example, you may have several modellers sharing a powerful server which can be used to carry out simulations without tying up the local PC resources.

As the simplest possible case, the rest of this section describes the setting up of a Workgroup of two PCs, one used for building and testing the model, called PC1, and one for carrying out simulations, PC2.

There are a few things to consider when setting up a workgroup environment.

• A Workgroup database should always be used.

• One machine must always be configured to act as a Coordinator for the Workgroup.

• If you want to share results with other users, you must specify a Remote Results Root for the database.

Setting up a Coordinator The Coordinator has two jobs. Firstly, it controls which Agents are available to carry out simulations in the Workgroup and secondly, it is responsible for uploading the results of simulations from all Agents to the Remote Results Root.

Any machine may be configured to act as a coordinator, if it has the Agent installed and it has network connectivity to all the machines in the Workgroup and access to the location specified by the Remote Results Root for the database. In this case, we are setting up PC2 as both the coordinator and a Remote Agent.

PC1

Local Agent

PC2 Remote Agent

Coordinator

Remote Root

7

The Agent may be installed as part of a normal ICM install or, if the Coordinator machine does not need to run the ICM user interface, then you can use the Remote Agent installer to provide just the Agent software and the ICM Simulation Engine.

If the Coordinator machine is running ICM, then the Agent configuration can be accessed using the Manage Job Agents dialog (see Appendix B). If the machine is using just the Remote Agent setup, then you will need to run the ICM Agent Manager (this will require administrator privileges).

Once logged into PC2, whether using the Manage Job Agent window or the Agent Manager, the first step is to choose the “Workgroup” option and select “Use this agent as the coordinator” as shown below and apply/save the changes. This Agent will now act as the Coordinator for the Workgroup.

8

To complete the Workgroup, it is necessary to run ICM on the other machine(s) in the Workgroup (PC1) and open the “Manage Job Agents” dialog where it is possible to set the Coordinator name (PC2) for the Local Agent:

9

Remember that there can only be one Coordinator in a Workgroup and all machines in the Workgroup need to be set up to use the same Coordinator.

Configuration of the Remote Results Root Once the coordinator is configured, then the storage of results for the workgroup should setup by specifying the Remote Results Root.

The Remote Results Root is a property of the database and is initially specified by using the dialog under File->Master database settings->Set Remote Roots…

10

The Coordinator of a Workgroup is responsible for the uploading of results to the Remote Results Root. All Agents in the Workgroup use the Coordinator to access this location. As a result, it is essential that the Agent which is acting as the Coordinator has the necessary permission to write to the Remote Result Root location. Since the Coordinator Agent will usually be running under the System account, it will usually not have the necessary privileges automatically.

The recommended method to provide access a network resource to an Agent running under the SYSTEM account is to grant file share permission to the SYSTEM account on the Agent Machine. This can be achieved for a network file share in a domain environment by giving access to the file share for the account identified by MACHINE_NAME$, where MACHINE_NAME is the name of the PC running the Agent.

An alternative approach is to change the Agent service account login details. This is described in Appendix A.

Setting Up the Remote Agent(s) Now that you have set up the Workgroup, you will want to make sure that each agent in the Workgroup is configured to play its part. To enable an Agent to carry out simulations for a user on another machine, the Agent must have the setting “Act as a remote agent”.

Unlike the case when running local simulations, a machine acting as a Remote Agent must be explicitly told which licence to use for the simulation engine. As a result, when “Act as a remote agent” is ticked in the dialog above, the licence settings become active. The licence may be any of the normal types: fixed or floating software licences, or any type of dongle. When the Agent starts a remote simulation, the simulation engine will use this information to acquire the appropriate licence.

If a machine is part of a Workgroup, but does not have “Act as a remote agent” checked, then the machine will be able to schedule jobs to other remote Agents, but will not run simulations for other machines.

If you have a large Workgroup, you may consider unchecking this option for the Coordinator machine, so that the Coordinator is responsible only for managing the Workgroup and does not have the overhead of running simulations itself.

Scheduling Remote Simulations Now that you have configured your workgroup, you will be able to schedule simulations on remote machines. When you run a simulation the “Schedule Job(s)” dialog will offer a range of options for which machine to be user for the simulation.

You may select “This computer” to run a local simulation, or select a named computer. The named computers may be able to run multiple simultaneous simulation and will tell you how many “free slots” are available for simulations on that machine. You may also select “Any computer” to allow the Coordinator to select a machine automatically for you.

The “Store Results” options allow results to either be stored in the users Local Results Folder (Locally) or in the Remote Results Folder (On Server). If you use the second option, the Coordinator will manage the upload of results to the server.

11

Configuration of a Workgroup for a CITRIX environment

If you are using ICM in a CITRIX environment, then it is always recommended to use a Workgroup configuration.

In this situation, you would normally run the ICM user interface on the CITRIX server and configure one or more other machines running remote agents. This will allow you to move the most computationally intensive operations (simulations and mesh construction) from the CITRIX server and onto dedicated machines.

Running local simulations in a CITRIX environment is likely to badly impact the performance of the CITRIX server and should normally be avoided. Because of this, the local agent running on the CITRIX server should normally use the option “Do not allow simulation on ‘This computer’”. Setting this option will mean that users may only select remote machines in the workgroup to carry out simulations (see Agent Options in the Appendices).

12

Configuring Agent Groups

For large workgroups, rather than providing a long list of computer names for users to select from, it may be useful to group machines. Machines may be grouped for various reasons: for example, to group machines by licence type. Grouping machines with 1D licences and those with 2D licences separately will allow users to select the agent group appropriate to the type of simulation they are carrying out.

Agent groups are managed by the coordinator. Loading the coordinator settings and pressing “Configure” will show the “Coordinator Settings” dialog (above). This will allow you to create agent groups and assign machines to a group. It is also possible to limit the databases from which a group may run simulations.

If desired, it is also possible to restrict the display of individual remote agents based on whether they are part of a group.

13

Once you have configured the Coordinator settings, make sure that they are saved back to the Coordinator in the Manage Job Agents dialog for the changes to take effect. After the Coordinator agent has restarted, running simulations should allow the user to select the agent group and the coordinator will allocate the simulation to a machine within the selected group.

14

Managing different ICM versions

For many users there is a need to allow multiple versions of InfoWorks ICM on a given machine, or within a Workgroup. This requirement is fully supported by the Workgroup framework, as Agents are not only able to manage simulations for the same version of ICM as the Agent, but for all earlier versions of the software. To support this, when installing a newer version of ICM on a machine, the newer version of the Agent will be installed and will automatically run as the Agent service.

When a run is scheduled on such a machine from a user running an older version of ICM (locally or as a remote simulation), then the Agent will run the simulation using the same version of the engine as the version of ICM used to schedule the simulation. It is important to note that, for compatibility, the engine version must be exactly the same – even to the patch/build number level. The list of all installed engines and their exact version can be viewed via the “About InfoWorks” information on any machine.

Since any ICM installer will automatically set its version of an Agent to act as the Agent for the machine, installing an older version of ICM onto a machine can prevent simulations from newer version being carried out. This is easily fixed by running the Agent Manager for the newest version. If the Agent Manager detects that a different version of the Agent is running, then you will be prompted to change to the newest version:

Clicking on Yes will make sure that the appropriate version of the Agent Manager is used.

15

Appendix A: Changing the Agent service account

Under some circumstances, it may be necessary to change the account which is used to run the InfoWorks ICM Agent. This is only normally required where the Agent (acting as a coordinator) requires access to a network resource for which the default SYSTEM account does not have the necessary access permissions. The account selected may be an individual user’s account, but it is generally recommended that a specific account be created for the service to use, taking care to ensure its password never expires and that is has permission to access the relevant resources.

Note that to change the Agent service account will require administrator privileges for the machine on which the Agent is running.

From the services control panel, locate the InfoWorks ICM Agent and select Properties from the right-click context menu.

The account details can be controlled from the Log On tab of the service Properties dialog (see below). The Agent account to be used will depend on the circumstances. Ideally, the accounts should not have password expiry settings that will require the Log On information to be updated regularly.

Once the service is restarted, the Agent service will use the new Log On settings and acquire the permissions associated with the specified account.

16

17

Appendix B: The Manage Job Agents window The configuration of any Agent (including the local Agent) can be inspected and modified using ICM by clicking on the “Manage job agents” button in the Job control window, as shown below. This dialog covers many of the same options as the Agent Manager program, but does not require administrator privileges to access it.

The default settings for the Local Agent, installed as part of the ICM Client are shown below.

18

Help in using this dialog is available in the Online Help, but it is helpful to point out the significance of the some of the options.

Local Agent It is possible to switch between connecting using a local pipe on the same computer (the default) and connecting using TCP/IP (needed if the local agent is on a different computer) (This terminology can confuse: this a “software pipe”, not a water-bearing feature!). If using TCP/IP, the name of the other computer and the TCP/IP port number must be specified (this port is the SIMPORT specified in the configuration of the Local Agent).

The status of the connection is shown and the Reconnect button can be used to force a reconnection after changing the connection settings.

Connected job agents Provided InfoWorks ICM is connected to the Local Agent, the “Connected job agents” section will include the Local Agent. If the Local Agent is connected to the Coordinator, it will also show the Coordinator and all Agents that are connected to the Coordinator (both Remote Agents and other Local Agents).

Agent configuration To make use of Agents other than the Local Agent, one Agent must be configured to act as the Coordinator and all Agents, both Local and Remote, must be configured to connect to the Coordinator. It is also necessary to have a Coordinator if you wish to make use of the “Remote Results Root” to shared results amongst users.

19

Appendix C: Agent options

Click the Agent options button in the Manage Job Agents window to display the Agent Options Dialog.

Normally, there would be no reason to change the TCP/IP ports unless there was a conflict with another networked application. These ports need to be open for all machines in a Workgroup environment.

The Housekeeping options allow inactive jobs to be removed from the queue after a specified period of time. The “Delete working files” period can be important for large Workgroups running large numbers of simulations. Setting this period appropriately can prevent large numbers of files from building up in the Agent working folder.

Normally the Agent provides logging information for troubleshooting purposes. If the logs are growing too large, you may wish to reduce the logging to “Basic”. You would only usually use the Trace option for short periods of time, when advised to do so by Innovyze support staff.

20

The Max threads total field is used to specify the maximum total number of threads to be used by all active simulation and mesh jobs running on the specified Agent. If set to 0, the actual limit is set to the number of cores on the machine.

The total thread limit is shared equally amongst active jobs. Each active job is allocated at least one thread (even if this takes the total threads above the limit). Per-job limits (specified on the Schedule Job(s) Dialog) are not exceeded.

A priority job (started using the Run immediately button in the Job Control window) is allocated the total number of threads and runs at a higher priority than the already

active jobs, each of which is allocated a single thread.

If you want to make sure that a machine running the Agent does not run simulations (e.g. in a CITRIX environment) then check “Do not allow simulation on ‘This computer’”.

By default, any user can load and save changes to an Agent running on any machine on the local network via the Manage Job Agents dialog. Clearly, this may be an undesirable way to manage the Workgroup and hence the Agent Options allow an Agent to restrict the users who are able to save changes to the configuration. By allowing the user to provide a list of databases which are used by the Agent, permission to make configurations can be limited to the database owners for the specified databases. This provides greater control over the configuration of the individual Agents and the workgroup as a whole.

The custom settings allow additional options to be applied to the Agent, which are not available via the user interface. Such settings are very rarely required and should only be applied on the advice of the Innovyze Support Team.

21

Appendix D: Special measures for specific ICM versions

There are some known issues with the behaviour of the ICM Agent in in some releases of ICM that cause problems. Although these have been addressed in later versions of the software, the issues are discussed here for users who need to run older versions of ICM.

Permissions issues for v6.5 and earlier As described in the main document, when running local simulation with releases prior to ICM 7.0, the Agent would often fail to correctly acquire the permissions of the user who initiated the simulation. This would cause problems where the default System account did not have the necessary permission to access the resources required to carry out the simulation.

The common solution for this problem would be to run the Simulation Agent under the user’s account (as described in Appendix A). This is undesirable because:

(a) It requires administrator privileges to complete.

(b) User passwords are frequently set to expire, stopping the Agent from operating.

(c) Group policy settings can prevent the use of user accounts for services.

This solution should not be necessary in ICM v7.0 or later and any Local Agent should normally be run under the default System Account (see the section on “Configuring a coordinator” for possible exceptions).

Licence issues for v6.5 and earlier The failure of the Agent to acquire the permissions of the user could also lead to licence failures for the simulation engine, since the engine (running as System) would not be able to read the user’s licence settings. This could be addressed by running the Licence Setup program and using the option to “Choose the licence to use for all users on this computer”.

This would allow the System account to access the correct licence settings and work normally. This situation was also undesirable, since this option again required Administrator privileges for the Licence Setup Wizard to complete the operation. Again, the need for this option has been removed in v7.0 of ICM.

22

Soft Licence issues for v7.0, v7.0.1 and v7.0.2 There was an issue discovered in ICM v7.0 which caused intermittent licence failures for the Simulation Engine when using Network Soft Licences. This problem has been fixed in patch release v7.0.3 of ICM. For users of v7.0 – v7.0.2 accessing such licences the only workaround was to set the Local Agent to login using the user’s credentials. This was undesirable for the same reasons as listed above.

In release v7.0.3, this workaround is no longer required and the recommendation is to use the default SYSTEM account for the Agent settings.