{"data":{"markdownRemark":{"html":"

Introduction

\n

The simudyne.core.abm.supplykit module provides a set of classes for quickly defining and building a network-based\nsimulation of a supply chain. The API sits on top of core-abm allowing you to implement supply chain models\ncharacterized by distribution facilities, the products and goods they process, and the transport methods involved in\ndriving the flow throughout the network.

\n

The Supply Chain Toolkit contains 4 new modules for representing the supply chain as a network:

\n
    \n
  1. Facility Agent: Agent class that inherits simudyne.core.abm.Agent with added functionality.
    2. \n
  2. TransportMessage: Message class that inherits simudyne.core.graph.Message that contains predefined fields for\nhandling transport between Facility agents.
    3. \n
  3. Loading Bay: Loading Bay class that contains a transport queue for holding pending incoming and outgoing TransportMessage and an initializable loading dock for loading and unloading cargo.
    4. \n
  4. Product: Product class that can be extended to represent any type of unit that is moved through the system.
    5. \n
\n

These 4 modules can be extended and used to represent a supply chain network with Facility Agents that make up different\ntypes of distribution and warehouse facilities. These facilities interact by moving inventory via differentiated\nTransport Messages (Trucks, planes, etc), capturing the flow across the network.

\n

In this overview, the basic concepts, best practices, and strengths of the toolkit will be highlighted. Greater detail\non the implementation of each module, including specific best practices and code examples for using the modules are\nprovided on the individual module docs.

\n

The Best Problems for Applying the Supply Chain Toolkit

\n

The toolkit is best for studying network-level aspects of a supply chain and is most useful in solving problems related\nto operational constraints, facility placement, inventory placement, and especially good at dealing with large-scale\nsystems with significant flow between the nodes (100's of millions of units).

\n

The Simudyne SDK uses a patented graph computation approach to an agent-based model, this means that because we treat\nthe model as essentially a graph of nodes (agents) and edges (links) where communication between the agents is handled\nvia the passing of messages. This means that the SDK is best suited at treating the supply chain system as a graph but\nnot as well suited to representing the physics of motion. This doesn't mean it is not possible to simulate these types of systems, but it requires more complex features to handle real-time traffic information, etc.

\n

Below are some examples comparing and contrasting the less complex and more complex aspects of the approach:

\n

\n \n \n \n \n \n \n \n \n \n

\n

Data Preparation

\n

Before laying out the model classes, a good starting point is to prepare the data for ingestion into the model. This data will be used for setup of the agents and the topology of the network.

\n

This follows the same structure as the sections Agent Creation & Agent Connection, the only difference is that the Facility Agent has custom fields that need to be added to your CSV file that include the name, latitude, and longitude.

\n

In the sample model you can find the sample data files provided. The 2 key steps are laid out below:

\n
    \n
  1. Generate Agent Source files: create columns for id, name, latitude, and longitude (note that each unique id in the id column must be unique across all agent groups of all types)
    2. \n
  2. Generate Topology File: create a from and to column, that contains all the connections expected between the facilities.
    3. \n
\n

Sample Facility Source File\n\n \n \n \n \n \n \n \n \n \n

\n

Main Supply Chain Model Class

\n

The Supply Chain Model Class is defined in the same manner as any other model built in the Simudyne SDK.

\n

Just like how other models are established in the Simudyne SDK, your main model class will contain the standard init(), setup(), and step() functions.

\n

The below code represents a basic structure for a setup() method for generating the agents and environment using the\nSupply Chain Model Class.

\n

SupplyChainDemo.java

\n
public class SupplyChainDemo extends AgentBasedModel<SupplyChainDemo.Globals> {\n\n   public static final class Globals extends GlobalState {\n       // map for going from String Name of facility to long address\n       public Map<String, Long> destinationAddresses;\n   }\n\n   @Override\n   public void init() {\n      registerAgentTypes(FacilityTypeA.class, FacilityTypeB.class);\n      registerLinkTypes(Links.AToBLink.class);\n   }\n\n   @Override\n   public void setup() {\n      CSVSource facilityTypeASource = new CSVSource(\"data/facility_A_source.csv\");\n      \n      // temp map for populating globals name -> long id map (makes sending transport messages easier)\n      Map<String, Long> destAddr = new HashMap<>();\n      Group<FacilityTypeA> facilityTypeAGroup = loadGroup(FacilityTypeA.class, facilityTypeASource, fA -> {\n         fA.outboundLoadingBay = new LoadingBay(2);\n         destAddr.put(fA.name, fA.getID());\n      });\n\n      CSVSource facilityTypeBSource = new CSVSource(\"data/facility_B_source.csv\");\n      Group<FacilityTypeB> facilityTypeBGroup = loadGroup(FacilityTypeB.class, facilityTypeBSource, fB -> {\n         fB.inboundLoadingBay = new LoadingBay(2);\n         destAddr.put(fB.name, fB.getID());\n      });\n\n      getGlobals().destinationAddresses = destAddr;\n\n      CSVSource topology = new CSVSource(\"data/topology.csv\");\n      facilityTypeAGroup.loadConnections(facilityTypeBGroup, Links.AToBLink.class, topology);\n\n      super.setup();\n   }
\n

The FacilityTypeA.class and FacilityTypeB.class are extending the Facility.class and uses a CSVSource to generate the agent fields and the agent topology.

\n

In the sample model files you will also see the dummy data used to generate the agents.

\n

The 2 different facility groups also have LoadingBay classes initialized to handle inbound and outbound TransportMessage.

\n

The step() method has the following sequences of behaviors defined that call the underlying functions from the Facility.class

\n

SupplyChainDemo.java

\n
@Override\npublic void step() {\n    super.step();\n    run(FacilityTypeA.processOutboundLoadingBay);\n    run(FacilityTypeA.departOutboundTransport, FacilityTypeB.receiveInboundTransport);\n    run(FacilityTypeB.processInboundLoadingBay);\n}
\n

The specific behaviors that drive these actions are defined in the Facility implementation in the next section.

\n

Facility Classes

\n

The following functionality implemented is simply an example and there are numerous ways to define behaviors.

\n

2 different Facility classes have been implemented:

\n
    \n
  1. Facility Type A - generates products and ships them out
    2. \n
  2. Facility Type B - receives product shipments and stores them in inventory
    3. \n
\n

Facility Type A

\n

Facility Type A represents an abstract type of shipping facility where products or units originate and are sent to other\nfacilities. For the purposes of this model there is a single Facility Type A and a single Facility Type B.

\n

This facility only handles shipping and implements an OutboundLoadingBay and sends TransportMessage messages.

\n

The first behavior this facility executes is the processOutboundLoadingBay action that implements the following\nmethods.

\n

FacilityTypeA.java

\n
@Override\nprotected void processOutboundLoadingBay() {\n        // pull trucks from transport queue\n        pullTrucksFromQueue();\n        // generate products\n        long processingTime = getContext().getTick() + getPrng().getNextInt(60);\n        processedProducts.computeIfAbsent(processingTime, k -> new ArrayList<>()).addAll(generateProducts());\n        if (processedProducts.containsKey(getContext().getTick())) {\n            List<Product> readyToDepart = processedProducts.get(processingTime);\n            if (readyToDepart != null) {\n                readyToDepart.stream().forEach(product -> {\n                String destination = \"W\";\n                Optional<TransportMessage> potentialTransport = outboundLoadingBay.loadingDocks.values().stream().filter(transportMessage -> transportMessage != null && transportMessage.destination == destination).findAny();\n            if (potentialTransport.isPresent()) {\n                potentialTransport.get().objectContents.add(product);\n            } else {\n                generateTruck(\"W\");\n                pullTrucksFromQueue();\n            }\n        });\n     }\n   }\n}
\n

The first function pullTrucksFromQueue(), pulls trucks from the transport queue using the logic below. The above functionality calls a function called generateProducts() which just randomly creates Product objects to be added to the processedProducts map where a random tick in the future is the key and a list of Product objects is the value. There is also a generateTruck() method that can be seen in the sample model that generates a new TransportMessage for any location that cannot be found in the outbound loading dock.

\n

FacilityTypeA.java

\n
    // placeholder function for handling transport queue\npublic void pullTrucksFromQueue() {\n        if (outboundLoadingBay.transportQueue.size() != 0) {\n            List<Integer> emptyBays = findEmptyBays(outboundLoadingBay.loadingDocks);\n            while (emptyBays.size() > 0 && outboundLoadingBay.transportQueue.size() > 0) {\n                long nextQueuePosition = Collections.min(outboundLoadingBay.transportQueue.keySet());\n                TransportMessage nextTruck = outboundLoadingBay.transportQueue.get(nextQueuePosition);\n                int emptyBay = emptyBays.remove(0);\n                outboundLoadingBay.loadingDocks.put(emptyBay, nextTruck);\n                outboundLoadingBay.transportQueue.remove(nextQueuePosition);\n            }\n        }\n}\n\n// Placeholder function for finding empty bays\npublic List<Integer> findEmptyBays(Map<Integer, TransportMessage> loadingDocks) {\n        List<Integer> emptyBays = new ArrayList<>();\n            for (Map.Entry<Integer, TransportMessage> bay : loadingDocks.entrySet()) {\n                if (bay.getValue() == null) {\n                    emptyBays.add(bay.getKey());\n                }\n        }\n        return emptyBays;\n}
\n

The logic above pulls trucks based on queue position and places them in the OutboundLoadingBay so that they can be loaded with items ready to depart.

\n

Once processOutboundLoadingBay() is executed, the next function called in the run sequence is also a behavior of Facility Type A called departTransport() which can be seen below:

\n

FacilityTypeA.java

\n
@Override\nprotected void departTransport() {\n        List<TransportMessages.TransportMessage> departedTransport = new ArrayList<>();\n        outboundLoadingBay.loadingDocks.values().stream().filter(transport -> transport != null && transport.departureTime == getContext().getTick()).forEach(t -> {\n            departedTransport.add(t);\n            send(TransportMessages.TransportMessage.class, tMsg -> tMsg.constructWithProducts(t.id,\n                t.transportType, t.weightCapacity, t.volumeCapacity,\n                t.weight, t.volume, t.objectContents, t.arrivalTime,\n                t.departureTime, t.origin, t.destination\n            )).to(getGlobals().destinationAddresses.get(t.destination));\n        });\n        outboundLoadingBay.loadingDocks.entrySet().stream().forEach(bay -> {\n            if (departedTransport.contains(bay.getValue())) {\n                bay.setValue(null);\n            }\n        });\n}
\n

Here the facility is simply checking to see if any of the TransportMessage objects in the loading dock are ready to depart and sends them to their destination where Facility Type B executes its behaviors.

\n

Facility Type B

\n

Facility Type B represents an abstract facility that only receives shipments and stores them in inventory.

\n

This facility implements an InboundLoadingBay only and handles incoming TransportMessage messages.

\n

The first function that is implemented receives TransportMessage that have been sent from Facility Type A and places them in the TransportQueue of the InboundLoadingBay.

\n

FacilityTypeB.java

\n
@Override\nprotected void receiveInboundTransport() {\n    super.receiveInboundTransport();\n}
\n

Once inbound shipments have arrived, they are placed into the TransportQueue where the next behavior checks to see whether any messages have met the time condition necessary for them to be processed. The message has been received by the agent at this point, however an arrival time at some tick in the future is in the message and it will not be available at the loading dock until this time has passed.

\n

FacilityTypeB.java

\n
@Override\nprotected void processInboundLoadingBay() {\n    pullArrivingTransport();\n    unloadTransportCargo();\n}
\n

The pullArrivingTransport() function checks to see if any messages have an arrival time equal to or before the getContext().getTick() (current tick) as below:

\n

FacilityTypeB.java

\n
public void pullArrivingTransport() {\n        List<TransportMessages.TransportMessage> arrivedTransport = inboundLoadingBay.transportQueue.entrySet()\n            .stream()\n            .filter(entry -> entry.getKey() <= getContext().getTick())\n            .map(Map.Entry::getValue)\n            .collect(Collectors.toList());\n\n        if (!arrivedTransport.isEmpty()) {\n            List<Integer> emptyBays = findEmptyBays(inboundLoadingBay.loadingDocks);\n                while (arrivedTransport.size() > 0 && emptyBays.size() > 0) {\n                    TransportMessages.TransportMessage t = arrivedTransport.remove(0);\n                    int emptyBay = emptyBays.remove(0);\n                    inboundLoadingBay.loadingDocks.put(emptyBay, t);\n                }\n        }\n}
\n

This takes into account available loading bays to ensure that there a available bays to process the arriving shipment.

\n

The final step is to unload the trucks and place the inbound items in inventory as can be seen below in the implementation of unloadTransportCargo()

\n

FacilityTypeB.java

\n
public void unloadTransportCargo() {\n        List<TransportMessages.TransportMessage> processedtrucks = new ArrayList<>();\n        inboundLoadingBay.loadingDocks.values().stream().filter(dock -> dock != null).forEach(t -> {\n            List<Product> cargo = t.objectContents;\n            cargo.stream().forEach(p -> {\n                nbUnitsProcessed++;\n                totalShipmentCost = p.weight * shipmentCostPeLb;\n                inventory.computeIfAbsent(p.productID, k -> new ArrayList<>()).add(p);\n            });\n            processedtrucks.add(t);\n        });\n        inboundLoadingBay.loadingDocks.entrySet().stream().forEach(bay -> {\n            if (processedtrucks.contains(bay.getValue())) {\n                bay.setValue(null);\n            }\n        });\n}
\n

Conclusion

\n

The provided code and classes can be extended to any number of unique facility types and unique forms of transportation to best represent the desired real-world supply chain.

\n

Check out the individual model docs for the classes in the Supply Chain Toolkit for best practices on different scenarios and how to improve performance using multi-threaded processing techniques.

\n
    \n
  1. Facility
    2. \n
  2. Transport Message
    3. \n
  3. Loading Bay
    4. \n
  4. Product
    5. \n
","headings":[{"value":"Introduction","depth":2},{"value":"The Best Problems for Applying the Supply Chain Toolkit","depth":2},{"value":"Use Case Example - Simple Supply Chain","depth":2},{"value":"Data Preparation","depth":3},{"value":"Main Supply Chain Model Class","depth":3},{"value":"Facility Classes","depth":3},{"value":"Facility Type A","depth":4},{"value":"Facility Type B","depth":4},{"value":"Conclusion","depth":2}],"frontmatter":{"title":"Supply Chain Toolkit Overview","toc":null,"experimental":false}},"site":{"siteMetadata":{"title":"Simudyne Docs","latestVersion":"2.6"}}},"pageContext":{"absolutePath":"/home/vsts/work/1/s/content/2.6/docs/supply_chain_toolkit/supply_toolkit_overview.md","versioned":false,"version":"2.6","kind":"docs","pagePath":"/supply_chain_toolkit/supply_toolkit_overview","chronology":{"prev":{"name":"Supply Chain Tool Kit","path":"/supply_chain_toolkit"},"next":{"name":"Facility Agent","path":"/supply_chain_toolkit/facility"}},"lastUpdated":"2026-04-21T13:56:54.867Z"}}