As mentioned on our Run & Deploy page, there are multiple methods that one could employ for their deployment. For the purpose of this guide we will focus on deploying to an EC2 instance primarily, but you may also make usage of other AWS technologies such as an EMR cluster, or because the SDK can be packaged to a Docker container and/or Kubernetes there are multiple possible options to use with AWS. Please refer to the aforementioned pages for specific steps; however this guide will not cover all deployment options.

Information Guide

Before we move onto the specific step-by-step guide for deploying on AWS we'll first cover some possible questions you may have when working with the AWS environment. For a reminder, much of your development work does not require an AWS instance or account for building and testing your model.

Region/Availability Zones:

In short there are no formal restrictions on which AZ you set, or which region your resources are deployed too. From a deployment side there are a few requirements to run your packaged model:

• a packaged FatJAR file that you will create once your model development is ready
• a Simudyne license file
• a simudyneSDK.properties file
• an installation of JAVA 8 JDK
• any other external data/scripts/code that you require to run the simulation

As such when working with AWS you are free to use any region with any additional requirements being based on how you are loading data, which region you wish to make the simulation available in, or if there are other AWS software that your are using that is restricted to a specific AZ.

Operating System

SDK development and deployment is available on Windows, Mac, and Linux. You are free to use whichever OS you are most comfortable with. For deployment we recommend using either the Windows or the Amazon Linux AMI (and the below steps will be based on that). Because the SDK requires JAVA 8 JDK; please ensure the OS can support this installation.

Data

The Simudyne SDK generates a lot of data, and in turn can ingest multiple sources as needed both to set various parameters, control monte carlo style runs, and of course to dynamically create your agents. Please refer to our Data Management for steps on working with data in the SDK, but because there are multiple ways to work with data you should consider the best option for your AWS deployment.

If your data requirements are larger than what your EC2 instance can handle (especially if running multiple days of analysis) our recommendation would be to setup an S3 bucket, or make usage of the JDBC connection for access. Note however this is not required, and does necessitate an IAM role that has write or admin access to the S3 bucket in usage. For more information on how you can copy data between a created EC2 and S3 instance please refer to Use Amazon S3 with Amazon EC2

Sizing and Costs

Because the size and complexity of your SDK model is based on a combination of factors it's up to your to make the formal decision on what size instance you want to deploy on, and therefore it's associated costs. Part of your development time should be allocated to optimization, as making even seemingly small changes to an agent's function, how data is managed, etc can dramitically decrease the amount of memory or computation time required. Below are some key factors that will likely require you to want a larger deployment espeically if you are scaling up from your local machine.

• Number of agents, and how interconnected they are: If you've been developing the model with say 100 agents, but for the real deployment you need 1 Million - you will liekly require additional memory.
• Amount of data input/output: This will also determine if you wish you make usage of AWS S3 buckets to offload data after a run or import real data if you've been developing the model against sythentic data.
• Agent complexity: If your agents for example have very complex Actions due to a specific function or algorithm that for example runs in quadratic or exponential time - you will need to factor this algorithm's usage in your agents/codebase in regards to the time it takes a simulation to complete, and the performance of your deployment machine.
• Complex data structures: The SDK provides a network of agents with the ability to send messages based on those links; however because the models are writen in JAVA - you are free and encouraged to make usage of other data structures for whatever usage your model requires. Having those structure available in the globals and/or certain actions taken on those structures (such as frequent searches) may impact your performance. If these actions cannot be simplified or optimized than this will also affect simulation time and memory requirements.

The only mandatory requirement is (either directly or indirectly) an EC2 instance. Our recommendation for deployment would be something like an "r6i.large" instance with an hourly on-demand cost of $ 1.126. This is because the main bottleneck for most models will be memory (due to storing agents + user data in memory as needed), and as such other memory optimized instances are also what we would typically recommend. However your specific model may require a lot of CPU usage (if say for example you are reading in a large amount of data).

The license cost for your deployment is included with the provided license you've already been given as part of your model development with the AMI cost. (based on whether you are a free trial, developer, or enterprise user)

Deployment Guide

AWS Requirements

For the below deployment guide you will need:

• an AWS account which you can sign up for one here
• a very basic familiarity with both AWS console and Linux/Windows
• a completed model built in the SDK. This could be your own model, or one of our tutorials or sample models that you've downloaded and are using the following steps to test deployment
• a valid Simudyne SDK license file
• roughly 1 hour to complete

