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¶
Once the 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 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. abd123 is a preferable folder name, whereas 123$@ 123 is not. Detailed information regarding the datasets and the EPOS input is found at Input.
In the conf folder, the configuration files that parametrize the execution of the epos-tutorial.jar can be found. The files log4j.properties, measurement.conf and protopeer.conf are relevant to the EPOS runtime parameters and usually do not need to be changed. The epos.properties file is Java properties file with the format key=value for each line. Extensive documentation and explanation regarding the configurations can be found at Configuration Parameters.
The executable epos-tutorial.jar can be run via the following commands:
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 log folder contains debug logs produced from log4j. For stable releases, the debug logs are expected to be an empty file.
The 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 dataset-name_timestamp format. The results are produced from the EPOS loggers that are explained at Logging & Output.
Example run¶
After downloading, extracting and entering the release, an example command line run can be done as follows:
> 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 release-x.x.x/conf/epos.properties, which are extensively analysed at Configuration Parameters. Please check Each .csv file is generated by the EPOS loggers, which are explained at Logging & Output.
IDE Setup¶
To download and use the EPOS source code, the following command line steps are recommended:
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 conf, datasets, log and output have the same contents and utility as the one described at Command-Line Setup. The files pom.xml and dependency-reduced-pom.xml are relevant to Maven and handle the dependencies of EPOS. The target folder contains the EPOS .jar executable and the compiled java classes generated by Maven. To regenerate the executable a new Maven build is recommended by rerunning the mvn clean install -U command. Finally, the project source code is found under the src folder. The subfolder path src/main/java contains the Java source code. The subfolder src/main/resources contains the protopeer related libraries as .jar packages. Any new resource files can be put there. Under the 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 mvn clean install -U successfully finishes, the project can be opened via your IDE of choice as a Maven project. Common mistakes involve opening the project as a 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 experiment package, can reproduce the behavior of the EPOS executable at Command-Line Setup. Detailed information on the code and possible extensions can be found at Input, Global Cost Function, Local Cost Function, Tree Topology, Termination Criteria and Advanced Topics.