Skip to content

Creating Demos

Jump to bottom
Stephen Frank edited this page Dec 19, 2013 · 5 revisions

Creating Demos

Demos are intended as a starting point for new users of the Campus Energy Modeling library. Therefore, all demos should have a standard structure, should be easy to use, and should lend themselves to modification.

Structure

All demos should adhere to the structure outlined below, in which mydemo serves as an example demo name. (Substitute the name of your demo wherever you see mydemo.)

  • Place all files for the demo apart from test data within a single, uniquely named folder (mydemo) under the Demo directory.
  • Include a Simulink model mydemo.mdl.
  • Include a README file README.txt.
  • If the demo requires initialization, include an initialization script mydemo_init.m.
  • If the demo requires test data, include it in plain text format in the /Test/data folder of the Campus Energy Modeling library rather than in the mydemo folder. See Testing for details.
  • Place any additional files required by the demo (for instance, EnergyPlus models) in the mydemo folder or a dedicated subfolder.

Guidelines

Please conform to the following recommendations for the demo model, initialization script, and documentation.

Model Style

The demo should be simple, clean, elegant, organized, and easy to understand under casual observation.

  • Ensure a clean layout; avoid overlapping or confusing signal paths.
  • Clearly label Simulink blocks intended for user interaction. Examples: Configuration switches, setpoints.
  • Use color coding to enhance model readability:
    • Color code From and Goto blocks according to their associated signals, matching colors to the Campus Energy Modeling library subcategories.
    • Color outputs and scopes gray to set them apart.
    • Use red text to identify blocks intended for user interaction.
  • Provide labels and contextual notes as required to understand the layout of the model.

Existing demos provide concrete examples of these style guidelines.

Initialization Script

Each demo that requires initialization should include a single initialization script named mydemo_init.m, in which mydemo is the name of the demo. This initialization script should conform to the following template:

%% [Name of Demo] Demo - Initialization Script
%
% Provide a brief summary of the function of the initialization script in
% relationship to the demo. Include guidance for user settings, if needed.
%
% Multiple descriptive paragraphs are fine.
%
% COMMENTS:
% 1. Reserve any extensive comments for the comments section.
%
% 2. Number comments sequentially.
%
% 3. The COMMENTS section is optional.

%% User Settings
% If the demo has any user-configurable settings, this section is required.

% Allow users to input settings in the format:
setting = [value];

% Provide brief guidance for each setting

%% Other Sections
% Run all code to initialize the demo here.
% All remaining code sections in the script must not require user input.

The initialization script should be easy to understand and modify. Comments within the initialization script should pertain specifically to the initialization of the demo; place more general comments in the demo's README.txt.

Documentation

Individual demos are documented in three places:

  1. In the demo list under Demos
  2. In the README.txt file for each demo
  3. In the demo initialization script (if any)

To document a new demo, please add it to the demo list and create README.txt according to the guidelines in Writing Documentation. README.txt should contain step-by-step instructions for initializing and executing the demo. These instructions should follow the general pattern:

Instructions: 
1.  Open MATLAB and set the working directory to the folder that contains this README file.
2.  Open the script 'mydemo_init.m'.
3.  Review the user settings in 'mydemo_init.m' and modify as desired.
4.  Run 'mydemo_init.m' to initialize the demo.
5.  Open and run the Simulink model 'mydemo.mdl' and view the results.

Whenever possible, avoid burdening the user with initialization requirements beyond editing and running the initialization script. Any detailed instructions or comments related to demo initialization should be included within the initialization script itself.

Testing

Prior to release, demos should be tested using the following procedure:

  1. Commit (or stash) any uncommitted changes.
  2. Back up the Demo directory manually to another location on disk.
  3. Delete the Demo directory from the project.
  4. Reset the project using git reset --hard. This restores the exact version of the Demo directory last committed to Git.
  5. Run the demo initialization script.
  6. Run the demo simulation.

Step 2 is a precaution in case your demos contain inadvertently uncommitted scripts or data; if you are sure this is not the case you may skip it. Steps 5 and 6 ensure that the demo runs cleanly "out of the box", that is, freshly loaded from a Campus Energy Modeling release.

If the test uncovers any errors, such as missing data files or sections of the initialization script which do not operate properly, fix these errors, commit, and re-run the test.

Clone this wiki locally