Difference between revisions of "OpenModelica/C3/Modelica-Packages/English"

From Script | Spoken-Tutorial
Jump to: navigation, search
 
Line 50: Line 50:
  
 
'''Package'''
 
'''Package'''
|| A '''Package''' is a specialized class in '''Modelica'''.
+
|| A '''Package''' is a specialized '''class''' in '''Modelica'''.
  
 
It is a collection of '''classes'''.  
 
It is a collection of '''classes'''.  
  
 
It can be stored as a '''single file''' or a '''directory'''.
 
It can be stored as a '''single file''' or a '''directory'''.
 +
  
 
We will first learn about '''single file storage'''.
 
We will first learn about '''single file storage'''.
Line 62: Line 63:
  
 
'''Single file storage'''
 
'''Single file storage'''
|| In '''single file storage''' all classes belonging to a '''package''' are written in a '''single file'''.
+
|| In '''single file storage''' all '''classes''' belonging to a '''package''' are written in a '''single file'''.
  
 
It is not recommended as it may get lengthy in a few cases.
 
It is not recommended as it may get lengthy in a few cases.
Line 93: Line 94:
  
 
* '''bouncingBallWithImport'''.  
 
* '''bouncingBallWithImport'''.  
 +
  
 
You may also open each of them individually.
 
You may also open each of them individually.
 +
  
 
Note that I have not selected '''spokenTutorialExamples''' folder.
 
Note that I have not selected '''spokenTutorialExamples''' folder.
 +
  
 
We shall discuss more about it when we look at directory storage.
 
We shall discuss more about it when we look at directory storage.
  
Click on '''Open'''.
+
 
 +
|-
 +
||Click '''Open'''.
 +
||Click on '''Open'''.
  
 
You may see that '''spokenTutorialExamples''' package is now seen in '''Libraries Browser'''.
 
You may see that '''spokenTutorialExamples''' package is now seen in '''Libraries Browser'''.
Line 135: Line 142:
  
  
*'''freefall''' class
+
*'''freefall class'''
 
* '''bouncingBall''' model and
 
* '''bouncingBall''' model and
 
* '''bouncingBallWithUserTypes''' models.
 
* '''bouncingBallWithUserTypes''' models.
Line 141: Line 148:
 
|-
 
|-
 
|| '''end spokenTutorialExamples;'''
 
|| '''end spokenTutorialExamples;'''
|| '''end''' statement defines where the package ends.
+
|| '''end statement''' defines where the package ends.
  
 
|-
 
|-
Line 147: Line 154:
 
|| We have viewed all '''classes''' and '''models''' of this package at one place.  
 
|| We have viewed all '''classes''' and '''models''' of this package at one place.  
  
Now, let us learn how to view individual classes in a package.
+
Now, let us learn how to view individual ''classes'' in a package.
  
 
|-
 
|-
Line 159: Line 166:
 
|| Double-click on '''freeFall''' in '''Libraries Browser'''.  
 
|| Double-click on '''freeFall''' in '''Libraries Browser'''.  
  
'''freeFall''' class has now opened.  
+
'''freeFall class''' has now opened.  
  
Individual classes of a package may be simulated.  
+
Individual '''classes''' of a package may be simulated.  
  
 
But the package itself can not be simulated.
 
But the package itself can not be simulated.
Line 191: Line 198:
  
 
'''Directory storage'''
 
'''Directory storage'''
|| In '''Directory storage''' classes are stored in separate files.
+
|| In '''Directory storage classes''' are stored in separate files.
  
 
Name of directory is same as that of the package.
 
Name of directory is same as that of the package.
Line 197: Line 204:
 
A file named '''package.mo''' is to be included in the directory and  
 
A file named '''package.mo''' is to be included in the directory and  
  
Each class starts with a '''within''' statement.  
+
Each '''class''' starts with a '''within statement'''.  
  
 
|-
 
|-
Line 267: Line 274:
 
|| The difference between single file and directory storage can only be understood when we open this '''package''' using a text editor like '''gedit'''.  
 
