Skip to content

Commit

Permalink
Fix some documentation about component development
Browse files Browse the repository at this point in the history
Rewrite invalid documentation about component
development build environment setup and mention
built-in component generator
  • Loading branch information
peterNordin committed Feb 14, 2021
1 parent 8c0933f commit c87d1b3
Show file tree
Hide file tree
Showing 2 changed files with 13 additions and 18 deletions.
15 changes: 7 additions & 8 deletions doc/userCustomComponents.dox
Original file line number Diff line number Diff line change
@@ -1,26 +1,25 @@
/*!
\page userAutomaticCodeGenerationPage Automatically generating Component Code
\section component-generator Component Generator Dialog
Hopsan has a component skeleton generator functionality, from where new components can be written without deeper knowledge of the Hopsan simulation core interface. __Note!__ This functionality has moved into the HoLC program (included with each Hopsan release). It was previously a part of Hopsan GUI.
Hopsan has a component skeleton generator functionality, from where new components can be written without deeper knowledge of the Hopsan simulation core interface. You will find it by choosing "Create external library" in the library widget.
After a library has been created you can right click it and select to "Add new component".
__Note__ This functionality was previously present in the separate HoLC (Hopsan Library Creator) application, but this application should now be considered deprecated. Using the functional build into HopsanGUI is recommended.

In this dialog it is possible to specify component name (used by simulation core, must not contain spaces), display name (shown in graphical interface) and component type (C,Q or S - see the \ref userTransmissionLineModelingMethodPage "transmission line element method"). It is also possible to add ports, parameters, utility functions and static variables. Finally, the code for the component can be written in two ways, either directly from C++ code, or from algebraic equations using a subset of the Modelica language.
In this dialog it is possible to specify component type (used by simulation core, must be unique not contain spaces), display name (shown in graphical interface) and component type (C,Q or S - see the \ref userTransmissionLineModelingMethodPage "transmission line element method"). It is also possible to add ports, parameters, utility functions and static variables. Finally, the code for the component can be written in two ways, either directly from C++ code, or from algebraic equations using a subset of the Modelica language.

When writing C++ code, there are three functions available: Initialize, SimulateOneTimeStep and Finalize. Initialize runs before the first time step of the simulation, SimulateOneTimeStep runs every time step, and finalize runs after the simulation is finished. Available and sought parameters are displayed above the code boxes. When clicking compile, the component will be converted to Hopsan interface syntax and compiled to an external library.

The other option is to use equations. This function is currently an experimental feature, and full functionality is not guaranteed. Equation-based modeling has several advantages over plain code modeling. It allows equations written in arbitrary ways, i.e. more than one variable on the left side. Equations can also be written in any order, as long as the number of equations equals the number of unknown variables. The language used is a subset of Modelica. It allows most basic functionality in the equation section. There is also an algorithm section, that will be executed prior to the equation solver each time step. This section does not support all Modelica algorithm functionality, and is basically intended only for defining explicit expressions that does not need to be part of the equation system. When compiling, a symbolic Jacobian matrix is generated and displayed in a popup window. This is then transformed to Hopsan syntax, together with a fixed-step equation system solver.

Generated components are loaded automatically into a "Generated Component" library.

\section generating-components-mathematica Generating Components From Mathematica
This feature is not implemented in the current version of Hopsan. In future releases it will be possible to automatically generate components from equations in Mathematica.
To be able to use the created components, you must have the Hopsan version with a compiler included or have configured Hopsan to use the system compiler (must be compatible, same used to build Hopsan).
*/

/*!
\page userUnitTestModelsAndComponentsPage Model and Component Unit-Testing
\page userUnitTestModelsAndComponentsPage Model and Component Regression Testing
When you have finished a component and/or model and you are satisfied with the simulation results you can save you model and some of the simulation results as a test model.
You can later run this model again and automatically compare the simulation results.
This is very important if you want to make sure that your component and models do not change their behaviour when new versions of Hopsan are released.
__Remember__ that you can not make any more changes (that affect simulation results) to the model file if you want the validation to match.
__Remember__ that if you want to make new changes (that affect simulation results) in the modeled component, your validation data must be recreated.

\section userUnitTestModelsAndComponentsPage-components_howtocreateCLI How to Create a Validation Model in Hopsan CLI
The HopsanCLI can automatically create a validation data set based on all scopes in your model. If no scopes are available, no data set will be created.
Expand Down
16 changes: 6 additions & 10 deletions doc/userSetupLibraryDevelopmentEnvironment.dox
Original file line number Diff line number Diff line change
Expand Up @@ -2,26 +2,22 @@
\page page_setuplibrarydevelopmentenvironment How to setup the component library development environment

To create your own Hopsan components (writing them as C++ code) you need to install the necessary compiler but you can use whatever code (text) editor that you want.
An alternative is to use the full Hopsan development environment, including compiler and IDE.
You can choose to use the built in code editor inside HopsanGUI, it offers basic code editing functionality.
An alternative is to use a full-fledged external C++ IDE.
This guide describes the first simpler option.

You only need to install the compiler if:
- You want to (re)compile component libraries that are already written.
- You want to write a small library with only a few simple components.
- You are not interested in debugging the code during simulation.
- You want to use some external automatic code generation tool or the HoLC (Hopsan Library Creator) program.
- You only want to use import/export features in Hopsan that require require a compiler (FMI requires this).

If you want to write a lot of new/advanced code yourself and use the debugger, then it is recommended that you install the full development environment.
If you choose this approach, then follow the instructions on the \ref page_setupbuildenvironment page.
__You only need to install the Qt Creator IDE and the Qt libraries.__ The external build tools may only be necessary if you want to recompile Hopsan itself.
If you want to write a lot of new/advanced code yourself and use the debugger, then it is recommended that you install a full development environment.


\section sec_installcompileronly_windows Installing the compiler only, on Microsoft Windows
<b>Installing the compiler for 64-bit Hopsan 0.7.*:</b>
-# You may need to install the 7-Zip program from http://www.7-zip.org to unpack the needed files.
-# Download "x86_64-4.9.3-release-posix-seh-rt_v4-rev1.7z" from http://sourceforge.net/projects/mingw-w64/files/Toolchains%20targetting%20Win64/Personal%20Builds/mingw-builds/4.9.3/threads-posix/seh/x86_64-4.9.3-release-posix-seh-rt_v4-rev1.7z
-# Unpack to a directory of your choice, _Example:_ `C:\Qt\x86_64-4.9.3-release-posix-seh-rt_v4-rev1`
-# In the HopsanGUI options, choose the path to the compiler, _Example:_ `C:\Qt\x86_64-4.9.3-release-posix-seh-rt_v4-rev1\mingw64\bin`
Download the version of Hopsan that comes with the compiler included to ensure that you get the correct version.
The compiler will be located in the mingw or mingw64 sub directories of the Hopsan installation.

\section sec_installcompileronly_linux Installing the compiler only, on GNU/Linux (*Ubuntu or Debian based systems)
Install the compiler (GCC) and other tools from you package repository using: `sudo apt-get install build-essential`
Expand Down

0 comments on commit c87d1b3

Please sign in to comment.