FRAM Model Visualiser Instructions

Instructions for use of the FRAM Model Visualiser (FMV)

Created from the original FMV instructions © Erik Hollnagel & Rees Hill (2014-2020)

Installation

The FMV is used to model complex socio-technical systems using the Functional Resonance Analysis Method - FRAM. The software is a Web Assembly application that runs in a users web browser and is available at: fmv.zerprize.co.nz. Testing has been completed in Edge and Chrome, but proper functionality is expected in any modern browser. The application can be installed to run in its own window and offline by following your browser's instructions for installing a Progressive Web Application, or PWA.

When you first open the application as an anonymous user, a basic user interface is presented with the functionality suitable for learning and building FRAM models, or for simply viewing and presenting models created by others. In the top right of the menu bar, a login option allows for free user registration and unlocks additional features, all of which are explained in this manual. If you have used the application previously and are trying to update to a later version, you may have to perform a Hard Reset, in Edge this is Ctrl+Shift+R but check with your specific browser.

The program is free software provided under the following license. The source code, this manual and other resources are available on GitHub: github.com/FunctionalResonance/FMV_Community_Edition

FMV - FRAM Model Visualiser
Copyright © 2021 ZERPRIZE LIMITED

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as published
by the Free Software Foundation, either version 3 of the License, or
any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License
along with this program.  If not, see <https://www.gnu.org/licenses/>.

Using the FMV

Project control

The menu bar along the top has the following items, explained from left to right:

• Open (upload): Opens a file browser for selecting a project data file saved previously or supplied, and loads it into the Visualiser window. Any .xfmv file saved from any version of FMV is compatible. To create a new file from a blank screen, if a previous file has already been loaded, simply refresh the browser window (In Edge this is Ctrl+R or in many browsers F5). You can also load a file by 'drag and drop', for example, dragging it from a file browser or email and dropping it onto the empty Visualiser window.
• Save (download): Saves the current project by downloading a data file to the default downloads folder. This behaviour is the same as a website and is the most universal to work in any browser on any operating system, as the application does not have direct access to a users file structure. The user is then responsible for naming the files and organising them in their preferred location.
• Save image: Saves the visualisation of the current project as an SVG file (Scalable Vector Graphic). The file is saved in the downloads folder with the same name as the project, but a .svg file extension. The image is exactly what currently appears in the Visualiser window, for example it will include highlighting if a Function is selected. The SVG format can be viewed in a web browser, inserted into documents and edited in many graphics applications. The initial size will match the current zoom level of the Visualiser window but it can be scaled without any loss of resolution, and as such, is a suitable or preferred format for both electronic and print publication. The examples in this manual are generated and displayed this way.
• Zoom Out: Zooms out, making the model smaller in the Visualiser window.
• Zoom to fill: Adjusts the zoom level so that the current model fits within the visible window and can be view in its entirety without scrolling.
• Zoom In: Zooms in, making the model larger in the Visualiser window.
  ℹ️ In addition to the zoom level of the Visualiser window, it is also possible to adjust the overall zoom level of the browser window. This can be accessed from the browser menu, or on most systems by holding the Ctrl key and using the mouse scroll wheel. This will change the view of the entire application including the menu buttons and controls. A combination of these options should be used to setup the preferred environment. F11 enters full screen mode to use more of the available screen.
