Have you ever noticed the same block constructs occurring repeatedly in your model? Simulink libraries provide you with a way to capture the template for an algorithm, and then reuse that template all over your model. For this post, I will to introduce the basic concepts of libraries, library blocks, and library links.
Creating a library
To create a Simulink library, you have to create a new Simulink library from the File> New > Library menu, or using the new_system function.
Libraries are special MDL-files. When you look at a library, you will notice that it does not have the simulation controls a normal model has. The library is not a functional model; it is a palette of components. Here is an example library that contains a block for doing variable saturation of a signal.
The library can be constructed in the same way a model is constructed, by dragging blocks into the library canvas and connecting signals. The Saturation Dynamic block is just a subsystem that contains the algorithm for dynamic saturation of the signal u:
Locking the library
When a library is first created, it is unlocked.
This allows you to edit and build the components. Once you save the library and close it, the library is locked.
No changes are allowed without unlocking the library. This can be done from Edit > Unlock Library. Most people just drag a block a few pixels to trigger Simulink to prompt you to unlock the library.
Reference blocks and algorithm reuse
Just like the blocks from the Simulink libraries, you can add the library blocks to any model you are working on. There is some terminology that goes along with library blocks. When you add the library block to your model, you are creating a reference block.
The reference block is an instance of the library block, but the contents are not stored in the model. A model using the reference block stores only a library link, which holds the path to the library block.
>> get_param('satModel/Saturation Dynamic','ReferenceBlock')
Set the Format > Library Link Display to User to see which blocks in your model are actually library links. This setting adds a library link icon to the corner of your block.
Adding your library to the browser
At this point, you might be asking how to add the library to the library browser. The short answer is: >> doc slblocks. I provided an example of this in the historical tour of the library browser.
What do you do with libraries?
Do you maintain your own libraries? How many components does a typical library contain? Do you share your work with other modelers? Post your library to the file exchange, or leave a comment here.
26 CommentsOldest to Newest
I do use libraries regularly and share that code with others in my team. One issue (Thread: 1-6A8141) that I have come across is with the use of Embedded Matlab blocks in libraries. If the block has a non-tunable structure parameter then you cannot put it in a library if the structure ever changes (which it will). I can however place multiple copies of the same EML block in my models and it will compile OK. I would be interested if you can think of any workaround which would allow me to put the EML block in the library.
I think that a very useful future block post would be how to build and maintain large models with a number of people working on parts of the model. Simulink is used by many large companies presumably with large models maintained by a number of people. It would be good to know the tricks used by them to make maintenance easier.
Some issues I hit up against include:
– How to tell what changes have been introduced by other people. There is no “diff” — and using diff on the .mdl file is not very enlightening.
– When to use libraries vs model referencing.
– How to pass a large number of parameters into the model. I tend to use structures (now often objects) to pass info into the model workspace, but their support seems haphazard (eg cannot pass a structure into a referenced model). Do people just use the base workspace?
as Kieran I often wondered how people bring large numbers of parameters into model. I use hierachical structures reflecting the model’s subsystem hierarchy where every subsystem is masked.
However, the support of parameter structures for tunable parameters is indeed limited – there are no structures allowed for referenced models and autocoding with RTW is not possible with structure parameters. This is indeed the reason which keeps me and my collegues from using model referencing.
Do you plan to enhance the support of structures as parameters?
I would also be very interested in the topic how to build and maintain large models with several people contributing. We use an external revision control system to track the changes (SVN / CVS), but the missing diff / merge tool for Simulink is really a nuisance.
“doc slblocks” is not very enlightening (at least in 2007b). It basically says to grab a copy from one of the TMW-supplied directories and modify it, but it doesn’t really explain what’s going on. Also, the slblocks.m files in different TMW-libraries sometimes define different structures. On a related note, I tried to add my libraries to the library browser. I put four of my libraries into to top library and added it to the browser via slblocks (as best I could figure out). One of those libraries contains 10 subsystem blocks. I can drag any one of those 10 into a model from the browser. But the browser thinks that three of those are themselves libraries, and clicking on them in the browser reveals all of the blocks in that subsystem. Any idea why the browser thinks that those three subsystems are libraries? I haven’t been able to figure it out yet.
large number of parameters: I’m looking for this discussion since some weeks and couldn’t imagine that nobody else has a similar problem.
The Simulink.Parameter object seems to handle only one parameter value and not to aim at structered types.
Mathworks hints in (RTW:Creating Data Objects Based on an External Data Dictionary) the use of some external data dictionary. But only EXCEL is mentioned. Does anbody know a good tool for that.
I think an answer could be some kind of data dictionary with interfaces to most important software-independent/standardized data formats. Additionaly, the handling of parameter data in the generated source code should be handled there. Unfortunately I have only found some 3rd party products so far.
I’m looking forward that MathWorks will deal with that problem, too.
Dear Seth and Gernot,
handling a large number of parameters is a very good topic. I suggest to extend this topic to signals ans states also.
We use Simulink and Embedded Matlab to develop attitude control algorithms for spacecrafts. Simulink is used for the “architecture” of the code while the actual code is implemented in Embedded Matlab. This embedded Matlab code is directly given to the software people as specification for the coding of the on board software. In my Similink model all signals, parameters and states (about 500 data items) are well defined with type, size etc. – but how do I get this information out of the model into an Excel list or a database – in other words, how do I maintain and export a data dictionary? I think this point is not well covered in simulink today.
Dear Seth and Kieran,
don’t know whether you already found a solution for the missing diff/merge feature. We had the same issue here – we wanted to automate failure injection into Simulink models, and required both diff and merge.
Due to the fact that it was unavailable, we built an own solution called medini unite – it’s a MATLAB/Simulink diff/merge tool (both diff analysis and graphical merge are supported, now we are in public beta, public product release will be 03/2009. It can also run headless to integrate better with versioning systems like SVN. Last but not least it’s built on top of EMF, i.e. it makes Simulink models available in the eclipse world.
If you are interested in this, please send an email to firstname.lastname@example.org.
Best Regards, Olaf
@Olaf and Kieran
Thank you for your comments. I am pleased to inform you that with the recent web update for Release 2008b, on October 30th 2008, we have introduced an XML text comparing capability that you may be interested in evaluating. MATLAB Report Generator 3.5 now has the capability to create a comparison report for a pair of XML text files. In addition, Simulink Report Generator 3.5 can use that capability to create a comparison report for pairs of XML text files, including an option to compare XML files exported from Simulink models. The XML comparison report can then display highlighted results in the original models. Please evaluate these new features in MATLAB Report Generator and Simulink Report Generator.
how can I export a Simulink model to an XML file in the first place?
@Harald – the ability to export to XML is part of Simulink Report Generator 3.5 which was released after R2008b via web download. If you have that, check out the documentation section titled “Comparing XML Files Exported from Simulink Models.”
following up my posting from January 19th, medini unite, the diff/merge tool for Simulink and Stateflow, is now available as 1.0 release, provides graphical and tree based diff and merge, undo/redo, auto merge, merge report generation, SCM integration and more. Embedded in eclipse (and therefore supporting XML/XMI) and highly performant and scalable. Demo videos and trial version available at http://www.ikv.de. Hope you’ll find some time to look at.
Best Regards, Olaf
I am facing the same problem, were you able to solve it!?
@Pat and Paul, I agree that the slblocks documentation is unexisting. From what I remember, when subsystems are masked the Library browser does not expand them and you cannot see what is under the mask.
I think the reason for this behaviour is that if you place a block in the library browser you don’t want the user to modify it. If you don’t need to define any parameters for the mask, fill some info in the documentation tab of the mask editor.
I hope it helps.
I’ve recently run into a related issue. It would appear that if you create your own masked sub-system and want to include it in a library in an expandable form, you cannot add any “Mask Description”. Including a “Mask type” seems to work fine though. This is using 2007b…haven’t tried anything newer yet.
You are right when you mention that adding a “Mask Description” to a masked subsystem in a library makes it not-expandable.
This is coherent with the behavior of masked subsystems in a model. Typically you mask a subsystem when you think the user should not look inside. If the user should not look inside, then the subsystem should not expand in the Library Browser.
As an additional note, if a masked subsystem have parameters, you do not need to add a “Mask Description” to hide it’s content. For masked subsystems without parameters, it is by adding a “Mask Description” that you force the user to “look under mask” to see its content.
Seth, I am confused with how XML is being used with Mathworks products. Does there exist the capability to generate embedded code from XML? If so where can I read more about it.
@Alex – XML is not a part of embedded code generation with Real-Time Workshop. We have documentation that describes how to compare XML files exported from Simulink models. That is a good resource to reference for more information on this capability.
I would like to know when to use libraries vs model referencing too. Thanks!
Please let me know if you find any guideline/document advising “when to use libraries vs model referencing”.
I’m facing the same issue, what should be used for large collaborative models?
@Zhibo, @Moreno: When you say Libraries vs Model Reference, I interpret your question as when to use SUBSYSTEMS vs Model Reference. Generally, it is an architectural choice. We have seen people take Model Reference to the wrong extreeme, such as, reference models with only 3 blocks in them. This is more appropriately modeled with subsystems. Generally, if you have a plan for your model architecture, you can easily try model reference at certain levels, and decide if it meets your need. If you select a level that is too low in the hierarchy, you end up with the problem I describe above. If you select a level too high in the hierarchy, you don’t get the maximum benefit from Model Reference features (such as incremental workflows, and componetization).
There are existing guidelines that address the use of Model Reference. The one I have most recently looked at is the NASA Orion GN&C Standards. I reccomend you review those, and search for “model reference”:
Or, go directly to the NASA Orion GN&C Simulink Standards PDF, section 4.4.3 ORION GN&C Model Architecture Decomposition for an example of how they did it.
@Seth,@Zhibo; Thanks for your answer I found another very usefull document concerning Libraries vs Model Reference at “http://www.mathworks.com/programs/cd_mbd/” Large-Scale Modeling for Embedded Applications
In regards to libraries I cannot find any information regarding the ability to update a version of a model at its source file which then updates the block held within the library file.
Is this possible or do you need to open up the library file every time and copy the updated block in?
I have been using libraries all along and I find it essential for getting the most out of Simulink.
Also I find it very useful to have the display of library links (as icons) turned on by default:
I’m looking for a way to lock the libraries blocks that I generate by the use of a password.
I would share these simulink blocks with my customers so that they can use my blocks without giving them the chance to unlock these to preserve the intellectual property of my company.
thanks in advance
@Zzaimon: The solution we recommend for that is protected reference model. See an example here:
Can we make Our Libraries without permission of @mathworks ?