Simulationcraft Automation Tutorial – Part II

In the last post, we went over the interface of the Automation Tool and demonstrated how to use it to perform simple talent, glyph, and gear comparisons. Today we’re going to dive into the last comparison type: Rotations.

This comparison type is really the highlight of the tool. While the other comparison types are neat, this one is amazing. It’s an incredibly powerful way to test different rotations against one another, though of course, with that power comes some added complexity.

Interface

First, let’s take a look at how the interface changes when we choose “Rotation” from the Comparison Type drop-down box.

The Rotation Comparison Interface.

The first thing you’ll notice is that everything is enabled. This mode uses all of the text boxes. Though you’ll notice that the “Default Rotation” text box has been renamed “Actions Header,” and the previously-unused box in the lower left is now the “Actions Footer” box. We’ll talk about what those do shortly. The center box is now renamed the “Rotation Configurations” box, and the right-hand-side Rotation Abbreviations box is now editable.

I want to draw your attention to the text in the Rotation Configurations box though. It may look peculiar to you unless you’ve read some of my earlier MATLAB work, like the 5.4.2 Rotation Analysis. If you have read that post (or others like it), you might recognize these as rotation shorthands:

Shorthand configurations.

Shorthand rotation configurations.

The first one is equivalent to a rotation where your priority order is Crusader Strike, then Judgment, then Avenger’s Shield. When we hit Import!, it translates this to an actor with that action priority list:

The generated actor for CS>J>AS

The generated actor for CS>J>AS

How does it know that CS means crusader_strike and so on? That’s what the Rotation Abbreviations sidebar is for. So let’s look at that in more depth.

Abilities

The Rotation Abbreviations sidebar defines all of the shorthands and their longhand equivalents. It’s essentially the dictionary the tool uses to try and make sense of the input you give it. It’s divided into sections by headings marked with six colons, the first of which is “:::Abilities, Buffs, Glyphs, and Talents:::” as shown below.

The shorthand definitions are in the Rotation Abbreviations sidebar.

The Abilities section of the Rotation Abbreviations sidebar.

As you can see, we’ve defined shorthands for a bunch of different abilities using the syntax:

shorthand=longhand

When you hit Import! the tool’s shorthand decoder takes the shorthand you give it and checks each ability against the shorthand side of each line of this section. If it finds one, it replaces that text with the longhand version. So for example, it searches for”CS” in this section, finds the “CS=crusader_strike” entry, and then creates an action priority list line for crusader_strike. As you can see in the example above, we use the greater than sign (>) in the shorthand to indicate a new line on the action priority list. So “CS>J>AS” becomes a three-line action priority list with crusader_strike, judgment, and avengers_shield.

This section also contains the definitions for particular buffs, glyphs, or talents. We’ll see how they get used a little later on, for now don’t worry about them.

Note that this text box is editable, meaning you can define your own shorthands if you want to. If you really want to use “Co” instead of “Cons” to represent consecration, you can change it! Likewise, if you want to add abilities (or buffs, glyphs, or talents) that aren’t already on the list, you can add new definitions by typing them into this section. Some specs already have a bunch of built-in shorthands written by SimC devs for that class. If your spec doesn’t, see the end of this post for information on how you can submit a list.

The shorthand syntax is much more powerful than just allowing you to define strings of abilities though. Most action priority lists use conditionals, so the tool has a way to let you do that in shorthand as well.

Options

The second actor uses the shorthand “CS>J>AS+GC” to demonstrate the use of options. If you look further down the Rotation Abbreviations sidebar, you’ll see a section labeled “Options”:

The Options section of the sidebar.

On this list you can see that we’ve defined an option “GC=buff.grand_crusader.react.” The tool uses the plus sign (+) as the indicator that you’re trying to specify an option, which is just a conditional for the use of that ability. The syntax “Ability+Option” translates into “ability,if=option” during the decoding process. Thus, “AS+GC” translates to “avengers_shield,if=buff.grand_crusader.react.”

The final example just shows that you can combine different options with logical operators, just like you can with conditionals in action priority lists. The entry

AS+GC&(DP|!FW)

translates to

actions+=/avengers_shield,if=buff.grand_crusader.react&(buff.divine_purpose.react|!glyph.final_wrath.enabled&target.health.pct<=20)

Obviously this is a nonsense conditional, it’s just there to demonstrate the flexibility you have with the system. With appropriate ability and option definitions, you can create almost any action priority list you can dream of here. One word of warning, however: note that while you can use logical operators like &|+-*/<=(), you cannot use >, because the decoder thinks that’s you telling it you’re starting a new action priority list line.