• Undo: Will undo changes made to a model, such as changing text, moving Functions or changing zoom levels. Will undo one change at a time stepping backwards.
• Redo: If Undo has been used, this will reverse the undo steps one at a time, restoring the changes.
• Show Aspect labels: Aspect labels are shown on the potential couplings, the connecting lines in the Visualiser window. This will turn them off so they are no longer displayed, and when used again will turn them back on, cycling between the two states. This can be used to remove clutter when focusing on the Functions and the potential couplings.
• Model rendering: Cycles through the available rendering options for how the Function hexagons are drawn in the Visualiser window. The default is 'Traditional', representing how Functions were portrayed in the original FRAM publications. The next two options have been available in previous versions and are referred to as 'Modern' and 'Floating', inspired by custom graphics from research publications. Three additional renders have been added to showcase the flexibility of the render options setup file now available in the public source code. 'Autonomy' was inspired by the Assuring Autonomy International Programme at the University of York: www.york.ac.uk/assuring-autonomy/training/films/.
• Table view: Provides access to the data generated by the model creation in a table format. Different sections of data can be turned on and off, and then saved as CSV files for use in other applications or for further analysis. The control cycles through three views; a split-screen between the table view and the Visualiser window, full-screen table view, and back to the full-screen Visualiser window. Functions highlighted in the Visualiser window will also be highlighted in the table. The table columns can be sorted and some of them can be filtered. The split-screen can be extended across two screens to appear as both full-screen table and full-screen Visualiser window at the same time. To work with FRAM models more extensively using spreadsheets, refer to myFRAM from the Industrial Systems Engineering group at Sapienza University of Rome: sites.google.com/uniroma1.it/resilienceperspectives/myfram.
• Reload: If the browser has been refreshed, or closed and reopened, and work has been lost, this will attempt to reload the last model that was being worked on. Even when the computer is shut down and restarted, this should reload the most current work.
• Login/Logout: When the application is first opened as an anonymous user, this is displayed as a login icon, used to log in to the application to unlock the full range of functionality. When logged in, it is displayed as a logout icon, used to log off and return to the basic view.
• Info: Displays an information screen with basic instructions and provides access to additional content including this manual, the license and the source code.

Function control

The side bar has the following items used for interacting with individual Functions, explained from top to bottom:

• New Function: This will cause a new empty hexagon to appear in the Visualiser window, representing a new Function. Focus then moves to the text box to the right of the control where the name of the Function can be entered. The name is saved when you move away from the text box (Tab or click away) and is then displayed on the Function in the Visualiser window. If you do not enter a name and click away, a default index number will be used, but this can be edited. To delete a function, delete all Aspect text (below) and then delete the Name text, and click away.
  ℹ️ The name should be short but distinct. Function names should begin with a verb in the infinitive form (but without the ‘to’), because a function describes an activity.
• Function text: This two-sided control will decrease or increase the size of the text displaying the Function Name in the Visualiser window. After pressing one of the buttons you can revert to the default text size by pressing the Esc key.
• Output, Input, Precondition, Resource, Control, Time
  The next six controls are used to describe the Aspects of the selected Function. When clicked, a text box will appear to the right allowing you to enter the name to describe the new Aspect. As with all text boxes in the app, the name is saved when you move away from the text box (Tab or click away).
  ⚠️ Caution: If you press 'Enter' this will just create a new line in the Aspect name. The 'new line' will become part of the Aspect name string and may cause an unexpected mismatch with another Aspect of the same name.
  It is also possible to use keyboard shortcuts. After using Tab to save an Aspect name, continue to use Tab and Shift+Tab to navigate the controls, or use the +,O,I,P,R,C,T keys to jump to a control. When a control is highlighted, pressing Space or Enter will activate it the same as clicking with the mouse.
  As soon as you have completed the entry of the Aspect name, it will be marked correspondingly in the Visualiser window. If the aspect name already exists for an Aspect of a different Function, a blue connector will be drawn. If the Aspect name does not yet exist for another Function, the entry will be shaded red and the Aspect will be marked by a red ring in the Visualiser window (this is referred to as an orphan).
  If you click on the new Aspect button for an Aspect for the second time, a new text box will be added for that Aspect. In this way it is possible to add as many new Aspects as required. The names given to the Aspects can be edited/corrected directly in the name text box of the Aspects. Any changes will be shown in the Visualiser window, which thus represents the current status of the model.
  ℹ️ Remember that Aspects describe states (noun phrases) rather than actions.
• Aspect text: This two-sided control will decrease or increase the size of the text displaying the Aspect labels on the couplings in the Visualiser window. After pressing one of the buttons you can revert to the default text size by pressing the Esc key.
• Function Colour: It is possible to choose the colour of a hexagon’s edge. This may be useful to mark functions that somehow differ, for instance, because they are carried out by different parts of an organisation. The default colour is white, meaning no colouring of the edge. The control opens a palette to select from a range of pre-defined colours. The top row of colours represent the standard base colours available in previous versions of FMV. The top left button resets a Function to no colour. The bar at the top that displays the selected colour can be clicked to open a further control that allows for the creation of custom colours. To apply the selected colour and close the palette, click the X button, press the Enter key, or click away from the control. To cancel the selection and return to the previous selection, press the Esc key.

Visualiser window