|| The difference between single file and directory storage can only be understood when we open this '''package''' using a text editor like '''gedit'''.  
  
You may use notepad or any other text editor if you are using '''Windows'''.
+
You may use '''Notepad''' or any other text editor if you are using '''Windows'''.
  
 
|-
 
|-
Line 285: Line 292:
 
|-
 
|-
 
|| '''within;'''  
 
|| '''within;'''  
|| '''within''' statement indicates that this file represents a '''package'''.
+
|| '''within statement''' indicates that this file represents a '''package'''.
  
 
|-
 
|-
Line 295: Line 302:
 
|-
 
|-
 
|| '''end spokenTutorialExamples;'''
 
|| '''end spokenTutorialExamples;'''
|| '''package.mo''' file can only contain the '''within''' statement and '''package''' declaration.
+
|| '''package.mo''' file can only contain the '''within statement''' and '''package''' declaration.
  
 
|-
 
|-
|| Let me switch to '''freeFall''' tab.
+
|| Switch to '''freeFall''' tab.
 
|| Let me switch to '''freeFall''' tab.
 
|| Let me switch to '''freeFall''' tab.
  
Line 305: Line 312:
  
 
'''within spokenTutorialExamples;'''
 
'''within spokenTutorialExamples;'''
|| This '''within''' statement indicates that '''freefall''' class belongs to '''spokenTutorialExamples''' package.  
+
|| This '''within statement''' indicates that '''freefall class''' belongs to '''spokenTutorialExamples''' package.  
  
Rest of this file has information specific to '''freeFall''' class.
+
Rest of this file has information specific to '''freeFall class'''.
  
 
|-
 
|-
Line 313: Line 320:
 
|| You may see that other models in this package namely '''bouncingBallWithUserTypes''' and '''bouncingBall''' follow a similar syntax as well.  
 
|| You may see that other models in this package namely '''bouncingBallWithUserTypes''' and '''bouncingBall''' follow a similar syntax as well.  
  
But, we didn’t observe '''within''' statement when we opened the package in '''OMEdit'''.  
+
But, we didn’t observe '''within statement''' when we opened the package in '''OMEdit'''.  
  
This indicates that '''within''' statement helps '''OMEdit''' recognize the file structure.  
+
This indicates that '''within statement''' helps '''OMEdit''' recognize the file structure.  
  
 
Hence, it is omitted by '''OMEdit''' while displaying the '''package'''.
 
Hence, it is omitted by '''OMEdit''' while displaying the '''package'''.
Line 329: Line 336:
 
|| We shall now understand more about '''Modelica Library'''.
 
|| We shall now understand more about '''Modelica Library'''.
  
'''Modelica Library''' is an open-source package.
+
*'''Modelica Library''' is an open-source package.
  
'''OMEdit''' automatically loads it for every session.  
+
*'''OMEdit''' automatically loads it for every session.  
  
It can be seen in '''Libraries Browser'''.
+
*It can be seen in '''Libraries Browser'''.
  
It has classes from mechanical, electrical and thermal domains.
+
*It has '''classes''' from '''mechanical, electrical''' and '''thermal''' domains.
  
 
'''Classes''' of this library can be referenced and used.
 
'''Classes''' of this library can be referenced and used.
Line 353: Line 360:
 
|-
 
|-
 
|| Click '''on (plus) SIunits'''
 
|| Click '''on (plus) SIunits'''
|| Of special mentioned is the '''SIunits''' package.  
+
|| Of special mention, is the '''SIunits''' package.  
  
 
Expand it.  
 
Expand it.  
Line 361: Line 368:
 
|| This package has type definitions for physical quantities like '''Angle, Length, Position''' etc.  
 
|| This package has type definitions for physical quantities like '''Angle, Length, Position''' etc.  
  
We shall see how to use these type definitions using '''bouncingBallWithImport''' class.  
+
We shall see how to use these type definitions using '''bouncingBallWithImport class'''.  
  
 
Compress '''SIunits'''.
 
Compress '''SIunits'''.
Line 435: Line 442:
 