Packaging Your Model

The first step is to make a few changes to your pom.xml. Make sure you add the jodatime and junit versions to your properties section.

pom.xml

<properties>
  <maven.compiler.source>1.8</maven.compiler.source>
  <maven.compiler.target>1.8</maven.compiler.target>
  <jodatime.version>2.10.1</jodatime.version>
  <junit.version>5.3.2</junit.version>
</properties>

You will then want to add the jodatime and junit dependencies to the section starting with ''

pom.xml

<dependency>
      <groupId>org.junit.jupiter</groupId>
      <artifactId>junit-jupiter-api</artifactId>
      <version>${junit.version}</version>
      <scope>test</scope>
    </dependency>
    <dependency>
      <groupId>joda-time</groupId>
      <artifactId>joda-time</artifactId>
      <version>${jodatime.version}</version>
</dependency>

Finally you will add the plugins for packaging the project.

pom.xml

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-shade-plugin</artifactId>
  <version>3.2.1</version>
  <executions>
    <execution>
    <phase>package</phase>
    <goals>
      <goal>shade</goal>
    </goals>
    <configuration>
      <shadedArtifactAttached>true</shadedArtifactAttached>
      <shadedClassifierName>allinone</shadedClassifierName>
      <artifactSet>
        <includes>
          <include>*:*</include>
        </includes>
      </artifactSet>
      <transformers>
        <transformer implementation="org.apache.maven.plugins.shade.resource.AppendingTransformer">
          <resource>reference.conf</resource>
        </transformer>
        <transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
          <main-Class>Main</main-Class>
        </transformer>
      </transformers>
    </configuration>
    </execution>
  </executions>
</plugin>
<plugin>
  <groupId>com.spotify</groupId>
  <artifactId>docker-maven-plugin</artifactId>
  <version>1.0.0</version>
  <configuration>
    <imageName>simudyne-maven-docker</imageName>
    <baseImage>simudyne/scala-sbt:2.11.12.1.0.4</baseImage>
    <entryPoint>["java", "-jar", "/${project.build.finalName}-allinone.jar"]</entryPoint>
    <!-- copy the service's jar file from target into the root directory of the image -->
    <resources>
      <resource>
        <targetPath>/</targetPath>
        <directory>${project.build.directory}</directory>
        <include>${project.build.finalName}-allinone.jar</include>
      </resource>
      <resource>
        <targetPath>/root</targetPath>
        <directory>.</directory>
        <include>licenseKey</include>
      </resource>
      <resource>
        <targetPath>/</targetPath>
        <directory>.</directory>
        <include>simudyneSDK.properties</include>
      </resource>
    </resources>
  </configuration>
</plugin>

Once your pom has been updated you can the package everything into a single jar (allinone) by running 'mvn clean compile package -s settings.xml' inside the project's folder. You may need to use -s ~/.m2/settings.xml or similiar if your settings file is not included in the project directory.

Once you've run this you should have a large JAR file in your target directory under the main project directory.

Creating Your Instance

Next we'll create our instance. We'll outline the steps below, but you can always refer to the Official AWS Documentation for guidance on setting up a new instance.

• Open the Amazon EC2 console at https://console.aws.amazon.com/ec2/ and select the orange Launch instance button.

• Set a name for your instance, and then select OS. For the purpose of this guide you should stick to the default which is a Windows or Amazon Linux instance with a preselected Amazon Machine Image (AMI) already chosen for you.

• You'll then select the instance type. As covered above in the Sizing and Costs section under information this choice is largely dependent on the size and complexity of your model. If you are just trying to deploy for your first time to ensure that everything works, you can use the the t2.micro/t3.micro selected by default based on your region. This is also Free Tier eligible if you are simply testing things. However you will liekly wish to use a large and more memory-optimized machine for real deployments.

• Under Key pair (login) select 'Create new key pair' (unlesss you have already created or associated a key pair, or one has been assigned to you)

• Follow the steps to create a key pair, and make sure to select either .pem if you are working primarily on a Unix-based system, or .ppk if using Windows. Make sure you store this in a secure location as it will be necessary to connect to the instance.

• Under Network Settings unless you have already created a Security Group you will likely want to proceed with the default which will create one for you.

• If your goal with this deployment is to access the SDK either via the console, or via a dashboard created with the REST API you will then want to select the boxes allowing for HTTP/HTTPS traffic. However if you are running directly in the command line, then you will not need to choose these options.

