.. _experimental-setup: ===================================== Initial Setup and Running Experiments ===================================== Here you may find useful information for setting up and running EPOS. EPOS can be either run via command line or as source code via an IDE. Information regarding those setups can be be found below: .. _command-line-setup: Command-Line Setup ------------------ Once the :code:`release-x.x.x.zip` is unpacked, then a folder with the following structure is generated: :: release-x.x.x ├── conf │   ├── epos.properties │   ├── log4j.properties │   ├── measurement.conf │   └── protopeer.conf ├── datasets │   └── dataset_name │   ├── agent_0.plans │   ├── agent_1.plans │   ├── agent_2.plans │   ├── agent_3.plans │   ├── agent_4.plans │   ├── agent_5.plans │   ├── agent_6.plans │   ├── agent_7.plans │   ├── agent_8.plans │   ├── agent_9.plans │   ├── agent_10.plans │   └── goal.target ├── epos-tutorial.jar In the :code:`datasets` folder, we can find the datasets that EPOS will operate on during execution. Each dataset folder should be named with alphanumeric characters and have no spaces or special characters in its name. E.g. :code:`abd123` is a preferable folder name, whereas :code:`123$@ 123` is not. Detailed information regarding the datasets and the EPOS input is found at :ref:`input-chapter`. In the :code:`conf` folder, the configuration files that parametrize the execution of the :code:`epos-tutorial.jar` can be found. The files :code:`log4j.properties`, :code:`measurement.conf` and :code:`protopeer.conf` are relevant to the EPOS runtime parameters and usually do not need to be changed. The :code:`epos.properties` file is Java properties file with the format :code:`key=value` for each line. Extensive documentation and explanation regarding the configurations can be found at :ref:`arguments-chapter`. The executable :code:`epos-tutorial.jar` can be run via the following commands: .. code-block:: console java –jar epos-tutorial.jar #default configuration in conf/epos.properties java –jar epos-tutorial.jar “path/to/conf” #configuration loaded from specific file After executing the Jar for the first time the release folder has the following format: :: release-x.x.x ├── conf ├── datasets │   └── gaussian ├── epos-tutorial.jar ├── log │   └── debug.log └── output └── gaussian_1539678828 ├── global-complex-cost.csv ├── global-cost.csv ├── global-response.csv ├── indexes-histogram.csv ├── local-cost.csv ├── num-reorganizations.csv ├── selected-plans.csv ├── termination.csv ├── unfairness.csv ├── used_conf.txt └── weights-alpha-beta.csv The :code:`log` folder contains debug logs produced from :code:`log4j`. For stable releases, the debug logs are expected to be an empty file. The :code:`output` folder contains the results after running EPOS for a dataset. Each time EPOS is run, then the results are stored under a subfolder with :code:`dataset-name_timestamp` format. The results are produced from the EPOS loggers that are explained at :ref:`logging-chapter`. Example run ^^^^^^^^^^^ After downloading, extracting and entering the release, an example command line run can be done as follows: .. code-block:: console > release-0.0.1 user$ ls #this will use the conf/epos.properties configuration conf datasets epos-tutorial.jar > release-0.0.1 user$ java –jar epos-tutorial.jar WARNING or INFO logs about config loading … Current config … Simulation 1 IEPOS Finished! It took: 0 seconds. > release-0.0.1 user$ ls conf datasets epos-tutorial.jar log output > release-0.0.1 user$ cd output > release-0.0.1 user$ ls gaussian_1538679318 > release-0.0.1 user$ cd gaussian_1538679318 > release-0.0.1 user$ ls #check the output of the current run global-complex-cost.csv local-cost.csv unfairness.csv global-cost.csv num-reorganizations.csv used_conf.txt global-response.csv selected-plans.csv weights-alpha-beta.csv indexes-histogram.csv termination.csv The above example run uses the properties found in the default configuration :code:`release-x.x.x/conf/epos.properties`, which are extensively analysed at :ref:`arguments-chapter`. Please check Each :code:`.csv` file is generated by the EPOS loggers, which are explained at :ref:`logging-chapter`. .. _ide-setup: IDE Setup --------- To download and use the EPOS source code, the following command line steps are recommended: .. code-block:: console git clone -b tutorial --single-branch https://github.com/epournaras/EPOS cd EPOS mvn clean install –U #or where the project pom.xml is The resulting folder structure is expected to look like: :: EPOS ├── conf ├── datasets ├── dependency-reduced-pom.xml ├── license.txt ├── log ├── output ├── pom.xml ├── src │   ├── main │   │ ├── java │   │ └── resources │   └── test │   ├── java │   └── resources └──target The folders :code:`conf`, :code:`datasets`, :code:`log` and :code:`output` have the same contents and utility as the one described at :ref:`command-line-setup`. The files :code:`pom.xml` and :code:`dependency-reduced-pom.xml` are relevant to Maven and handle the dependencies of EPOS. The :code:`target` folder contains the EPOS :code:`.jar` executable and the compiled java classes generated by Maven. To regenerate the executable a new Maven build is recommended by rerunning the :code:`mvn clean install -U` command. Finally, the project source code is found under the :code:`src` folder. The subfolder path :code:`src/main/java` contains the Java source code. The subfolder :code:`src/main/resources` contains the protopeer related libraries as :code:`.jar` packages. Any new resource files can be put there. Under the :code:`src/test` folder the test classes and resources can be found. More regarding the source code organization and its relation to Maven builds can be found `here `_. Once the :code:`mvn clean install -U` successfully finishes, the project can be opened via your IDE of choice as a :code:`Maven project`. Common mistakes involve opening the project as a :code:`Java project` instead. In that case the IDE will not be able to open the project. In that case please delete the project for your IDE and remove any IDE related files and folders before trying to reimport it. A special version or an update to the IDE plugins might be required to use Maven, e.g. `for Eclipse `_. Running the project experiment classes found under the :code:`experiment` package, can reproduce the behavior of the EPOS executable at :ref:`command-line-setup`. Detailed information on the code and possible extensions can be found at :ref:`input-chapter`, :ref:`global-cost-function-chapter`, :ref:`local-cost-function-chapter`, :ref:`tree-topology-chapter`, :ref:`termination-criteria-chapter` and :ref:`advanced-topics-chapter`.