|| It is tedious to use the full name of a class every time.  
 
|| It is tedious to use the full name of a class every time.  
  
This can be simplified using '''import''' statement.  
+
This can be simplified using '''import statement'''.  
  
Now, we shall type a few statements that show the use of '''import'''.  
+
Now, we shall type a few '''statements''' that show the use of '''import'''.  
  
The statements to be typed are provided in a text file named '''import-statements.txt'''.  
+
 
 +
The '''statements''' to be typed are provided in a text file named '''import-statements.txt'''.  
  
 
Go to the location where you saved it on your system.  
 
Go to the location where you saved it on your system.  
Line 445: Line 453:
 
Double-click on '''import-statements.txt'''.
 
Double-click on '''import-statements.txt'''.
  
'''Windows''' users may use notepad to open this file.
+
'''Windows''' users may use '''Notepad''' to open this file.
  
 
|-
 
|-
Line 461: Line 469:
 
|| The file is now open in '''gedit'''.
 
|| The file is now open in '''gedit'''.
  
Copy all the statements using '''Ctrl+C''' or by doing right click.
+
Copy all the statements using '''Ctrl+C''' or by doing right-click.
  
 
|-
 
|-
Line 477: Line 485:
 
|| Switch to '''OMEdit'''.  
 
|| Switch to '''OMEdit'''.  
  
Paste all the statements at the beginning of the model.  
+
Paste all the '''statements''' at the beginning of the model.  
  
 
|-
 
|-
Line 483: Line 491:
  
 
'''Modelica.SIunits.Velocity''' //
 
'''Modelica.SIunits.Velocity''' //
|| Delete the declaration statements for '''Length''' and '''Velocity''' which have been defined before.
+
|| Delete the '''declaration statements''' for '''Length''' and '''Velocity,''' which have been defined before.
  
 
Delete the extra spaces.
 
Delete the extra spaces.
 +
  
 
Save this model by pressing '''Ctrl + S'''.
 
Save this model by pressing '''Ctrl + S'''.
Line 496: Line 505:
  
 
Close the pop up window.
 
Close the pop up window.
 +
 
|-
 
|-
 
|| Select '''h''' in the '''Variables Browser''' and Click on '''Modeling''' button.
 
|| Select '''h''' in the '''Variables Browser''' and Click on '''Modeling''' button.
Line 516: Line 526:
 
|| Now let us now try to understand the '''import''' statements.  
 
|| Now let us now try to understand the '''import''' statements.  
  
Using the '''import''' statements Modelica looks up for '''Length''' and '''Velocity''' type definitions using the path mentioned here.
+
Using the '''import statements''', '''Modelica''' looks up for '''Length''' and '''Velocity''' type definitions using the path mentioned here.
  
 
This saves the trouble of referring to the package every time.
 
This saves the trouble of referring to the package every time.
Line 530: Line 540:
  
 
//
 
//
|| Now let us see how we can replace these two '''import''' statements by a single '''import''' statement.
+
|| Now let us see how we can replace these two '''import statements''' by a single '''import statement'''.
  
Delete the two statements.
+
Delete the two '''statements'''.
  
 
|-
 
|-
Line 544: Line 554:
 
|-
 
|-
 
||  
 
||  
|| This statement is known as a '''wild-card import'''.
+
|| This '''statement''' is known as a '''wild-card import'''.
  
This way, any class from '''SIunits''' may be accessed without explicitly mentioning it.
+
This way, any '''class''' from '''SIunits''' may be accessed without explicitly mentioning it.
  
 
|-
 
|-
|| Click on '''simulate'''.
+
|| Click on '''Simulate'''.
 
|| Now let me '''Simulate''' this model.
 
|| Now let me '''Simulate''' this model.
  
Click on '''simulate''' button.
+
Click on '''Simulate''' button.
  
 
Close the pop up window.
 
Close the pop up window.
Line 577: Line 587:
 
||As an assignment,  
 
||As an assignment,  
  
