GI in No Time - a Simple Microframework for Genetic Improvement
Switch branches/tags
Nothing to show
Clone or download
Latest commit bd258bd Sep 4, 2018

README.md

Build Status

Notice! Under Development (4th Sept 2018)

Currently the Gin team are working on an extensive update to Gin. We've introduced a ton of new features, and the banner headline is: Gin now works on industrial-scale projects. As the work has involved such large scale modifications, we're working in a private fork. We expect this fork to be released to the public repo before the end of 2018.

Gin: Genetic Improvement in No Time

This is the repository for the academic research paper "Genetic Improvement in No Time", submitted to the GI 2017 workshop at GECCO 2017. Please see this preprint of the paper.

Gin is a Genetic Improvement (GI) tool. Genetic Improvement is the application of Genetic Programming and other metaheuristics to existing software, to improve it in some way. In its initial incarnation, Gin was designed to reduce the execution time of Java code by modifying source files whilst preserving functionality as embodied by a set of JUnit tests.

This repository was created based on a private development repo and is still undergoing development. Please raise an issue if you have a specific request or notice a bug.

The Gin Design Philosophy

The goal of Gin is to stimulate development in GI tooling, and to lower the barrier to experimenting with GI and related ideas such as program fragility.

With this in mind, it was written in Java and targets Java, a language almost univerally familiar to GI researchers. It also mostly avoids functional constructs and similar in Java. In fact, the code is in parts stupidly simple, in that design patterns and good practice are sacrificed in the name of brevity, simplicity, and readability. It is not designed to be an elegant or general solution, but to be easily understood and modified.

In order to reduce Gin's footprint, we rely on the JavaParser and JUnit libraries in order to parse and test the code under optimisation, respectively.

Getting Started

These instructions will show you how to build gin and run a simple local search on the example program. Gin is designed to be hacked rather than used as a library, so there is no "API" in the traditional sense, you should just modify the code.

Prerequisites

Gin requires:

  • JDK 1.8.x
  • Gradle (tested with version 3.3)
  • A number of dependencies, which can be downloaded manually or via Gradle (recommended)

JDK downloads:http://www.oracle.com/technetwork/java/javase/downloads/index.html

Gradle can be downloaded from their website:https://gradle.org/install

The library dependencies can be found in the build.gradle file. Here's a list correct at the time of updating this README:

Installing and Building gin

These instructions were tested on OS X.

Clone the repo:

git clone https://github.com/gintool/gin

Build using gradle (alternatively import into your favourite IDE, such as IntelliJ)

cd gin
gradle build

If you want to run gin from the commandline, you may want to build a fat jar to avoid having to explicitly include all the depencies in your classpath:

gradle shadowJar

This will create a fat jar at build/gin.jar.

If you want to use gin with an IDE, it can be useful to have all the depencies in a top-level directory:

gradle copyToLib

This will place all dependencies in the top-level lib directory.

Running a Simple Example

If you build the far jar as above, you can run gin on a simple example with:

java -jar build/gin.jar examples/Triangle.java

Your output will be similar to the following:

Optimising source file: examples/Triangle.java

Initial execution time: 1.66700594275E9 (ns) 

Step 1 | COPY 27 -> 4:0 |Failed to compile
Step 2 | MOVE 32 -> 4:0 |Patch invalid
Step 3 | COPY 0 -> 6:0 |Failed to compile
Step 4 | COPY 21 -> 1:2 |Failed to compile
Step 5 | MOVE 21 -> 3:0 |Patch invalid
Step 6 | DEL 10 |Failed to pass all tests
Step 7 | DEL 29 |*** New best *** Time: 2679060.0(ns)
Step 8 |Time: 1.653746228E9
.
.
.
Step 100 | DEL 29 | COPY 2 -> 9:0 | COPY 21 -> 4:0 |Failed to compile

Best patch found: | DEL 29 | COPY 2 -> 9:0 |
Found at step: 72
Best execution time: 1549250.0 (ns) 
Speedup (%): 99.91 

The output tells you for each step whether a patch was invalid (e.g. because it could not be applied) or whether the patched code failed to compile or it failed to pass all provided tests. If none of these conditions hold, then the runtime is shown, and it is highlighted if the patch has resulted in the fastest successful passing of all tests seen so far. At the end, a brief summary is shown.

Analysing Patches

Gin provides a simple tool called PatchAnalyser, which will run a patch specified as a commandline argument and report execution time improvement, as well as dumping out annotated source files indicating statement numbering etc.

Running Unit Tests

gradle test

Contributing

As Gin is still very much in an early stage of development, no process is yet in place for contribution. Please feel free to open issues and submit pull requests. If you'd like to aid in the development of Gin more generally, please get in touch.

License

This project is licensed under the MIT License. Please see the LICENSE.md file for details