The main window in the application is used to visualise the FRAM model rendered as a graphical representation, either the model that is being built, or the project that has been opened and uploaded into the application. The visualisation shows hexagons, representing the Functions, as well as lines connecting the hexagons, or couplings. The six points of the Function hexagon represent the six Aspects, and coupling lines join an Aspect from one Function, to an Aspect from another Function if they share the same name, with the label of the shared name appearing in the centre of the coupling. These couplings describe how an Output from one (upstream) function may serve as an Input / Precondition / Resource / Time / Control of one or more (downstream) functions.

• For some functions the Aspects may be marked with a thick red circle. This means that the Aspects are 'orphans', or in other words that the model is incomplete. The designation of an Aspect as an orphan aspect is made automatically by the FMV according to the FRAM syntax.
  ⚠️ Caution: An Aspect is marked as an orphan if the Aspect name is unique, i.e., does not match the name of any other Aspect. This will happen when a name is entered for the first time, since it obviously will be unique, but also if the name has been misspelled. In addition to actual misspellings this may happen because the name includes a non-printing character, such as a carriage return, a tab, or a space, which can occur inadvertently with copy and paste. Conversely, two Aspects may become connected if they contain the same incorrect string. During model creation always check for both expected and unexpected couplings.
  
• Background Functions are shown with a grey interior, or in some render options simply as the Function name inside an oblong. A function is recognised as a background function if it only has one or more Inputs (also called an Entry Function) or one or more Outputs (also called a drain or Exit Function). The FMV will automatically detect whether a function is a Background Function.
• Foreground Functions are shown with a white interior. A Background Function becomes a Foreground Function if one or more of the other four Aspects (P, R, C, T) are defined. The FMV will automatically detect whether a function is a foreground function. A Foreground Function is expected to have at least one Input.

Prepare Work example - A FRAM model with eight grey Background Functions and three white Foreground Functions. One of the Foreground Functions is selected as shown by the blue highlight.

• To interact with a Function, select it by clicking on it in the Visualiser window where it will then be shown with a blue highlight. Unselect by clicking the background behind the Functions, or you can select a different Function. You can also cycle through the Functions using the left and right arrow keys.
• When a Function is selected, the Function control side bar will show the data for the selected Function, as described previously. All coupling lines associated with the selected Function will also be coloured blue. These represent the Function's Aspects that are potentially coupled with the Aspects of other Functions.
• A Function that is selected can be moved around in the Visualiser window by clicking and dragging with the mouse; the couplings to other Functions will automatically follow the movement. If the image of the model extends beyond the visible window, then scroll bars will appear so you can scroll to any part of the model.
• A coupling can be selected by clicking on the aspect label that appears along it. When a coupling is selected the line is highlighted blue. When a coupling is selected, the label can be dragged along the line to any position. This may be helpful to avoid overlapping labels. When Functions are moved and coupling lines are redrawn, the label will remain attached to the line in the same position relative to the ends. The default position is in the transition point of the curve, usually about halfway along. To return a label to this position, there is a slight snap when moving with the mouse.

ℹ️ Because the FMI application is presented within a web browser, additional functionality is available from the menu and commands of the web browser, such as the Zoom features mentioned previously, F11 full screen mode, Translate, and the Find on page search features.

FMI - FRAM Model Interpreter

The FRAM Model Interpreter (FMI) is a software tool that can be used to interpret a FRAM model and through that determine how the described activity or task may develop. The FMI provides a realisation or interpretation of a given model in the sense that it examines the consequences of the couplings specified by the Aspects of the model’s Functions and thereby shows how an event can develop. The FMI can therefore be used to determine how the potential couplings defined in the model will be realised as actual couplings for specified conditions – an instantiation.

The FMI is also offered as a stand-alone application with its own descriptive manual, available on SafetySynthesis: safetysynthesis.com and referenced on the Functional Resonance website: functionalresonance.com. This manual describes how to use the FMI basic version as an integrated tool within the FMV, but the above reference should be used for a more detailed description of the method and the terminology used.

FMI control

The FMI controls are located at the bottom of the Function control side bar and are explained as follows:

• Reset FMI: Reset the interpretation and return the model to its original state. Use this button at any stage to clear the results and start over.
• Advance one cycle: Start or progress the interpretation one step at a time. The first step Initialises the model and then, if an error is not produced, will highlight the Entry, Exit and Background Functions as follows: (this is Cycle 0)
  • Entry Functions are highlighted green
  • Exit Functions are highlighted red
  • (Other) Background Functions are highlighted blue-grey
  • Subsequent clicks will continue the interpretation one step at a time. Each step is called a Cycle, where only the Functions that have been activated by their Inputs will consider producing an Output dependant on their other Aspects. Activated Functions on each Cycle that produce Outputs are then highlighted green.