Declare variable '''h''' and '''v''' of '''freeFall''' class as '''Length''' and '''Velocity''' types respectively.
+
Declare variable '''h''' and '''v''' of '''freeFall class''' as '''Length''' and '''Velocity''' types respectively.
  
These type definitions can be found in '''SIunits''' package of Modelica library.
+
These type definitions can be found in '''SIunits''' package of '''Modelica''' library.
  
 
|-
 
|-

Latest revision as of 14:11, 5 April 2016

Visual Cue Narration
Slide:

Title Slide

Welcome to the Spoken Tutorial on Packages.
Slide:

Learning Objectives

In this tutorial, we are going to learn:
  • How to create a package of classes in Modelica.
  • How to reference classes in a package.
  • How to import a package and
  • How to use Modelica Library.
Slide:

System Requirements

To record this tutorial, I am using
  • OpenModelica 1.9.2 and
  • Ubuntu Operating System version 14.04 and
  • gedit.

Windows users may use Notepad or any other text editor instead of gedit.

Slide:

Prerequisites

To understand and practice this tutorial, you need
  • Knowledge of class and type definition in Modelica.
  • Prerequisite tutorials are mentioned on our website.

Please go through them.

Slide:

Package

A Package is a specialized class in Modelica.

It is a collection of classes.

It can be stored as a single file or a directory.


We will first learn about single file storage.

Slide:

Single file storage

In single file storage all classes belonging to a package are written in a single file.

It is not recommended as it may get lengthy in a few cases.

/* OMEdit */

Click on Modeling button at bottom right

Now let me switch to OMEdit to demonstrate single file storage for a package.
Please download and save all the files available on our website.

You may see that there is a file and a folder bearing the name spokenTutorialExamples.

Please download both of them.

Now, let me open the necessary files in OMEdit.

Press Ctrl + O.

Go to the appropriate location on your system and select

  • spokenTutorialExamples.mo,
  • bouncingBallWithUserTypes.mo and
  • bouncingBallWithImport.


You may also open each of them individually.


Note that I have not selected spokenTutorialExamples folder.


We shall discuss more about it when we look at directory storage.


Click Open. Click on Open.

You may see that spokenTutorialExamples package is now seen in Libraries Browser.

Double click on spokenTutorialExamples icon.
Switch to Text View if the file opens in Icon/Diagram View.
/* spokenTutorialExamples */

package spokenTutorialExamples

Now let me discuss spokenTutorialExamples

First line defines the name of a package.

Evidently, name of this package is spokenTutorialExamples.

Highlight piecewise //

class freeFall

model bouncingBall

model bouncingBallWithUserTypes

//

This package consists of


  • freefall class
  • bouncingBall model and
  • bouncingBallWithUserTypes models.
end spokenTutorialExamples; end statement defines where the package ends.
We have viewed all classes and models of this package at one place.

Now, let us learn how to view individual classes in a package.

Click on the (+) button with spokenTutorialExamples in Libraries Browser. Click on the (+) button besides spokenTutorialExamples icon in Libraries Browser.

This displays the names of classes present in this package.

Double-click on freeFall. Double-click on freeFall in Libraries Browser.

freeFall class has now opened.

Individual classes of a package may be simulated.

But the package itself can not be simulated.

Let me go back to spokenTutorialExamples tab. Let me go back to spokenTutorialExamples tab.
Hover over Simulate button in toolbar. Note that Simulate button doesn’t appear in the toolbar which indicates that this package cannot be simulated.
Now let me unload spokenTutorialExamples from OMEdit.

Do a right-click and select unload.

Select Yes.

This is done so as to avoid conflict when demonstrating directory storage.

Now let me go back to the slides.
Slide:

Directory storage

In Directory storage classes are stored in separate files.

Name of directory is same as that of the package.

A file named package.mo is to be included in the directory and

Each class starts with a within statement.

Now, let me demonstrate the folder spokenTutorialExamples that you’ve downloaded.

Note that this folder represents the same package as that we have already discussed.

Let me demonstrate the file structure of this folder.

Go to the location where you saved the downloaded files on your system.

