# HintCO - Hint-based Configuration of Co-simulations

This framework is a automated co-simulation program which is based on hints.
The co-simulation user defines some hints in the framework, and then the framework automatically tries to find the best master algorithm to satisfy the user's hints.
It runs numerous simulations, using the past results to improve the next simulation with a new master algorithm.  

## Download

The latest precompiled binaries for Windows are available for download in the releases.

For Linux and Windows platforms, see [Getting Started in Development](#getting-started-in-development).

## Usage Instructions

There are two main tasks in running a co-simulation with HintCO:

1. Configure a co-simulation scenario file. This is an XML file that can be easily edited with Eclipse and the editor plugin shipped with HintCO.
2. Compute the co-simulation results.

#### Configuring Co-simulation Scenarios

Co-simulation scenario are just XML files. See [watertanks.xmi](HintCOEngine/examples/watertanks.xmi) for an example.

HintCO provides EMF Editor Plugins to edit such files. To use them, setup the development environment and export the editor jars (see the instructions below). Then, place the exported `HintCO.edit_*.jar` and `HintCO.editor_*.jar` files into the `plugins` folder of an Eclipse Modelling Tools distribution (Photon Release 4.8.0).

#### Running Co-simulations

HintCO provides some example co-simulations. The scenario files are available in the [example](HintCOEngine/examples) directory and the FMUs are available in the [resources](HintCOEngine/resources) directory.

If `hintco` denotes the HintCO binary, then run

```
hintco -s .\examples\watertanks.xmi -o output -n 1
```

Where `.\examples\watertanks.xmi` can be found in  [examples](HintCOEngine/examples), and `output` is where the results will be generated.
The fmus are assumed to be in a `resources` folder, in the same directory as the binary `hintco`.
A helper script under [scripts](HintCOEngine/scripts) is provided, to create pdfs for the plots produced:

```
python plot_results.py ./output/0_1
```

To get help on the API:

```
hintco -h
```

## Getting Started in Development

These instructions will get you a copy of the project up and running on your local machine for development and testing purposes.

### Prerequisites

Windows/Linux platform.

### IDE Configuration

To setup the framework, you need follow these steps:

1. Install Eclipse ModelingTools.
	Version: Photon Release (4.8.0)
	For the below dependencies, use 'Install new software' in Help tab of eclipse.
2. Work with repository: `Photon - http://download.eclipse.org/releases/photon`
3. Install "Modeling → EMF - Eclipse Modeling Framework Xcore SDK"
4. Install "Modeling → Xpand SDK"
5. Install "Modeling → Xtext Complete SDK"
6. Import the HintCO repository as an eclipse "Existing Project".



### Exporting the HintCO Binary

Exporting the HintCO binary is performed in Eclipse.

1. Use Eclipse to open the [HintCOEngine/HintCO.product](HintCOEngine/HintCO.product) file.
2. Ensure that the *Overview* tab is selected.
3. On the right-hand side of the tab, under the *Exporting* headline, click the *Eclipse Product export wizard* link.
4. Set the destination directory where the binary will be exported to.
5. Select *Finish*.

### Exporting the Editor Plugins

Exporting the editor plugins is performed in Eclipse.

1. Use Eclipse to open the [HintConfiguration.edit/plugin.xml](HintConfiguration.edit/plugin.xml) file.
2. Ensure that the *Overview* tab is selected.
3. On the right-hand side of the tab, under the *Exporting* headline and on the line starting with *4.*, click the *Export Wizard* link.
4. Set the destination directory where the plugin jar will be exported to.
5. Select *Finish*.
6. Repeat the above steps for the [HintConfiguration.editor/plugin.xml](HintConfiguration.editor/plugin.xml) and [HintConfiguration/plugin.xml](HintConfiguration/plugin.xml) files.

### Deploying the Editor Plugins

1. Take the jar files generated in [Exporting the Editor Plugins](#exporting-the-editor-plugins) and move them to the eclipse *dropins* folder. Make sure the eclipse distribution is equivalent to the distribution used in [IDE Configuration](#ide-configuration).

## Contributing

Please read [CONTRIBUTING.md](https://msdl.uantwerpen.be/git/claudio/HintCO/src/master/CONTRIBUTING.md) for details on our code of conduct, and the process for submitting pull requests to us.

## Versioning

We use [SemVer](http://semver.org/) for versioning. For the versions available, see the [tags on this repository](https://msdl.uantwerpen.be/git/claudio/HintCO/tags).

## License

This project is licensed under the MIT License - see the [LICENSE.md](LICENSE) file for details

## Paper

If you use HintCO, please cite our paper.

Gomes, C.; Oakes, B.; Moradi, M.; Gámiz, A.; Mendo, J.; Dutré, S.; Denil, J. and Vangheluwe, H. (2019). HintCO – Hint-based Configuration of Co-simulations.In Proceedings of the 9th International Conference on Simulation and Modeling Methodologies, Technologies and Applications - Volume 1: SIMULTECH, ISBN 978-989-758-381-0, pages 57-68. DOI: 10.5220/0007830000570068.
```
@conference{simultech19,
author={Cláudio Gomes. and Bentley James Oakes. and Mehrdad Moradi. and Alejandro Torres Gámiz. and Juan Carlos Mendo. and Stefan Dutré. and Joachim Denil. and Hans Vangheluwe.},
title={HintCO – Hint-based Configuration of Co-simulations},
booktitle={Proceedings of the 9th International Conference on Simulation and Modeling Methodologies, Technologies and Applications - Volume 1: SIMULTECH,},
year={2019},
pages={57-68},
publisher={SciTePress},
organization={INSTICC},
doi={10.5220/0007830000570068},
isbn={978-989-758-381-0},
}
```
