Adding a new model

This is still a proposal under construction and should not be actively followed yet

This page contains information on how to add new models to the library:

• Think and plan what you want to do
• Search for previous work
• Inform your colleagues on what you plan to do
• Follow best practices when writing your model

Introduction

Before writing the first line of code, always start with these 3 steps

1. think and plan what you want to do (and don't forget why you want to do it)
2. search for previous work (you may not need to do it after all)
3. inform your colleagues on what you plan to do (they will be happy to help and learn)

This is a bit of extra work, but we agree with the following part from the GitLab Handbook:

If it is worth spending time on, it is worth creating an issue for it since that enables other people to learn and help.

And it will give you a better foundation to spend your time on the right tasks and create great work.

Once you have gone through this preparation process, you can finally start working on your model.

Think and plan what you want to do

At least take a minute to answer the following questions for yourself:

• What is your problem?
• Why do you want to solve it?
• How do you want to solve it?
• Who do you think can help you?
• Who do you think will benefit from your solution?

Search for previous work

It is possible that the model you plan to write already exists, could re-use parts of other models or has at least been dreamed about by someone else. Therefore, build on others' work and take a minute to do some research before writing your own code.

You can start your research here:

• The AixLib issue tracker documents all of our work. And it has a search bar above the issue descriptions. Use the search to find any previous work on your topic. For this, do not only filter for open issues, but have a look at the closed ones, too.
• It is possible that AixLib contains a model from the Modelica IBPSA Library or from the times before we made good use of the issue tracker. Therefore, also search the library for models that may help you. You can use the search bar on the very top of the AixLib repository page. Also Dymola and OpenModelica have their own search functions. In any case, it is a very good idea to familiarize yourself with AixLib before you start writing your own models. This is not only for models you may directly use, but you also can see some modeling patterns to help you along in other models.
• Just as you should be familiar with AixLib, you should be familiar with the Modelica Standard Library and search there for any models you may be able to re-use.
• In addition, there are many great libraries for modeling building and community energy systems. Especially Buildings, IDEAS and BuildingSystems. Make sure to also search these libraries for models and inspiration.

Inform your colleagues on what you plan to do

Our vision is to use the AixLib issue tracker as the central platform to communicate about all our work. Therefore, use it to inform everyone about your plans before you write the first line of code. Your goal should be to inform everyone who can help you, join the development to learn together and who may re-use your model in the future. Therefore, please do not use 1-line descriptions such as "Add new building model". Instead, try to briefly answer all the questions from the "Think and plan what you want to do"-section for anyone who reads your description. Again, these questions are:

• What is your problem?
• Why do you want to solve it?
• How do you want to solve it?
• Who do you think can help you?
• Who do you think will benefit from your solution?

In addition, it is great if you can quickly summarize the results of your search for previous work.

Follow best practices when writing your model

At this point, we assume you have thought about what and why you want to model, you know the existing models that can help you, you have informed everyone about your plans, and received their feedback and input.

Now it's time to actually start modeling. During this process, please keep the following things in mind:

• Make sure to follow our Modelica Guidelines, especially the naming conventions for your variables
• Please document every model according to our Documentation guidelines
• Whenever possible, do provide an example model to demonstrate that your new development works as intended. The documentation of the example should include all the information any other person would need to check if the model runs correctly (i.e. What are you trying to show? How should the model behave? What result variables are interesting?...).
• Regarding your Git workflow: Commit often, write good commit messages, and make the smallest pull requests possible. If you develop a large package, it is much appreciated to make multiple pull requests along the way. The faster we can review a pull request, the better.