Portal

Portal: Container for a Subsystem

A Portal object appears on the screen like any other object but rather than having a fixed behaviour, it is a link to a sub-system screen.

Every Portal contains one Subsystem screen on which there is always at least one Portal Entry and one Portal Exit. A Portal can be classified as “Logical Only”, as it cannot itself hold items. Only the capacity objects in the subsystem can hold items.

No time passes while an item moves into or out of a Portal. An item entering a portal is 'teleported' to the sub-system screen and appears on that screen at the Portal Entry object, and proceeds along its path. Likewise, any item entering a Portal Exit on a subsystem screen will re-appear on the screen containing the Portal which owns that subsystem, and proceed along the path.

About Subsystems

A sub-system in Planimate® is another screen somewhere "below" the Main screen. Every Portal has only one sub-system.

You can create subsystems to form a hierarchical model structure and compose complex models using a number of screens.

Here is an example of a model hierarchy.

Each of the levels here is a subsystem.

The subsystem is represented in its parent (owning) screen as a portal.

Every Sub-system has at least one Portal Entry and Portal Exit.

Subsystems can also contain normal entries and exits.

Hierarchical Model Structure

Creating sub-systems forms a hierarchical model structure and enables complex models to be composed of a number of screens. This reduces screen clutter and makes a model easier to understand. A Sub-System can be a useful means of representing a major function of thesystem being modelled, or a separate physical location.

Uses for Sub-Systems

The physical location of one part of a system often provides a constraint to performance. If you contain this part of the system within a portal, you can use its subsystem to demonstrate this finite capacity within what you are modelling. You can build a number of subsystems that can be substituted for one another in a single model. This makes developing and testing options for various treatments of areas within your model very convenient to do.

Another use for sub-systems is when you wish to perform a "What-if? " study in the model. Different subsystems can represent different models, which you can run together or separately and between which you can compare behaviour and performance results.

You can also link Portals to other Portals using Spatial Links, Tracks or Pipe objects. In this way, a Portal can act as a node point in a network of transits.

Often, you will want to be able to make objects that operate in a more sophisticated manner than the standard objects from the Object Palette. You can use a portal as a container in which you combine the standard objects to produce an object at the Portal level, which can represent a complex set of processes, or behaviours. These can become quite sophisticated, and if you want to, you can use subsystems and portals to create ‘Planimate® Modules’, which are customised, tailored objects capable of being saved to file, and loaded and used in many different models, and which provide a standard set of inputs, outputs and behaviours for which you can create customised editing and configuration panels.

Making the top level screen a sub-system

The top level (Main) screen of a model can be considered to be a subsystem that has no Portal Entries or Exits.

It can contain attributes and tables. And it can be placed into a Portal and thus made into a sub-system. The Put Into Sub-system option in the Object View Background Menu enables this to be done. Doing so creates a new top level Main screen which contains a portal. When a Main Screen is made into a Portal, its Attributes and Tables are all brought down inside the portal as part of the subsystem.

Portal States

Idle

Indicates there are no items in the Portal.

Busy

The portal has detected some items within itself.

Customised Portal States

You can customise a Portal’s states to provide a more extensive range of icons to display during a model run.

With this menu option you can customise a Portal’s states.

For each state you can select a state name, a value and an icon.

Customised states are changed by operations in routine code.

Navigating between Sub-systems

You can navigate between subsystems in a number of ways.

To enter a Sub-System through the Portal:

Double click in the Portal Icon

or...

Select Enter Subsystem from the Portal's Object Edit Menu.

To Leave a Sub-System and return to the screen containing the Portal:

Double click in either the or the

or...

Select Up to Portal from the Object Edit Menu of a Portal Entry or Portal Exit

or...

Select Up to Portal from the Object View Background Menu

Using the Model Hierarchy browser window

Click on the Subsystem Name in the Model Hierarchy window on the left of your screen.

Scroll if necessary, and use the plus/minus symbols to expand and collapse branches in the hierarchy like you do when browsing folders.

You can also set Click Actions on Paint Objects to provide screen navigation capability.

Use of the <Ctrl+B> key combination moves you back and forth between the last two screens you visited.

Portal Data

A Portal can contain data private to itself, which is only available to items, objects and code within it. The Data can be in the form of:

Data

Description

Attributes

Single Value Attributes located at a Portal are called Portal Attributes. You can create as many Portal Attributes as you wish.

Tables

Tables with variable rows and columns can be located at a Portal. You can create as many Portal Tables as you wish.