• Keep the default selections for the other configuration settings for your instance.

• Finally from the summary panel on the right when you're ready, choose Launch instance. This will take a few minutes to complete.

Adding Your Files

Once you have created your instance you'll then want to find it's IP Address or Public DNS. If you followed the above steps and were taken to your new instance you should see this on the summary screen for the instance. Otherwise go to https://console.aws.amazon.com/ec2/ and select instances, and finally your desired instance.

For Linux

• First we'll connect to our instance directly via SSH. Per the above steps on creating a key pair you should have either a .pem or .ppk file dependent on your workstation. If you followed the above steps your default root username will be 'ec2-user'. If you are using a different AMI please refer to AWS Connect to Linux or the AMI provider for username.

• Please follow the steps for connecting via SSH to a machine per your current workstation operating system. Ensure that your private key is included as part of this connection.

• Once you have connected directly via SSH we now will want to move our relevant files to the instance. There are multiple ways you could do this (uploading and downloading if publically available for example); however for our purposes you should use a tool like FileZilla which will allow you to use your private key file and username to make a SFTP connection.

For Windows

• For Windows we'll connect via RDP. Please follow the connection steps here to connect to your Windows instance. From there downloading files via your approved internal file share (Dropbox/Onedrive/etc), or alternatively if you do not have an existing online file share we suggest uploading data to an S3 bucket and then downloading from there.

The files we'll need to move are

• a packaged FatJAR file that you created above
• a Simudyne license file
• a simudyneSDK.properties file

Running

Once everything has been moved and you are connected to machine running is as simple as java -jar NAMEOFYOURJARHERE.jar. Of course if this is meant to be a long running process (aka not a batch style run, btu something accessible via the web) you will want to use tools to keep the process running after your close your login session. For Linux the recommendation Simudyne suggests would be 'tmux' which you can find a tmux beginner's guide here. For Windows you can use the javaw instead of java to maintain a long-running process.

Troubleshoot

• Unable to create jar: Please either refer to the command prompt for any specific error that would prevent the jar from being created (such as a compile error). If however there are no issues but a file is not created, please refer to your pom.xml to ensure that the above plugins are included.

• Connection to instance failed: If you have followed the above steps and despite using the correct DNS/IP address, private key file, and username are still unable to connect to your EC2 instance you will want to refer to the following AWS Documentation to best troubleshoot.

• No Java detected: If the AMI instance you are using does not have Java 8 JDK installed already you (as the root ec2-user) will need to run the following command sudo yum install java-1.8.0-openjdk-devel or download an installer is using Windows as the Adminstrator

• Contacting Support: If you are still unable to resolve issues with your deployment, please feel free to contact support@simudyne.com for assisstance. Please note however some issues such as a key pair or instance created by your organizations IT may require working with additional personnel not on the Simudyne team.

Setting up via AMI

Purchasing from Marketplace

• Simudyne SDK on Amazon Linux 2023
• Simudyne SDK on Windows Server 2022
• AWS EC2 Console

Alternatively after clicking "Launch Instance" from the EC2 console click "Browse more AMIs" and search for "Simudyne". After selecting the Linux or Windows version you'll want to either click Subscribe now or on launch. From here it's essentially the same steps as setting up any new instance on AWS. No other configuration on the Simudyne side is required - you'll still need to:

• Create or make usage of an existing Key pair
• Select the size of the machine taking note that the Simudyne AMI is approved for either r6i, r6a, r7i, or r7a machines as they are a suitable memory and cpu limit for running a production system.
• Configure your network security group, and decide if you wish for the machine to be available to HTTP/S traffic
• Set your storage options and size. The AMI is configured for only EBS style storage

Finally click "Launch Instance" and follow the steps above on how to connect depending on your chosen operating system.

Maintaining Your Deployment

Monitoring and Logging

Once you have successfully deployed your Simudyne SDK models to your new AWS instance there are a few steps you can take to monitor the simulation run, and how to best handle situations where something goes wrong.

This also will not cover the myriad of available tools you have available to either monitor the health of the instance (which you would do via the AWS Console), or some other tool to monitor the process on your instance. Please refer to the user guide for those tools to confirm how to monitor as directed. The most common monitoring toolset would be something like the 'top' command on a Linux instance.

This will differ based on the toolset used for maintaining the simulation as a daemon process (for example tmux attach -t 0 being the most likely command on Linux) Please refer to the guide for this toolset in order to view the output from the running process to check for runtime errors. If you are simply running in command line for a batch style run and have not set up a daemon for the java jar command you can simply refer to the current output.

