Organizing Simulink files and folders in a project
Today I am happy to welcome Sarah Dagen from MathWorks Consulting Services to talk about project organization.
I recently received this email from a friend:
I'm helping my friends get started with Simulink and I wondered if there is a recommended folder structure for Simulink projects. I found stuff online for MATLAB toolboxes (see this for example), but nothing for Simulink. The project will include all the usual stuff:
- Simulink models in a model ref hierarchy
- Libraries of Simulink components
- Generation of production and HIL code from models
- Handwritten C/C++ code and blocks to use it from models
- Unit and system level tests
- MATLAB analysis scripts
- Data
I thought others might be interested in this, too. This is one of the most common questions I get from customers and colleagues alike.
While there is no definitive "right" answer, after 10+ years of consulting with Simulink users across many industries and applications, I have converged on a file and folder structure for managing the materials relating to Model-Based Design that works well for me. (That's why I have friends who actually send me emails like that one above.)
You may disagree with the details of my organization scheme, and that's fine. What is important is to have a scheme, whatever it is, and apply it consistently.
I'll explain the main features of my preferred project structure.
Simple top-level organization
The first thing is to always use Projects! Projects are my number one most useful tool for Model-Based Design. I have a project template that I use as a starting point. You can download it and open it here: ExampleProjectStructure.sltx
I want a simple structure at the top that is agnostic to the project details, so will look the same for every project regardless of the application.
Here are the folders I start with for the project root, and what I use them for:
- cache: This is for automatically generated Simulink files, like .slxc and slprj files
- codegen: Automatically generated code goes here. More on this and the cache folder below.
- data: Store data in here that is shared across the project. Examples include: configuration sets that are referenced by multiple models; global data such as sample times or other design data used in multiple models
- doc: Project-level documentation. Includes information such as how this project is meant to be used.
- internal: Scripts, functions, and utilities that are used for the management of the project itself. In this example, I've put a function that generates a model structure in this folder. The contents of this directory are agnostic to the particular systems represented in the project models.
- libraries: Simulink libraries or other libraries used by the project models, such as C/C++ source
- models: All of the model folder structures go in here. More on that below.
- utilities: Scripts, functions, and other utilities that are specific to the files in the project, such as analysis or visualization.
Location for generated files
I use separate folders, "cache" and "codegen", for cache and code generation files, respecitvely. Back when Guy wrote about this in 2015, you had to write code to handle this in a project startup script, but now projects have a built-in feature to handle this.
File/folder pattern for model files
Let's say I want to add a model named vehicleA, I can call the utility function createNewModel:
createNewModel('vehicleA')
It will generate this folder structure inside the models folder:
We have:
- <ModelName>: Top folder created for each model. Contains a Simulink model with the same name.
- data: Data dictionary, and any data required to construct the model's data dictionary, such as scripts for calculating parameter values.
- doc: Documentation on this model.
- requirements: Requirements for the model. Ideally these would be linked to the model's elements.
- test: Simulink Test Manager, test harness, and a folder to store baseline data.
The idea is that, as much as possible, I should be able to pick up the top directory containing the model and have a standalone "package" with the model and its data, requirements, documentation, and all its unit test materials (test harnesses, test case files, test inputs and expected results, etc.). For larger systems, and truly standalone components, these could graduate to standalone projects that are referenced by another project. I'm keeping it simple here for this example.
For each model in my project, I create a folder with the name of the model:
createNewModel('vehicleB')
createNewModel('vehicleC')
The repeating file/folder structure lends itself nicely to automation. Depending on the project, I leverage this to differing degrees and might include automation for things like test case generation, documentation, or other templated files.
What about model reference hierarchies? I do not represent model reference hierarchies in my folder structure; I put all model files at the same level.
This is for a few reasons:
- I don't always have a single hierarchy; I often have reference models that are used in several hierarchies, so it wouldn't make sense to have them stored in one particular hierarchy.
- I want to encourage myself and my collaborators to apply the same amount of organization and discipline with all models, whether they are at the top of a hierarchy or not (such as having tests and documentation for every model).
- Over time, I've found that folder hierarchies can get really, really messy and hard to maintain.
- For the top-level models that I want users to easily find as an entry point to the project, I use project shortcuts.
Scaling up
As project size and complexity increases, I use project references to manage things. Some aspects of my project structure change a bit for this, but the general features that I have discussed here stay the same.
Now it's your turn
Try my project template and let us know what you think in the comments below! Feel free to use this as a starting point and adapt it to your specific needs.
There are many different ways to structure and organize files; I'd like to hear about your favorite patterns, and why they work well for you.
- Category:
- Projects,
- Simulink Tips,
- Standards and Guidelines
Comments
To leave a comment, please click here to sign in to your MathWorks Account or create a new one.