Panels

You can add View Panels to a portal. View Panels are screens where you place information only. Neither items nor objects are shown in a View Panel. They only show views of data like attributes, tables, graphs, and paint objects (buttons, images etc). Panels are owned by Portals, and are copied with the portal as part of its hierarchy when you copy and paste a portal.

Labels

You can add Label Lists to a Portal. These Label Lists are “Scoped” which means they are visible only to items and code within the portal’s scope (i.e. its branch of the model hierarchy). As with attributes and tables, scoped label lists with the same name as lists higher in the hierarchy will "obscure" those higher up.

Classes

You can add Scoped Item Classes to a Portal. These Classes can only be used within the portal’s scope. An item of a certain class can enter into the portal and be transformed into one of these private classes, and then revert back to the original class upon leaving the portal.

Class Mappings

Class mapping specifies how external classes are mapped to internal classes in the module as items enter (and also the reverse when items leave the module). This data option provides an editor for you to assign mappings between higher classes and the private, scoped classes.

Scoped Item Classes and Class Mapping Scoped Item Classes

Item classes can be scoped to a portal (currently in item class edit menu). This means that their flows can only exist in the scope of that portal. This keeps the portal self contained. Copying the portal will create a separate item class for the copy and the 2 will be isolated from each other. Scoped item classes will have access to scoped label lists (which global item classes do not) encouriging the modularity further

Class Mapping

The idea here is to provide a mechanism where a module (a portal) can be pasted into a model, carrying with it not just attributes and tables but also label lists and item classes (with their attributes) which it uses internally. The goal is that the module can be pasted (singly or multiply) into another model without any of its internal code interfering with existing model code, or with multiple instances of itself. Scoped item classes are an important part of this as even if common global class names were somehow agreed upon, different modules would need different attributes and use the same named attribute differently. By scoping, this usage is kept local and isolated.

To work within an existing model, a mechanism is required to "map" the existing, outside or "external" classes in a model to the private, local or "internal" classes in the module being pasted in. This is provided by the "Class Mapper". The class mapper specifies how external classes are mapped to internal classes in the module as items enter (and also the reverse when items leave the module).

Getting Items into Portals

Items can enter a portal in the following ways:

  1. via flows 

  2. via a spatial link/track 

  3. messaging to the portal 

  4. via a broadcast 

  5. via a wormhole 

  6. via a throw exit (Place Item into Object, mode available in Application Panels). 

Methods 1 and 2 and 3 are currently mapped by the class mapper. As the item enters portal it gets "translated" to an internal item for the portal. As it leaves, it gets translated back to the external item. To enable mapping for a message item you need to manually set up the mapping as the platform doesn't prompt to do it automatically as when you are flow editing. Method 4 should already occur due to the existing broadcast mechanism for class translation (see below though). 5 and 6 wont be supported for modules as they are not modular by nature.

Translation of Items and Attributes

The translation process involes copying matching item attributes (see below) as occurs in "tupling" with tables and between different item classes. This applies to both item attributes and item table references. Matching names get mapped unless the INTERNAL item class has the "private" option set for the attribute/table reference.

