Developing Models

Developing Models

The Campus Energy Modeling Simulink block library is located in the directory Library/simulink/. The block library itself is stored in the single file CampusEnergyModeling.mdl. In addition to this file, the libraries rely on two types of supporting functions:

• Block mask callback functions *_cb.m, located in the callback/ subdirectory, and
• S-functions *_sfun.m for the implementation of custom Simulink blocks, located in the sfun/ subdirectory.

The graphics/ subdirectory includes images for use with the Simulink blocks.

Simulink Blocks

There are five sections to the block library:

• Electrical
• PV
• Buildings
• Weather
• Data Acquisition

These sections appear as navigation entries in the Simulink library browser.

Creating New Blocks

To create a new Simulink block model for inclusion in the library, first develop and test the masked block in a separate Simulink model. Please follow the guidelines presented below for the block mask, callback functions, and S-functions. For assistance, see Block Creation Basics in the Simulink documentation.

Once the block is ready, add it to the library:

1. Open the Campus Energy Modeling block library in Simulink.
2. Unlock the library via Diagram > Unlock Library.
3. Copy the block into the relevant subsection of the library.
4. For consistency, please resize/reformat the block to match the other blocks in the library.
5. Document your function using the guidelines and template provided in Writing Documentation.
6. Save the library.
7. Place any other required files (callback functions, S-functions) in the appropriate directory.
8. Commit your changes (if you haven't already).
9. Consider also creating an automated test script for your new Simulink block.

General Guidelines

The Simulink block library is the central software feature of the Campus Energy Modeling project. The individual blocks are the project's best means of achieving the goal of providing simple, seamless, and user-friendly interfaces between Simulink and other modeling tools. Therefore, please follow these modeling guidelines:

• Use a block mask to encapsulate the required inputs, outputs, and parameters.
• Use intelligible names for inputs, outputs, and parameters.
• Emphasize ease of use:
  • Minimize required user inputs not directly relevant to the energy model, such as communication settings and paths to executables. The block should intelligently determine most settings related to any underlying communication. This promotes the appearance of a seamless application interface.
  • If applicable, use callbacks and tabs to improve block mask navigation.
  • Automate initialization whenever possible.
• Emulate the intuitive nature of native Simulink blocks.

Existing Simulink blocks provide excellent examples for both code style and documentation.

Block Masks

All blocks for inclusion in the library must be encapsultated in a block mask (rather than included as unmasked subystems). Use of a mask provides a single interface to the underlying energy model, simplifying model implementation. All parameters relevant to the model should be set via the mask dialog; do not force users to navigate under the mask to change settings.

Block Callbacks

In Simulink, callback functions allow a block designer to create dynamic mask dialogs or even dynamic, self-modifying subsystems. Callbacks also provide a means of mask initialization. Please use callbacks as needed to improve the user-friendliness of your block.

When writing anything more complicated than single-command callbacks, we organize all callbacks in a single file as suggested in Organizing Mask Callbacks. Name this file blockName_cb.m, in which blockName is the name of the corresponding Simulink block, and place it in Library/simulink/callback/. Within this file, create a function named blockName_cb and use this primary function as a switchyard to route all callbacks to relevant subfunctions. The basic syntax is:

function varargout = blockName_cb(block, callback, varargin)
    %% Setup
    % Default output = none
    varargout = {};

    %% Callbacks
    % Select and execute desired callback
    switch callback
        % Place routing to callbacks here... example below
	
        % Initialization
        case 'init'
            varargout = PVSmoothing_cb_init(block, varargin{:});
        
        otherwise
            warning([block ':unimplementedCallback'], ...
                ['Callback ''' callback ''' not implemented.']);
        
    end
end

%% Subfunctions
% Initialization
function out = PVSmoothing_cb_init(block, ...) % Replace ... with other required arguments
	% Place callback code here
end

See Organizing Mask Callbacks for details and existing callback functions for examples. Please document your callback function per the template.

S-Functions

If your block uses an S-function, please name the file which contains the S-function blockName_sfun.m, in which blockName is the name of the corresponding Simulink block. Place the file in Library/simulink/sfun/. Please document your S-function per the template.

Modifying Existing Blocks

If you modify an existing block, please update the block documentation as needed. If applicable, please also update any tests and demos which use the block.

Documentation

Please document your Simulink block as described in Writing Documentation. Also include function documentation for any callback functions and S-functions associated with the block.

Once your block is included with an official release of the Campus Energy Modeling project, you should also update the wiki documentation:

• For new Simulink blocks, add an entry under the appropriate section of Library.
• For modified Simulink blocks, update the block entry in Library as needed.