The Simudyne SDK has a built-in health check which you can use to confirm that your models are deterministic. This can be enabled in your simudyneSDK.properties file by setting nexus-server.health-check to true. Note that this health check will only work by running a few ticks of your model in two separate harnesses and then compare the results to see if given the same seed they match. This matching can also make usage of Atomic Logging

If you wish you can make usage of a Log4J.properties file with your own desired settings in order to get a more verbose output for monitor where your simulation is in terms of processing. This can also be used in conjunction with the Atomic Logging feature. Atomic Logging is a newer experimental feature that allows a greater visibility into the specific actions/sequencing/message sending/and more for your simulation. It also allows you to easily create points in the simulation where you cna log output as needed (without having to add multiple imports and checks to write to output)

Updates

Making changes to your deployment is as simple as replacing the jar file with a newly packaged jar file. As usual if you wish to upgrade the version of the Simudyne SDK or any other dependencies you will need to make the corresponding changes to your pom.xml on your workstation. However once you've confirmed that any changes you've made are correct and are able to package and test on your workstation then you don't need to make any other changes on the AWS side. There are a few caveats to this however:

• Ideally if you are making these updates you should consider setting version numbers to your jaf file and now overwriting the file directly. This way you can stop the current JAVA process of your deployment and test with the new one, but still be able to revert back quickly if a problem arises.
• If you are using the Nexus Console - you will be unable to run both processes simultaneously (if trying to do a hotswap) as this will give an error stating that the port is already in usage.
• Most notably this update step ignores any other external processes which you will need to follow per your simulations requirements. (Such as if there's changes required to the loaded dataset, connection credentials in your properties file, or post-processing scripts)

System Updates

It is recommended for you to stop any Simudyne SDK software when making changes to the underlying instance. The simulation should not be affected by any security or other updates; however ensure that the JAVA OpenJDK version is maintained as JAVA 8.

Updating License

If your license has expired you will receive an error in the output (or in Simudyne Console) informing you as such. Once you have been granted or purchased a new license file the best option would be to rename the file to just 'licenseKey' (no extension) and replace the file directly. From there you can try to re-run the simulation jar.

Key Pairs/Passwords

By default the Simudyne software does not provide any password for access to it's simulations. As such if you wish to make a dashboard only available to either a certain group of people (with either a set password, or a login system) then you will need to include this in your custom dashboard making usage of the REST API.

As well if you are primarily running simulations via the command line directly on the instance it would be best to setup a policy for your Key Pairs and subsequently SSH access to be rotated at a scheduled consistent with your organizations security policies. Typically Simudyne would recommend that you make these changes as part of the license file update (which lasts for 1-year) at a minimum.

AWS Service Limits

If you are deploying to a single instance (and not a Docker-based deployment) per above you will likely not require any additional service limits beyond the default. The caveats to this include whether you are using an existing account of one setup by your organization. This will require you to request "All Standard (A, C, D, H, I, M, R, T, Z) Spot Instance Requests" and/or "EC2-VPC Elastic IPs" as the compute and IP addressess are what is required for a typical setup.

Disaster Scenario

The Simudyne SDK's method for recovering from a disaster scenario is as follows:

• Ensure that any work on any workstation is maintained in a versionning software such as Git. This is useful even in normal situations such as user change or working with multiple developers.
• Backup as desired any packaged jars used for deployments. Because deployment is so simplistic, if you need to re-deploy elsewhere the process for doing is simple, and any relevant files (such as license or properties) will be available on workstations.
• Our PRNG ensures that if a simulation were to fail mid-run either through a sweep or script, because the results will be the same you can simply re-run the simulation. This however does not account for working with live/streaming data. If you are using input data that can be updated or modified our recommendation would be to create separate 'snapshots' of this data that your Simudyne SDK model can be re-run against should a run fail.

Contacting Support

The best option for getting support is to email support@simudyne.com

You can also hop into our Community Discord Server and ask a Simudyne Dev for help!

Currently there are 2 tiers of support for the Simudyne SDK.

• Limited to no support is available for those using a free or trial license.
• Dedicated support-team and developers will be assigned to any tickets created via our email system above if you have purchased a license.
• During contract discussions businessess may request "modeling support" which involves assigning a member of our team or more likely a 3rd-party partner to said contract to provide support beyong technical, development, or deployment issues in order to help build the underlying model.