This documentation covers both the User Guide for operating the Supply Chain Simulation Platform and the Deployment Guide for setting up the platform on AWS infrastructure.
\n| Section | \nDescription | \n
|---|---|
| User Guide | \nHow to use the platform: launching, running simulations, viewing results, and troubleshooting | \n
| Deployment Guide | \nHow to deploy the platform on AWS: EC2 setup, configuration, and maintenance | \n
This guide will help you get started with the Supply Chain Simulation Platform, from launching the application to running your first simulation and analyzing the results.
\nBefore using the platform, ensure you have:
\nsimulator folderIf you see the desktop shortcut, you're ready to go! Skip to Launching the Platform.
\nIf you don't see the desktop shortcut:
\ninstall.batTo use the AI-powered analysis and chat features, you'll need an API key from one of our supported providers:
\nSelect your AI provider:
\n\n\nNote: Without an API key, you can still run simulations and view results. Only the AI chat and automated insights features require an API key.
\n
When the platform loads, you'll see the main dashboard with a navigation sidebar on the left:
\n| Icon | \nSection | \nPurpose | \n
|---|---|---|
| Guide | \nUser Guide | \nIn-app help and documentation | \n
| Settings | \nSettings | \nConfigure AI provider and API keys | \n
| Setup | \nSetup | \nUpload and process your data | \n
| Simulation | \nSimulation | \nRun simulations and monitor progress | \n
| Results | \nResults | \nView simulation outputs and metrics | \n
| Analysis | \nAnalysis | \nAI-powered insights and chat | \n
The left sidebar provides access to all main sections. Click any icon to navigate to that section. The currently active section is highlighted.
\nFor quick help while using the platform, click the Guide icon in the sidebar. This provides step-by-step instructions for each feature directly within the application.
\nBefore running a simulation, you need three types of data files (CSV format):
\nSee Understanding Your Data for detailed requirements, or use our Sample Data to get started quickly.
\nAfter processing, you can optionally adjust demand settings:
\nThis file describes your supply chain network locations.
\n| Column | \nRequired | \nDescription | \n
|---|---|---|
| facility_id | \nYes | \nUnique identifier (e.g., \"WH001\", \"DCEAST\") | \n
| latitude | \nYes | \nGeographic latitude coordinate | \n
| longitude | \nYes | \nGeographic longitude coordinate | \n
| facility_type | \nRecommended | \nType of facility (e.g., \"WAREHOUSE\", \"DC\", \"STORE\") | \n
Example:
\nfacility_id,latitude,longitude,facility_type\nWH_001,34.0522,-118.2437,WAREHOUSE\nDC_EAST,40.7128,-74.0060,DISTRIBUTION_CENTER\nSTORE_101,37.7749,-122.4194,STOREThis file describes your product catalog. Weight and volume are required for accurate trailer loading calculations.
\n| Column | \nRequired | \nDescription | \n
|---|---|---|
| unitID | \nYes | \nProduct/SKU identifier | \n
| unitWeight | \nYes | \nWeight in pounds (lbs) | \n
| unitCube | \nYes | \nVolume in cubic feet | \n
| unitCost | \nOptional | \nUnit cost in USD | \n
Example:
\nunitID,unitWeight,unitCube,unitCost\nSKU_0001,15.5,0.75,49.99\nSKU_0002,8.2,0.35,24.99\nSKU_0003,42.0,2.10,149.99This file contains historical shipment data showing how products move through your network.
\n| Column | \nRequired | \nDescription | \n
|---|---|---|
| origin_facility | \nYes | \nSource facility ID | \n
| destination_facility | \nYes | \nDestination facility ID | \n
| timestamp | \nRecommended | \nWhen the shipment occurred | \n
| quantity | \nOptional | \nNumber of units shipped | \n
| sku | \nOptional | \nProduct identifier | \n
Example:
\norigin_facility,destination_facility,timestamp,quantity,sku\nWH_001,DC_EAST,2024-01-15 08:30:00,100,SKU_0001\nDC_EAST,STORE_101,2024-01-15 14:45:00,25,SKU_0001\nWH_001,STORE_101,2024-01-16 09:00:00,50,SKU_0002The platform includes sample data files to help you get started quickly.
\nSample data files are located in the sample_data folder within the installation directory.
| File | \nDescription | \nUse For | \n
|---|---|---|
facilities.csv | \nSample warehouse and distribution center locations | \nFacilities upload | \n
products.csv | \nSample product catalog with weights and volumes | \nProducts upload | \n
shipments.csv | \nSample historical shipment records | \nShipments upload | \n
sample_data folderSelect and upload all three files:
\nfacilities.csvproducts.csvshipments.csvThis will create a sample simulation that you can run immediately to explore the platform's features.
\nAfter running a simulation, the Results section provides comprehensive analytics.
\nThe main results view shows:
\n| Tab | \nWhat It Shows | \n
|---|---|
| Overview | \nHigh-level summary and key metrics | \n
| Facilities | \nIndividual facility performance and utilization | \n
| Network | \nNetwork-wide flow and routing metrics | \n
| Units | \nProduct movement and throughput | \n
The system automatically identifies potential issues:
\nClick on any anomaly to see details and potential optimization suggestions.
\nThe AI Analysis feature lets you ask questions about your simulation results in plain English.
\nSymptom: Nothing happens when you double-click the desktop shortcut
\nSolutions:
\nstart-platform.bat directly from the installation folderSymptom: Browser opens but shows a connection error
\nSolutions:
\nSymptom: The command window opens briefly then closes
\nSolutions:
\ninstall.bat again to ensure dependencies are installedSymptom: Simulation completes but shows 0 results
\nSolutions:
\nSymptom: AI chat shows an error or doesn't respond
\nSolutions:
\nSymptom: Validation fails with error messages
\nCommon issues:
\nSymptom: Can't find the platform shortcut on your desktop
\nSolutions:
\ninstall.batIf you encounter issues not covered in this guide:
\n| Action | \nShortcut | \n
|---|---|
| Submit chat message | \nEnter | \n
| New line in chat | \nShift + Enter | \n
| Service | \nURL | \n
|---|---|
| Dashboard | \nhttp://localhost | \n
| Item | \nLocation | \n
|---|---|
| Sample Data | \nsample_data/ folder | \n
| Configuration | \nconfig/settings.json | \n
| Simulation Outputs | \nsimulator/supply-chain-simulation-intelligence/data_session_*/outputs/ | \n
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.
\nAn alternative method for setup involves purchases the AMI (Amazon Machine Image) from the AWS Marketplace. Currently Simudyne offers a Linux AZ Linux and Windows Server 2022 version. There are a few benefits for choosing these options:\n
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.
\n\n
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:
\nAs 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.
\nSDK 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.
\nThe 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.
\nIf 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
\nBecause 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.
\nActions 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.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).
\nThe 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)
\nFor the below deployment guide you will need:
\nThere are 2 main things to consider with deployment of the SDK on AWS. The first is that most likely the amount of compute required to run your model will likely exceed the Free-Tier. The second is that if your AWS account was not set up by your organization (such as you are using a personal account) you should not be using your root account for deployment or operations. Please refer to the following page on best practices for usage of the root user. Other users, especially if customer-facing due to the requirement of running via command-line should be given as restricted accounts. (Only have access to a directory created for them with the relevant JAR file, no sudo access, etc).
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.
\npom.xml
\n<properties>\n <maven.compiler.source>1.8</maven.compiler.source>\n <maven.compiler.target>1.8</maven.compiler.target>\n <jodatime.version>2.10.1</jodatime.version>\n <junit.version>5.3.2</junit.version>\n</properties>You will then want to add the jodatime and junit dependencies to the section starting with '
pom.xml
\n<dependency>\n <groupId>org.junit.jupiter</groupId>\n <artifactId>junit-jupiter-api</artifactId>\n <version>${junit.version}</version>\n <scope>test</scope>\n </dependency>\n <dependency>\n <groupId>joda-time</groupId>\n <artifactId>joda-time</artifactId>\n <version>${jodatime.version}</version>\n</dependency>Finally you will add the plugins for packaging the project.
\npom.xml
\n<plugin>\n <groupId>org.apache.maven.plugins</groupId>\n <artifactId>maven-shade-plugin</artifactId>\n <version>3.2.1</version>\n <executions>\n <execution>\n <phase>package</phase>\n <goals>\n <goal>shade</goal>\n </goals>\n <configuration>\n <shadedArtifactAttached>true</shadedArtifactAttached>\n <shadedClassifierName>allinone</shadedClassifierName>\n <artifactSet>\n <includes>\n <include>*:*</include>\n </includes>\n </artifactSet>\n <transformers>\n <transformer implementation=\"org.apache.maven.plugins.shade.resource.AppendingTransformer\">\n <resource>reference.conf</resource>\n </transformer>\n <transformer implementation=\"org.apache.maven.plugins.shade.resource.ManifestResourceTransformer\">\n <main-Class>Main</main-Class>\n </transformer>\n </transformers>\n </configuration>\n </execution>\n </executions>\n</plugin>\n<plugin>\n <groupId>com.spotify</groupId>\n <artifactId>docker-maven-plugin</artifactId>\n <version>1.0.0</version>\n <configuration>\n <imageName>simudyne-maven-docker</imageName>\n <baseImage>simudyne/scala-sbt:2.11.12.1.0.4</baseImage>\n <entryPoint>[\"java\", \"-jar\", \"/${project.build.finalName}-allinone.jar\"]</entryPoint>\n <!-- copy the service's jar file from target into the root directory of the image -->\n <resources>\n <resource>\n <targetPath>/</targetPath>\n <directory>${project.build.directory}</directory>\n <include>${project.build.finalName}-allinone.jar</include>\n </resource>\n <resource>\n <targetPath>/root</targetPath>\n <directory>.</directory>\n <include>licenseKey</include>\n </resource>\n <resource>\n <targetPath>/</targetPath>\n <directory>.</directory>\n <include>simudyneSDK.properties</include>\n </resource>\n </resources>\n </configuration>\n</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.
\nNext 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.
\nOpen the Amazon EC2 console at https://console.aws.amazon.com/ec2/ and select the orange Launch instance button.
\nSet 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.
\nYou'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.
\nUnder 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)
\nFollow 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.
\nUnder 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.
\nIf 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.
\nKeep the default selections for the other configuration settings for your instance.
\nFinally from the summary panel on the right when you're ready, choose Launch instance. This will take a few minutes to complete.
\nOnce 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.
\nFirst 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.
\nPlease 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.
\nOnce 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.
\nThe files we'll need to move are
\nThe above guide assumes you are connecting to this instance as the root user (ec2-user for Linux, Adminstrator for Windows). However you should strongly consider setting up other users other than root, especially if this instance will be connected to by other clients to run the SDK software. While if your end-users may only connect via HTTP/HTTPS to the Console or your created Dashboard it is still better to run as a non-root user if possible.
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\nnot 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\n'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.
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.
\nNo 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.
\nAlternatively 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:
\nFinally click \"Launch Instance\" and follow the steps above on how to connect depending on your chosen operating system.
\nOnce 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.
\nThis 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.
\nThis 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)
\nMaking 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:
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.
\nIf 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.
\nBy 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.
\nAs 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.
\nIf 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.
\nThe Simudyne SDK's method for recovering from a disaster scenario is as follows:
\nThe best option for getting support is to email support@simudyne.com
\nYou can also hop into our Community Discord Server and ask a Simudyne Dev for help!
\n\n\tDiscord Server\nCurrently there are 2 tiers of support for the Simudyne SDK.
\n