• Continue Interpretation: Start and 'play' the entire interpretation from start to finish, after clicking Reset. If the model has already progressed, this will continue the model interpretation and progress again through all Cycles until either all Exit functions have been activated, or no functions are activated in a Cycle.
• Show activated: Highlight green all Functions that were activated during the interpretation. Usually checked at the end of an interpretation but can also be checked after any Cycle.
• Show not activated: Highlight red all functions that were NOT activated during the interpretation. This is the opposite of Show activated above, and together the two controls can be used to help troubleshoot a model to find where or why a Function is not being activated or a coupling is not being completed.
• Show FMI LOG: Display the 'FMI LOG' window containing text results of the interpretation. The window can be opened at any time and will display results up to the current Cycle.
  If the model does NOT pass the initialisation on the first step, then the FMI LOG will display automatically to show warnings explaining what needs to be completed before the interpretation can begin, such as orphans, missing Inputs and missing Outputs. For example:
  WARNING: <Leave harbour> does not have any Inputs
WARNING: <Finish loading> has an orphan
WARNING: <Trim vessel> does not have any Outputs
  If the model passes the first initialisation step (Cycle 0), then interpretation results are displayed according to the following structure:
  • Title and time stamp.
  • Identification of Entry and Exit functions. For example:
    Entry function <Finish loading>
Exit function <Commence voyage>
    An Entry Function is a Background Function from which the Output is the Input to a Foreground Function.
    An Exit Function is a Background Function where the Input comes from an upstream Foreground Function.
  • Interpretation Profile – a summary of the Interpretation Profile settings for each Foreground Function. For example:
    Function <Man harbour stations> Input: All Precondition: All Resource: All Control: All Time: All
  • Confirmation of the initialisation success and a listing of the Background Functions and Entry functions that have been activated ready for the first interpretation Cycle.
  • Cycle results. Each Cycle begins with a heading, such as:
    BEGIN CYCLE 1
    Then there is a list of each Function that was activated during that Cycle, meaning that the function is ready, and all the aspect conditions have been fulfilled. When a Function is activated its Outputs are then activated and available to downstream Functions on the next Cycle. If no functions activate then this message will be displayed:
    No functions were activated during this cycle.
• Delay: The final control is a slider for setting a delay timer or pause to control the speed that the interpretation is displayed when using the Continue Interpretation 'play' control. A longer time will slow down the visualisation between Cycles. A setting of 0 will run the interpretation as fast as the local computer can calculate and render the results in the Visualisation window.
  ℹ️ It should be noted that the time of the delay does not relate to 'model time' or time that may be represented by the model or its instantiation. It is only and simply to aid the visualisation of the FMI interpretation.

Interpretation Profile

It is expected that most FRAM models do not follow a simple linear progression because of the complexity of socio technical systems that they are attempting to model. It is not unusual for larger models to have several diverging and converging branches, feedback loops, and multiple entry and exit points. This can result in Functions that mutually depend on or block (interlock) each other, which in practice may led to conditions where functions wait forever for an aspect to become fulfilled. The FMI can identify these cases by interpreting the model step-by-step while keeping track of the status of all the aspects and activation conditions. A further purpose of the FMI is to investigate the consequences of variability of functions. In the basic FMI this is done by means of an Interpretation Profile which specifies the conditions under which a function may become activated, rather than by considering the variability of outputs directly.

When the FMI is first used on a model, the default assumption is that a Function's method evaluates the aspects as follows:

IF ALL (defined) Inputs are present AND 
IF ALL (defined) Preconditions are present AND 
IF ALL (defined) Resources are present AND 
IF ALL (defined) Times are present AND 
IF ALL (defined) Controls are present, THEN the function is activated
OTHERWISE wait

This is represented by an Interpretation Profile for each Function as follows:
[Input: ALL, Precondition: ALL, Resource: ALL, Time: ALL, Control: ALL]

For a particular model structure or to specify conditions for an instantiation, the Interpretation Profile can be adjusted for Foreground Functions individually. The options for each parameter are:

