From Planimate Knowledge Base
Revision as of 16:29, 3 April 2009 by Tony.Griffith (talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

Portal: Container for a Subsystem

Portal Palette Icon.jpg

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.

Portal Hierachy.jpg

Each of the levels here is a subsystem.

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

Every Sub-system always has at least one Portal Entry and Portal Exit.
(Sometimes they are hidden)

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 however 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

Portal State Icon Idle.jpg  Idle     Indicates there are no items in the Portal.

Portal State Icon Busy.jpg Busy       The portal has detected some items within itself.

Important Note:

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

This is very useful! Once you start creating complex or sophisticated models you will want to do this a lot of the time. Be sure to refer below for mode information about Customizing Portal States.

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


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:

Portal Entry Icon.jpg  Portal Entry

or the

Portal Exit Icon.jpg Portal Exit


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


  • Select "Up to Portal" from the Object View Background Menu

Using the Model Hierarchy browser window:

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

Portal Hierachy.jpg

Other Ways and Means:

  • You can 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. This is also known as 'scoped' data, because it is only available to items, objects and code within the portal. The Portal can be considered the 'owner' of this data and it can be in the form of:


Single-value variables located at a Portal are called Portal Attributes.

You can create as many Portal Attributes as you wish.


Tables with variable rows and columns can be located at a Portal.

You can create as many Portal Tables as you wish.


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.


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.


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

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.

The Class Mappings Portal Data option provides an editor for you to assign mappings between higher classes and the private, scoped classes.

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).

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.

For full details refer to this page: Item Class Mappings

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.

Refer to the Portal Options Choices page for full details.

Adding Links between Portals

The Add option on a Portal Object menu enables you to link this Portal to other Portals using objects called 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.

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

More detail on Spatial Link.

More detail on Tracks.

More detail on Pipe.

Customise States

The Customise States Portal Data menu option enables you to replace the standard Portal States (Idle, Busy) with a set of states that you define yourself.

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

Customised states are changed by operations in routine code.

For full details refer to this page: Customize Portal States

Subsystem (Related Actions)

This option in the Portal Edit menu enables you to make changes to aspects of the subsystem panel that sits below this portal.

For full details refer to this page: Subsystem Related Actions

Portal as Module

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.

For full details refer to this page: Modules

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

== Portal Articles ==

Portal Object Frequently Asked Questions