/* spokenTutorialExamples folder */ Double-click on spokenTutorialExamples folder.

Notice that the folder has following files:

  • package.mo,
  • freeFall.mo,
  • bouncingBallWithUserTypes and
  • bouncingBall.

We shall understand more about directory storage using both OMEdit and gedit.

/* Directory */ Note that package.mo indicates that this folder represents a package.

Without this file, the folder doesn’t represent a Modelica package.

/* OMEdit */

Ctrl+O

spokenTutorialExamples → package.mo

Now, let me switch to OMEdit to demonstrate directory storage.

Press Ctrl + O.

Navigate to the spokenTutorialExamples folder that you have downloaded.

Select package.mo from this folder and click on Open.

Double-click on spokenTutorialExamples in Libraries Browser. spokenTutorialExamples package can now be seen in Libraries Browser.

Double-click on spokenTutorialExamples icon.

/* spokenTutorialExamples */ Open the package in Text View if it opens in either Icon/Diagram View.
/* spokenTutorialExamples */

Scroll down

If you scroll down, you may notice that this package is the same as that we have seen in single file storage.
The difference between single file and directory storage can only be understood when we open this package using a text editor like gedit.

You may use Notepad or any other text editor if you are using Windows.

Right-click on spokenTutorialExamples and select unload. Now let me unload spokenTutorialExamples package from 'OMEdit.
/* Download location */

Double-click on bouncingBall.mo, bouncingBallWithUserTypes ,freeFall, package.mo.

Switch to spokenTutorialExamples folder and open all the files using gedit.

Now all the files are open in gedit.

Let us take a look at package.mo first.

within; within statement indicates that this file represents a package.
package spokenTutorialExamples Name of this package is spokenTutorialExamples.

Note that the name of folder was spokenTutorialExamples as well.

end spokenTutorialExamples; package.mo file can only contain the within statement and package declaration.
Switch to freeFall tab. Let me switch to freeFall tab.
/* freeFall */

within spokenTutorialExamples;

This within statement indicates that freefall class belongs to spokenTutorialExamples package.

Rest of this file has information specific to freeFall class.

You may see that other models in this package namely bouncingBallWithUserTypes and bouncingBall follow a similar syntax as well.

But, we didn’t observe within statement when we opened the package in OMEdit.

This indicates that within statement helps OMEdit recognize the file structure.

Hence, it is omitted by OMEdit while displaying the package.

Let me go back to the slides.
Slide:

Modelica Library

We shall now understand more about Modelica Library.
  • Modelica Library is an open-source package.
  • OMEdit automatically loads it for every session.
  • It can be seen in Libraries Browser.
  • It has classes from mechanical, electrical and thermal domains.

Classes of this library can be referenced and used.

Now let me switch to OMEdit to demonstrate Modelica Library.
Click on (plus) Modelica Locate Modelica icon in Libraries Browser and expand it.

Note that Modelica Library has packages named Blocks, Complex Blocks etc.

You may note that a package may further contain packages as well as is evident here.

Click on (plus) SIunits Of special mention, is the SIunits package.

Expand it.

Click on (minus) SIunits This package has type definitions for physical quantities like Angle, Length, Position etc.

We shall see how to use these type definitions using bouncingBallWithImport class.

Compress SIunits.

Double-click on bouncingBallWithUserTypes and bouncingBallWithImport icons in Libraries Browser. And double-click on bouncingBallWithImport and bouncingBallWithUserTypes.
Let me shift OMEdit window to the left for better visibility.
We shall first look at bouncingBallWithUserTypes.

We have learnt about this model in the prerequisite tutorials.

/* bouncingBallWithUserTypes */

type Length = Real(unit = “m”);

type Velocity = Real(unit = “m/s”);

This model has type definitions named Length and Velocity.

We can instead use the type definition in SIunits instead of defining them explicitly in every model.

We shall see how to do that using bouncingBallWithImport model.

/* bouncingBallWithImport */ Let me switch to bouncingBallWithImport.
Modelica.SIunits.Length h; A class in a package is referenced to using dot.

