Implementing a Desktop Compiler Optimization

We have an existing ticket to implement the desktop compiler's optimizations in Tortoise. This is a brief overview on the process to follow to implement one of them.

For reference, a few example optimizations that have been done already and can be used as reference include "Nsums", "Nsums4", and "OtherWith".

Process

We assume we want to implement the "AnyWith1" optimization in this process, as an example.

• Make sure to understand what you're testing in NetLogo code. A lot of these optimizations take combinations of primitives that can be more efficient when they're processed together.
  • Like any? turtles with [ color = red ] would normally run turtles with [ color = red ] creating an agent set of red turtles followed by an any? check on that result, but they can be combined to save some time by reporting true when the first turtle with the condition is found.
• Create a simple language test for it in Tortoise.txt in Tortoise so you can quickly test it using netLogoWeb/testOnly *Commands -- -z Tortoise using the sbt console.
  • This is just a fast, easy-to-run test for implementation purposes, it shouldn't be checked in with any commits.
• Add the optimization in the proper DockingFixtures.scala section (Command or Reporter), matched against the NetLogo repo Optimizations.scala, so it'll be used in all other tests, too.
• Find the optimized prim version in the NetLogo repository. This will be the logic we'd like to duplicate.
  • Example: The _anywith class in _anywith.scala. But make sure to look at the version from headless and not netlogo-gui.
• In Tortoise, add the matching prim in Prims.scala.
  • This is where the compiled prim is translated into the CoffeeScript code that will actually be run by the engine.
  • After adding the prim, you should re-run your quick Tortoise.txt test and confirm it fails - the optimization is seen, but you haven't implemented the functionality yet so it breaks. If the test passes, something may not be right.
• In Tortoise, add the optimized code in the appropriate place in the engine, depending on the prim and optimization.
  • For _anywith, this applies to agent sets, so we'd look to an agent set class to implement it.
• Run tests, work on it until it passes.
• Run a broader set of tests (netLogoWeb/test:fast and netLogoWeb/test *Reporters are good ones), make sure they all still pass.
• Publish the Tortoise artifacts locally and use them in Galapagos to test a model using the now optimized primitives. You should be able to use a web developer console to actually step through your optimized code.

Optimizations

* means already implemented.

• AnyOther*
• AnyOtherWith
• AnyWith1
• AnyWith2
• AnyWith3
• AnyWith4
• AnyWith5
• CountOther*
• CountOtherWith
• CountWith*
• Nsum*
• Nsum4*
• OneOfWith*
• OtherWith*
• PatchAt
• RandomConst
• With*
• WithOther*