An external item survives while an internal item is inside a portal where a mapping has occurred. It gets put "aside" until the item leaves the portal whereupon its attributes are updated. This whole process works both in lookahead (looking into the module/portal to determine if it has capacity, the module looking "out" to see if there is capacity for an item that wants to leave) and "lookthrough" (looking right through a module with no capacity to see if what is on the other side has capacity for an item to move. It should also work recursively (modules inside modules).

Private item attribute option

If a subsystem contains a class with private item attributes, these attributes are not set or returned to the "external' item class which is being mapping into or out of the subsystem. All other item attributes with matching names are copied when translating external to internal and coming out again.

Reporting Mappings

A "Report" button in the class mapping overview will display a summary of the attributes/table references that the internal class is allowing to be tupled and indicating which ones are actually matched by the external class.

Current Limitations

Carried items to be transferred between the external and internal items on the way in/out.

The ability for a module to produce an item without one entering and the class mapping to properly occur as the item leaves the module.

Table references to be treated similar to item attributes as described above

If a class is mapped, the module is not able to assign routes/link targets for the external item. A mechanism to enable this needs to be developed (though this raises the issue - how does the module know about the external network)

A mechanism to "insulate" modules from scoped broadcasts is intended. This will prevent a module having its internals activated by modeller broadcasts in the model it is pasted into unless those broadcasts are specifically targetted at it.

Class Mappings and Modules

When a module (portal with "module" option on) which has internal classes is included in a flow, PL will check if there is a mapping for the current class being edited. If there isn't it will offer to allow an internal class to be selected. If the module only has one class, then PL will create a mapping automatically without prompting the user. This simplifies the use of modules with a single scoped class within them.

Portal Options

Portals are highly-configurable objects. They can play a range of roles in your model. In most roles, they will act as self-contained, fully-encapsulated objects at various scales, which represent a location, or perhaps a process within a location. This is particularly true when your Portals act as node points in a network of links. In any of these roles, there will be some options that will support that role.

Adding Links between Portals

The Add option on a Portal Object menu enables you to link this Portal to other Portals using Spatial Links, Tracks or Pipe objects. In this way, a Portal can act as a node point in a network of transits. Items emerging from within portals can be directed on to a Spatial Link or Track object and undergo a transit delay before leaving the other end of the link and entering into the portal subsystem at that end.

More detail on Spatial Link.

More detail on Tracks.

Pipes operate to move attribute values from place to place, and Portals provide the end points for animation of these transfers.

More detail on Pipe.

Customisation of Portal States

With this menu option you can customise a Portal’s states. For each state you can select a state name, a value and an icon. Customised states are changed by operations in routine code.

More detail on Customising Portal States.

Subsystem Related Actions

This menu flyout provides you with the following actions:

Action

Description

Open in Window

You can have the subsystem panel of a Portal pop up in its own window.

Popup Properties

You can set the properties of a popped up subsystem panel. This action is also available for this portal’s subsystem when it is displayed, under Panel, in the menu bar.

Shared Routines

You can view a list of the shared Routines resident at this Portal’s level. This action is also available for this portal’s subsystem when it is displayed, under Panel, in the menu bar.

Remove all Subcontents from Dataset

You can elect to remove all data in this subsystem, and subsystem in this branch of the hierarchy from all Dataset configurations. This applies recursively starting at the portal selected and is useful when a hierarchy of objects contains data that should no longer be saved in the dataset but the objects need to be retained for backwards compatability. Use this action with care, as each list, table, attribute etc has to be manually added back to a dataset.

Portal as Module

A new feature in Planimate® 5 enables you to set an option on a Portal for it to Act as a Module. This will make your Portal behave more like an specially tailored object, and have its own configuration panels and parameters. You are free to design and construct the internal behaviours of your Module Portal in a fully encapsulated manner, using Scoped Attributes, Tables, Label Lists, Item Classes and Subsystem Panels. This Module can also be saved as a self contained object that can be loaded and used in other models.

Saving Modules for Re-use

Modules can also be saved using the File Menu option “Save Model and Create Module (PMB file)”. As a self contained object that can be loaded and used in other models. The intention is that subsystem based "modules" will provide the functionality of recently-retired standard Planimate® 4 objects, with the advantage that the specific logic of these objects can be customised way beyond the older objects’ hard coded capabilities. Saving a Module requires that the model which is the module is saved as a Planimate® Module Bundle (PMB) file and only has one top level portal. No other objects are carried through the merge process.

The File menu option "Add Module To Current Model" enables simple merging of models. Selecting this option saves the current model, enables a "PMB" saved model to be selected, loads that model and merge with original model, leaves user with the "module" ready to be pasted, (the original model is not resaved after the merge). Loading a module will now merge in any resources in its DB file into the current model's DB file. Any existing resources with the same name and type are replaced.

Modules have Configuration Panels

Turning on the Portal option "Act As Module" will cause the Portal to search for subsystems containing the "Subsystem is Module Configuration Screen" flag. These substems are presented in the Portal's context menu and will popup when selected. It is recommended to have the popup options "Stay in Front of Main Window" and "Ensure Visable on Display" are turned on for the Configuration Screen subsystems.

Incorporating Modules in new Models

When a module (portal with "module" option on) which has internal classes is included in a flow, Planimate® will check if there is a mapping for the current class being edited. If there isn't it will offer to allow an internal class to be selected. If the module only has one class, then Planimate® will create a mapping automatically without prompting the user. This simplifies the use of modules with a single scoped class within them.

Other Module Notes

Modules looking for module configuration screens will not search within other modules nested within the module.

The INI file option "ModuleFolder" defines the folder Planimate will first look in when loading a module.

ModuleFolder="Modules" (will look in {exe path}\Modules)

Refer to Editing Object Properties for information about editing properties common to all objects.