Modelica.SIunits refers to SIunits package which belongs to Modelica library.

Modelica.SIunits.Length h; Variable h is declared to be of Length type which is defined in SIunits package.
Modelica.SIunits.Velocity v; Similarly, variable v is declared to be of Velocity type which is defined in SIunits package.
Note that parameters radius and g are declared in a similar fashion.

Now let me Simulate this model.

Click on Simulate button in the toolbar.

Close the pop up window.

Select h in the Variables Browser.

Note that the plot obtained is similar to the one seen in the case of bouncingBallWithUserTypes.

let me de-select h.

Delete the result.

Switch to Modeling perspective.

It is tedious to use the full name of a class every time.

This can be simplified using import statement.

Now, we shall type a few statements that show the use of import.


The statements to be typed are provided in a text file named import-statements.txt.

Go to the location where you saved it on your system.

Double-click on import-statements.txt.

Windows users may use Notepad to open this file.

/* gedit */

Copy the statements:

import Modelica.SIunits.Length;

import Modelica.SIunits.Velocity;

Length h;

Velocity v;

The file is now open in gedit.

Copy all the statements using Ctrl+C or by doing right-click.

Paste //

import Modelica.SIunits.Length;

import Modelica.SIunits.Velocity;

Length h;

Velocity v;

//

Switch to OMEdit.

Paste all the statements at the beginning of the model.

Delete // Modelica.SIunits.Length //

Modelica.SIunits.Velocity //

Delete the declaration statements for Length and Velocity, which have been defined before.

Delete the extra spaces.


Save this model by pressing Ctrl + S.

Now the model is complete and ready for simulation.

Click on Simulate button. Click on Simulate button to simulate it.

Close the pop up window.

Select h in the Variables Browser and Click on Modeling button. Select h in the Variables Browser.

Note that the plot is same as in previous case.

De-select h and delete the result.

Switch to Modeling perspective.

//

import Modelica.SIunits.Length;

import Modelica.SIunits.Velocity;

//

Now let us now try to understand the import statements.

Using the import statements, Modelica looks up for Length and Velocity type definitions using the path mentioned here.

This saves the trouble of referring to the package every time.

A detailed discussion of lookup rules is beyond the scope of this tutorial.

Delete //

import Modelica.SIunits.Length;

import Modelica.SIunits.Velocity;

//

Now let us see how we can replace these two import statements by a single import statement.

Delete the two statements.

Type //

import Modelica.SIunits.*;

And type import (space) Modelica (dot) SIunits (dot) asterisk (semicolon)

Save this model by pressing Ctrl + S

This statement is known as a wild-card import.

This way, any class from SIunits may be accessed without explicitly mentioning it.

Click on Simulate. Now let me Simulate this model.

Click on Simulate button.

Close the pop up window.

Select h Select h in the Variables Browser.

You may notice the similarity of plot once again.

De-select h and delete the result.

Click on Modeling. Go back to Modeling perspective.
Now let me switch to the slides.
Slide:

Assignment

As an assignment,

Declare variable h and v of freeFall class as Length and Velocity types respectively.

These type definitions can be found in SIunits package of Modelica library.

This brings us to the end of this tutorial.
Slide:

About the Spoken Tutorial project

Watch the video available at the link shown below:

http://spoken-tutorial.org /What\_is\_a\_Spoken\_Tutorial

It summarises the Spoken Tutorial project.

If you have questions in this Spoken Tutorial, please visit the website shown.

Slide:

Textbook Companion Project

We coordinate coding of solved examples from popular books.

We give honorarium to contributors.

Please visit our website.

Slide:

Lab Migration Project

We help migrate labs from commercial simulators to OpenModelica.

Please visit the following website.

Slide:

Acknowledgements

Spoken Tutorial Project is supported by NMEICT, MHRD Government of India.
Slide:

Thanks

We thank the development team of OpenModelica for their support.
I would like to thank you for joining me in this tutorial.

Good bye.

Contributors and Content Editors

Kaushik Datta, Nancyvarkey