{"id":11227,"date":"2021-12-27T12:06:23","date_gmt":"2021-12-27T17:06:23","guid":{"rendered":"https:\/\/blogs.mathworks.com\/simulink\/?p=11227"},"modified":"2021-12-27T12:06:50","modified_gmt":"2021-12-27T17:06:50","slug":"generating-reports-for-a-simulink-model-including-latex-equations","status":"publish","type":"post","link":"https:\/\/blogs.mathworks.com\/simulink\/2021\/12\/27\/generating-reports-for-a-simulink-model-including-latex-equations\/","title":{"rendered":"Generating Reports for a Simulink Model including LaTeX Equations"},"content":{"rendered":"
Today I am happy to welcome guest blogger <\/span>Sarah Dagen<\/span><\/a>, from <\/span>MathWorks Consulting<\/span><\/a>.<\/span><\/div>
Sarah first lists different options available in Simulink to document your design, and concludes with a new capability added recently: Using LaTeX equations in Simulink Notes, which allows you to automatically produce reports, thanks to the <\/span>Simulink Report Generator API for notes<\/span><\/a>!<\/span><\/div>

Introduction<\/span><\/h4>
While the functional behavior of models we create is usually the star of the show, anyone who has had to review, test, or maintain these knows that documentation can be the real hero. Simulink offers many ways to capture information along with a design, allowing you to create documentation as you go; here are a few examples:<\/span><\/div>

Block Description<\/span><\/h4>
If you right-click on any block and select \"Properties...\", the General tab offers a \"Description\" field.<\/span><\/div>
\"\"<\/img><\/div>
This can also be get\/set programmatically:<\/span><\/div>
\"\"<\/img><\/div>

Annotation<\/span><\/h4>
Double-clicking in the Simulink canvas allows you to create annotations. Once the annotation has been created, you can click on its edge and attach it to a block. It is also possible to <\/span>create annotations programmatically<\/span><\/a><\/div>
\"\"<\/img><\/div>

Area<\/span><\/h4>
Starting from the left toolbar, it is possible to create areas. In addition to allowing you to type a description, an area allows you to move all the blocks inside it as a group.<\/span><\/div>
\"\"<\/img><\/div>

Block Annotation<\/span><\/h4>
The Block Properties dialog allows you to create block annotations. In block annotations, you can use tokens to display the value of bock parameters.<\/span><\/div>
\"\"<\/img><\/div>

Doc Block<\/span><\/h4>
The <\/span>DocBlock<\/span><\/a> is another option to document a Simulink model. Add the block to any Subsystem, double-click on it and start typing. If you open the mask parameters for the DocBlock, you can configure it to open the note as either text, RTF or HTML.<\/span><\/div>
\"\"<\/img><\/div>

Equations<\/span><\/h4>
Much of what we model in Simulink is based on equations. While Simulink is great for visualizing the flow of data through algorithms, sometimes it\u2019s a lot easier to understand what\u2019s going on if you can just see the equation that is being modeled. <\/span><\/div>
While you might be used to seeing equations typed in plain text, it can be much easier to understand when rendered the way you might write it out by hand -- this is why so many engineers and scientists love TeX and <\/span>LaTeX<\/span><\/a>! And while MATLAB has long provided ways to interpret TeX and LaTeX syntax, including it everywhere you might have documentation associated with a Simulink design can be tricky. <\/span><\/div>
For example, you can create Simulink canvas annotations with equations:<\/span><\/div>
\"\"<\/img><\/div>
However, it\u2019s not very straight-forward to get this type of annotation into a report that might be needed as design documentation, such as a System Design Description (SDD). A SDD is part of a high-integrity certification workflow, such as for <\/span>DO-178C<\/span><\/a>, so this can be more than just a minor annoyance. <\/span><\/div>

Model Notes<\/span><\/h4>
Notes<\/span><\/a> are another way to create documentation for your model. Notes are saved in a separate file from your model, unlike the other annotation techniques shown above. Notes are context-aware and can contain and display content for subsystems throughout your model hierarchy. And, notes can include equations! <\/span><\/div>
\"\"<\/img><\/div>
When someone else will open the model, this will look like:<\/span><\/div>
\"\"<\/img><\/div>

Report Generation<\/span><\/h2>
Now it\u2019s time to bring all this together\u2026 information that is sensitive to its Simulink context, includes mathematical equations and formatting, and can be used in automatically generated, portable, and complete design documentation \u2013 behold, the <\/span>Simulink Report Generator API for notes<\/span><\/a>! <\/span><\/div>
For the model in the above screenshot, this code will generate a PDF with a screenshot of the subsystem followed by the Note, including equations.<\/span><\/div>
model = <\/span>\"mVdpEqn\"<\/span>;<\/span><\/span><\/div><\/div>
open_system(model);<\/span><\/span><\/div><\/div>
import <\/span>mlreportgen.report.*<\/span><\/span><\/div><\/div>
import <\/span>slreportgen.report.*<\/span><\/span><\/div><\/div>
import <\/span>slreportgen.finder.*<\/span><\/span><\/div><\/div>
rpt = slreportgen.report.Report(model + <\/span>\"_Notes_Report\"<\/span>,<\/span>\"pdf\"<\/span>);<\/span><\/span><\/div><\/div>
open(rpt);<\/span><\/span><\/div><\/div>
titlepage = TitlePage(<\/span>\"Title\"<\/span>,model);<\/span><\/span><\/div><\/div>
add(rpt,titlepage);<\/span><\/span><\/div><\/div>
toc = TableOfContents();<\/span><\/span><\/div><\/div>
add(rpt,toc);<\/span><\/span><\/div><\/div>
finder = DiagramFinder(model);<\/span><\/span><\/div><\/div>
while <\/span>hasNext(finder)<\/span><\/span><\/div><\/div>
system = next(finder);<\/span><\/span><\/div><\/div>
ch = Chapter(<\/span>\"Title\"<\/span>,system.Name);<\/span><\/span><\/div><\/div>
add(ch,system);<\/span><\/span><\/div><\/div>
notes = Notes(system);<\/span><\/span><\/div><\/div>
add(ch,notes);<\/span><\/span><\/div><\/div>
add(rpt,ch);<\/span><\/span><\/div><\/div>
end<\/span><\/span><\/div><\/div>
close(rpt);<\/span><\/span><\/div><\/div>
rptview(rpt);<\/span><\/span><\/div><\/div><\/div>
\"\"<\/img><\/div>

Now it's your turn<\/span><\/h4>
Are you leveraging <\/span>Simulink Report Generato<\/span><\/a>r and <\/span>Simulink Notes<\/span><\/a> to document your design and automatically generate reports? Let us know in the comments below.<\/span><\/div>\r\n<\/div>