• ALL: meaning that all aspects of the specified type must be present before the function is activated.
• ANY: meaning that at least one of the aspects of the specified type must be present before the function is activated.
• NONE: meaning that none of the aspects of the specified type will be taken into account before the function is activated.
• ℹ️ There is no difference between All and Any if there is only one of that Aspect type.

In the following example, the Function <To leave harbour> has one Input, three Preconditions, one Control, and one Resource. In the nominal condition, the function will be activated if all defined aspects are present.

Consider if the Interpretation Profile was changed to this setting:
[Input: ALL, Precondition: ANY, Resource: ALL, Time: ALL, Control: ALL]
In this case the Function could be activated when just one of the Preconditions were present. If that, for instance, was [Moorings have been dropped] then the vessel could potentially leave the harbour without being trimmed and with the bow doors open.

Interpretation Profile control

To change the Interpretation Profile for a Function, first select the Function in the Visualiser window. The Name and Aspects will be displayed in the Function control side bar.

• Although not initially visible, there is a button below each I P R C T control used to add new Aspects. The outline of the button will appear when you hover over with the mouse pointer.
• Click on the button to cycle through the possible values. A universal maths symbol is displayed to represent the conditions described previously, where:
  • ∀ = All
  • ∃ = Any
  • ∅ = None
• For the example above where Precondition was changed to Any (and Input, Resource and Control were set to All), the resulting Interpretation Profile would be set in the Function control side bar as follows:
  
• ℹ️ Note that it is not possible to set the profile for an Input to None because the interpretation rules state that a Foreground Function must have at least one Input.
• It is possible to cycle the value back to a blank. This is the default and is interpreted exactly the same as All (∀).

The conditions explained so far are for defined Aspects that are coupled with Outputs from upstream Functions, that is Input, Precondition, Resource, Control and Time. These settings are not relevant to Background Functions, which only have Outputs and are defined by FRAM as having no variability. Their Outputs are considered constant and available during every interpretation Cycle.

A special case are Entry Functions. As with other Background Functions, their Outputs are present on Cycle 0 when the interpretation begins, which means that downstream Functions can become active on Cycle 1, provided any other specific conditions are fulfilled. The difference is that an Output from an Entry Function couples with a downstream Input and (because Foreground Functions must have at least one Input to activate) are key to the propagation of the interpretation. By default, the Output is only activated on Cycle 0 to prevent that the Entry Function continues to start the model.

The default behaviour of Entry Functions can be overridden to investigate specific situations, for example, to test the behaviour of a feedback loop in a model that requires the Entry Function to activate on a repetitive cycle. This is achieved with the following control:

• First use the Reset FMI and Advance one cycle FMI controls to identify the Entry, Exit and other Background Functions.
• Select the Entry Function by clicking on it in the Visualiser window.
• There is a text box below the O control used to add new Outputs. Click on it to enter a value (it will only become editable if an Entry Function is selected).
• A number can be entered as a valid input and interpreted as follows:
  • 0 = Initial only: This is the same as the default behaviour if left blank. The Entry Function will only activate on Cycle 0.
  • Integer N = Every N^th Cycle: The Entry Function will activate on Cycle 0 and then every N^th Cycle. For example, if a 1 is entered the Entry Function will activate every Cycle. If a 3 is entered then the Entry Function will activate on Cycle 0, 3, 6, 9 and so on for every multiple of 3.
    ⚠️ Caution: This setting expects a whole number integer. Decimals greater than 1 will be accepted but may cause unexpected results (the Function will only activate if the multiple results in exactly a whole number).
  • 0<p<1 = Random Probability p(): If a decimal between 0 and 1 is entered then this will be treated like a probability and the Function will activate if a pseudo-random number generated on each Cycle is less than or equal to the probability. For example, if 0.5 is entered then the Function will activate 50% of the time, but exactly on which Cycle is not pre-determined. The random pattern will be different every time the FMI is reset.
• The Entry Function in the example below shows a setting that will cause it to activate on Cycle 0 and then every 5^th Cycle:
  

The final FMI example below shows the full model used in the FMI examples above after Cycle 0, when the Entry, Exit and other Background Functions have been identified and highlighted:

Leave Harbour example - The Entry Function <Finish loading> is highlighted green. The Exit Function <Start sea passage> is highlighted red. The Background Function <Issue company rules> is highlighted blue-grey.