One way around that limitation is to use the pound sign (#), which is a special character definition in options. For example, the option

HP#=holy_power>=#

lets you specify an option like “HP3″ that will translate to “holy_power>=3″. The # sign will match any number including decimals, so it would properly translate HP3.2 into “holy_power>=3.2″. This should let you get around the limitation of not being able to use the greater than symbol in a logical expression.

There’s another special sequence for options that can be useful when an option depends on the ability it’s modifying. In an option, the text “$ability” will be replaced with the name of the current ability. So for example, since we have the definition “AC#=action.$ability.charges>=#”, a line like “AS+AC1″ would translate to

avengers_shield,if=action.avengers_shield.charges>=1.

Obviously this is nonsense since Avenger’s Shield doesn’t have charges, but this could be useful for abilities that do, like Shield Block.

Operators

The third section of the Rotation Abbreviations sidebar is called “Operators,” and it defines abbreviations that allow for more flexible creation of operators. An operator requires an additional abbreviation which it acts upon, called the “operand.” The syntax for this is “Operand.Operator”, like so:

GC.BA

When the decoder encounters the syntax “X.Y”, it checks for X in the list of Ability shorthands and checks for Y in the list of Operator shorthands. If it finds both, it will replace “X.Y” with the operator longhand, and then look for the text “$operand” in the result, replacing any instances of that text with the longhand form of the ability.

The list of operators.

The list of operators.

In our example, the ability list contains “GC=grand_crusader” and the operator list has “BA=buff.$operand.react.” So the decoder will first replace “GC.BA” with “buff.$operand.react”, and then replace the “$operand” in that with “grand_crusader.” The final result is

buff.grand_crusader.react.

You might wonder why we would want to use an operator when we can just define an option to handle the entire conditional expression. The answer is primarily one of flexibility. The “.BA” operator lets us test for a buff with any abbreviation we’ve already defined in the Abilities section. Likewise, the “.CD” operator, we can check the cooldown of any of those abilities. By using  operators, we don’t need to define a new option for each cooldown, buff, or debuff that we want to check for.

Operator/operand pairs like “GC.BA” or “CS.CD” are just special types of options, so just like other options they can be combined using logical operations. The decoder will properly parse “AS+GC.BA&CS.CD0.5&E” as

avengers_shield,if=buff.grand_crusader.react&cooldown.crusader_strike.remains>=0.5&target.health.pct<=20

Just as with abilities and options, you can define your own operators by adding them to the appropriate section of the sidebar. There are a few things to keep in mind when defining your own shorthands in any of the three sections.

  • Shorthands are all case-insensitive, so if you define “AS=avengers_shield” both “AS” and “as” will be matched and converted by the decoder. This means you can’t use “AS,” “As,” and “as” to stand for different abilities.
  • Each section of the sidebar is independent. So you can define
    • “AS=avengers_shield” in the “:::Abilities:::” section,
    • “AS=cooldown.avengers_shield.remains” in the “:::Options:::” section, and
    • “AS=action.$operand.charges” in the “:::Operators:::” section

    and the decoder will be smart enough to use the appropriate one based on syntax. So “AS+AS&AS.AS” would parse just fine.

  • The Rotation Abbreviations sidebar is saved when you exit the program, so if you add shorthands they will be there when you start the program up again. However, the sidebar is completely reset every time you choose a new class or spec from the drop down boxes, and your changes will be discarded. This is done partly because it’s far easier than saving the text of the sidebar separately for each class, and partly to make it easy for me to add abbreviations in the future. If there’s a shorthand abbreviation you feel should be added to a spec’s defaults, please contact me (here or via an issue ticket) and I’ll add it to the list.
  • The one thing you should absolutely not do is change the section labels in the sidebar. The code uses the “:::stuff:::” pattern to separate the sidebar into three separate tables of shorthand/longhand pairs, which it then uses to perform the replacement. If you delete one of the colons, the program will probably crash when you hit the Import! button.

Now that we have all the shorthand pieces, let’s see how we use the tool to perform a simple rotation comparison.

Using The Rotation Comparison Tool

For our first foray into rotation comparisons, we’re going to stick to something simple. Let’s test the ideal priority of our holy power generators: CS, J, and AS+GC. With only three abilities, there are six different permutations we could consider:

 

Our first rotation comparison.

Our first rotation comparison.

When we hit Import!, we get a list of six actors, each of which has the appropriate action priority list entries.

The generated profile.

The generated profile.

You’ll note that the rotation comparison automatically gives each of these actors a name based on the shorthand you provide. You can override this automatic naming by providing your own as an option, just as we did in the earlier comparisons. For example, changing the first line to “CS>J>AS+GC name=Alice” will add a “name=Alice” line to the end of the profile which will overwrite the automatically-generated name.

If we run the simulation, we again get a report like before, showing how each actor performed:

Report for Rotation Comparison #1

The resulting report.

The resulting rotation comparison report.

Since we’re only running this with 1000 iterations, the error is about 10 DPS, so the rankings aren’t all that conclusive. In fact, there’s a much more glaring error in these results that would call their validity in question, which we’ll discuss in more detail shortly. However, it’s clear from this example how you might go about comparing different rotations. And note that just as we did with the earlier comparisons, we can tweak the talents, glyphs, or gear of any actor by adding commands after the shorthand, like so:

CS>J>AS+GC name=Alice talents=1111111 glyphs=alabaster_shield
CS>AS+GC>J name=Bob talents=2222222 glyphs=word_of_glory

But wait, there’s more!

Actions Header and Footer

Let’s say we want to apply some actions to all actors. For example, if you look at that simulation you might have noticed the glaring error I mentioned earlier: none of the actors ever cast Judgment! In fact, they can’t, because none of them have a seal active, because we never told them to cast a seal. Normally that’s done in the precombat action list, which we never provided. Likewise, none of them actually use active mitigation abilities, so the TMI results are essentially random and don’t reflect the holy power generation of each action list.

We could define a shorthand for SotR and put it in every one of the action lists, like “SotR>CS>J>AS+GC,” but that would be a bit tedious and make each configuration harder to read. Doubly so if we added shorthands and entries for Word of Glory and Eternal Flame. And it still doesn’t solve our seal problem.

This is where the Action Header and Footer text boxes come to the rescue. They act as bookends for each rotation configuration, allowing you to specify some actions that apply to every actor. So let’s edit the Action Header and Footer boxes and see how this works.

Editing the Action Header and Footer

Editing the Action Header and Footer

The tool will now sandwich each configuration between the text in these two boxes. When we hit Import!, we now have actors which will cast Seal of Insight before combat and use Shield of the Righteous, Holy Wrath, and Consecration:

The profile generated after adding text to the Actions Header and Footer boxes.

The profile generated after adding text to the Actions Header and Footer boxes.

Running this simulation gives us a little better differentiation between the different holy power generator priorities:

Results for Rotation Comparison #2

The results of our revised simulation.

The results of our revised simulation.

Another good example is adding an “actions+=/sacred_shield” line to the end of the Actions Footer to refresh Sacred Shield any time you have an empty GCD. I’m sure you can imagine other uses as well. Note that since the tool is just splicing together text, you’re not limited to putting just actions in the Actions Header or Footer. Any valid SimC syntax that you want to add to the end of each actor would work, such as “position=back” or “tmi_window=5.” In fact, you could add those to the Default Gear text box to achieve the same effect.

Rotation Syntax: Part Deux

What if I want to add something in-between two shorthands? As a (somewhat contrived) example, what if I want to try all of the permutations of CS>J>(other stuff)>AS? As it turns out, you can do that several different ways.

If you prefer sticking with shorthand, you could obviously define a shorthand for (other stuff). To make this example more concrete, let’s say that “other stuff” is our level 90 talents, e.g. ES>LH>HPr, or /execution_sentence/lights_hammer/holy_prism in longhand. We could define

X=execution_sentence/lights_hammer/holy_prism

and then define rotations CS>J>X>AS, CS>AS>X>J, and so on to create our permutations.

If the list of “other stuff” is so long that this would be unwieldy, we could make use of another input mode of the Rotation Configurations text box. You see, the text box can also handle full, text-based action lists that span multiple lines. However, in this input mode, we have to separate each actor with a blank line, much like we did in the gear comparison. That might look something like this:

A longhand action list declaration.

A longhand action list declaration.

When we hit the Import! button, this text is faithfully reproduced between our Actions Header and Footer. The tool is smart enough to (a) recognize that we’re using a blank space to separate actors, and (b) only try to decode shorthand lines, which are lines containing one or more “>” symbols that do not start with the text “actions.” In fact, we can even mix full action declarations and shorthands, like so:

A mixture of longhand and shorthand definitions.

A mixture of longhand and shorthand definitions.

You can hit Import! to see that the decoder translates the shorthand lines into longhand for you, and places them in the appropriate order with all of the rest of the text for that actor. The only limitation is that it will not try to decode single-action shorthands, so “CS” won’t be translated, because the decoder treats any line that doesn’t contain a “>” to be plain text. This is why I didn’t use “AS+GC” in Alice’s configuration above. If you need to, you can get around this by “cheating” a bit and chaining the ability together twice. For example, “CS>CS” would be decoded into two crusader_strike lines. The second one would just be redundant, it wouldn’t change any of the actor’s behavior.

If your “other stuff” was very long, you could put it in a simple text file (e.g. middle_of_rotation.simc) and use that file name in place of the explicit action description. In other words, you’d replace actions+=/execution_sentence/lights_hammer/holy_prism with middle_of_rotation.simc. And you could even define an abbreviation “X=middle_of_rotation.simc” on the sidebar if you wanted, so that you could use it in shorthands. You really have an incredible amount of flexibility in how you define rotations with this tool.

There’s one major limitation that I want to mention though. If you use a new blank line to separate actors, you need to be consistent and do it for every actor. In other words, the input shown below will not work – or rather, it will translate to two different actors rather than three!

Mixing single-line and multiple-line configurations. This only produces two actors, the second one having CS>J>AS>CS>AS>J as its rotation. In other words, don’t do this!

Final Comments

By the end of this tutorial, you should be able to use the Automation Tool to compare all sorts of different things. The goal was to make the tool as useful as possible while still keeping it simple to use. Any theorycrafter that’s familiar with basic SimC syntax should be able to fire up the GUI and use the tool without having to mess around with the command line or batch processing. I’ll be making heavy use of the tool myself in the coming months as I run (and post) simulations investigating our optimal play style in Warlords of Draenor.

If you have a question about the tool or a suggestion for improvement, please don’t hesitate to contact me. Leaving a comment here on the blog is fine, or you can catch me in the #simulationcraft irc channel on irc.stratics.com. If you have a long list of shorthand abbreviations to add to the sidebar, you should contact me rather than posting the entire list here, as I have a google doc set up for that which will make it easier to copy/paste your shorthands into the code.

There are several things that aren’t well-supported, and may not ever be. The most important is probably the use of multiple action lists and the /run_action_list command. A lot of profiles use this to separate out single-target and multiple-target rotations, or make more complicated rotation paths a little clearer to read. There’s no inherent syntax for defining separate action lists in the shorthand code, though of course you could write them out in full or use .simc files and cleverly stitch them together.

That said, this tool was never intended for that type of fine-detail tuning. It uses the same philosophy as our TC101 experimental tests – simplify down to as few variables as possible. So for example, you might use this tool to test different single-target rotations (with one boss), and then use those results to determine the ideal single-target action priority list. You could then add a second boss in the Footer and create a bunch of configurations to test 2-target action lists, and so on. Once you’ve determined each of those independently, you would create a master profile that called the appropriate action list based on the number of targets. By breaking it down into several smaller problems, this tool can still save you plenty of time and effort compared to running sims by hand.

This entry was posted in Simcraft, Simulation, Tanking, Theck's Pounding Headaches, Theorycrafting and tagged , , , , , , , , , , , . Bookmark the permalink.

5 Responses to Simulationcraft Automation Tutorial – Part II

  1. Schroom says:

    great stuff till now. it’s not possible, or at least not yet, to do the same for overrides? like, to simulate one toon with different Bosses. Or even combine both? is it?

    • Theck says:

      Sure, just use the Footer area to define a bunch of bosses. For example, you can do a glyph sim creating 10 identical paladins, and then define ten bosses in the Footer area, each one targeting a different paladin.

      enemy=fluffy_1
      target=G_1

      enemy=fluffy_2
      target=G_2

      etc.

  2. Iutihaeel says:

    Hello, Theck.

    First of all, thank you for your marvellous work. I’m trying to squeeze the last bit dps out of my Prot Pally in order to play some kind of dps/tank hybrid class. With the recent changes, the Glyph of Harsh Words becomes a viable option again. Since i’m mostly off-tanking or even not tanking at all, dps ist a much more valuable factor than survivability to me. I couldn’t figure out how to alter the rotation to use word of glory offensively. Is there any option to do this right now?

    Thanks in advance.

Leave a Reply to Iutihaeel Cancel reply