About modifiers and layers

[fohrloop]

I'm trying to understand how layers work in the keyboard_layout_optimizer. This is what I've got this far (might be correct or incorrect):

• Layers are defined by adding more elements into the lists in keyboard configuration file base_layout.keys. For example, this has 6 layers (1 base layer + 5 other layers):

base_layout:
  keys:
    # Row 1
    - - ["x", "X", "ſ", "−", "ξ", "Ξ"]
      - ["v", "V", "…", "⇞", "", "√"]
      - ["l", "L", "_", "⌫", "λ", "Λ"]

The keys that lead to the layers are set in the keyboard config yaml, base_layout.modifiers. If there are 6 layers (1+5), the modifiers should have 5 elements. Each of the element has two keys: Left and Right. For example:

    - Left:
        type: hold
        value: [[1,2]]
      Right:
        type: hold
        value: [[18,2]]

Then, the type can be either "hold", "one_shot" or "long_press", and the value should be a list of positions defined in the keyboard.matrix_positions. Is that correct?

Then, more questions:

• What difference it makes in the evaluation/optimization phase if the type is "hold", "one_shot" or "long_press"?
• What does it mean if Left value is different from the Right value? Does the above example mean that pressing and holding [1,2] the keys for the Left hand do change layer, and then pressing and holding [18,2] changes the values on the right side? I ask this because since [1,2] key is on the Left side, I would guess people want that to alter the right side.
• What does grouped_layers: 2 do? I read is says "number of consecutive symbols from base layout to group together generating a layout" but that does not still open it to me.
• When running optimization, can keys freely move between layers? Is that configurable?

[dariogoetz]

I'm trying to understand how layers work in the keyboard_layout_optimizer. This is what I've got this far (might be correct or incorrect):

* Layers are defined by adding more elements into the lists in keyboard configuration file `base_layout.keys`. For example, this has 6 layers (1 base layer + 5 other layers):

base_layout:
  keys:
    # Row 1
    - - ["x", "X", "ſ", "−", "ξ", "Ξ"]
      - ["v", "V", "…", "⇞", "", "√"]
      - ["l", "L", "_", "⌫", "λ", "Λ"]

Yes, exactly. And the symbols that you specify on the commandline are those from the first items of these lists for which the fixed_keys are false.

The keys that lead to the layers are set in the keyboard config yaml, base_layout.modifiers. If there are 6 layers (1+5), the modifiers should have 5 elements. Each of the element has two keys: Left and Right. For example:

    - Left:
        type: hold
        value: [[1,2]]
      Right:
        type: hold
        value: [[18,2]]

Then, the type can be either "hold", "one_shot" or "long_press", and the value should be a list of positions defined in the keyboard.matrix_positions. Is that correct?

Yes. Alternatively to specifying positions from keyboard.matrix_positions you can also specify symbols, e.g. ♛ or a. Then the key corresponding to that symbol in the layout will serve as a modifier. Keep in mind that that key might change with the layout if the symbol is one of those specified on the commandline; in particular, it might then move during optimization.

Then, more questions:

* What difference it makes in the evaluation/optimization phase if the type is "hold", "one_shot" or "long_press"?

The difference between these types manifests when the higher layer symbols are broken down into multiple base layer keypresses (if evaluation.ngram_mapper.split_modifiers.enabled is true otherwise the keys are taken "as they are"). Then n-grams containing a symbol on a higher layer are replaced with a series of n-grams containing the corresponding modifiers and the corresponding key. E.g. an A is replaced by shift and a.
Depending on the type (hold, one_shot and long_press), the rules for this expansion change. Most notably, the hold modifier makes the assumption that the modifier key is held beyond the keypress of the modified key. For bigrams and trigrams his introduces new n-grams that have the modifier after the modified key, e.g. A-b gets expanded to shift-a, a-b and shift-b.
The one_shot type simply puts the modifier before the modified key, e.g. A-b gets expanded to shift-a, a-b.
The longpress modifier (does not have a value field and) does not add any modifier, e.g. A gets expanded to a.

Each of these modifier usages can have their own cost associated to them with the modifier_usage metric.

* What does it mean if Left value is different from the Right value? Does the above example mean that pressing and holding [1,2] the keys for the Left hand do change layer, and then pressing and holding [18,2] changes the values on the right side? I ask this because since [1,2] key is on the Left side, I would guess people want that to alter the _right_ side.

No, the evaluator makes the assumption that higher-layer symbols on a key on the one hand will be modified with a modifier on the other hand. So if a key is hit with the left hand, the modifier under Right will be taken. It would make sense to then also specify a location on the right hand if there are two modifier keys for that layer (e.g. left and right shift key). If there is only one modifier key on the keyboard, both entries under Left and Right may also refer to the same item (e.g. for many modern split keyboards with thumb-clusters).

* What does `grouped_layers: 2` do? I read is says "number of consecutive symbols from base layout to group together generating a layout" but that does not still open it to me.

This parameter is only used when the "grouped layout generator" is used via the --grouped-layout-generator commandline argument. Usually, when not using that option, the whole list of symbols in the base_layout moves together with the permutations of the layout (according to the layout string on the commandline) except for the layers specified in fixed_layers. For instance, if fixed_layers is empty, then ["x", "X", "ſ", "−", "ξ", "Ξ"] would always be on the same key. For fixed_layers=[2], then the ſ would remain on its original position (as defined in the base_layout) and all the other symbols would move together with x.
When using the "grouped layout generator", the list of keys in the base_layout are grouped together by the number of grouped_layers. So if grouped_layers=2 then x and X would stay together, ſ and − would stay together and ξ and Ξ would stay together. Note however, that in that case, you would need to specify every first item of these groups in the layout string on the commandline, one group after the other, e.g. for the standard.yml config instead of a layout string abcd you would need to specify abcd{+]:αβχδ.
This layout generation option in particular allows you to move/optimize symbols freely between layers (see your next question), e.g. in the above example using the layout string αbcd{+]:aβχδ would put the α on the base layer and a on the third layer (i.e. switch α and a).

The hgi.yml config file was made with this in mind. It describes a very small keyboard with less keys than alpha characters. There, the alpha characters were optimized across layers.

* When running optimization, can keys freely move between layers? Is that configurable?

Yes, by using the --grouped-layout-generator option, see the explanation above.

[fohrloop]

(whether the "key up" happens before or after the other key, does not matter, though, if I'm not mistaken).

Wouldn't the [ShiftDown]ab[ShiftUp] result in AB? And then [ShiftDown]a[ShiftUp]b to Ab?

The keypress of the shift key and the a are directly one after the other. If you would only expand the H-a to shift-h, h-a, this would be missed.

Nevermind, this explains it. The only way to not miss it would be to also consider the key-ups: Ha -> [shift]h, [shift-up]a. Thank you for taking time and explaining this.

[dariogoetz]

With "the other key", I meant the modified key. So it is unclear whether "shift up" happens before or after "a up". b will be pressed after both of the other key ups.

[fohrloop]

can key from layer 0 go freely to layer 1, and if so, how?

Regarding to this. First thanks for the examples, but I still ask for a confirmation. Let's say I have a 4-key keyboard. And I have two layers, and I want to put there symbols e t a o 1 2 3 4. I put to the base layout:

base_layout:
  keys:
    - - ["e", "a"]
      - ["t", "o"]
    - - ["1", "3"]
      - ["2", "4"]

And I run the optimizer. Will the optimizer then move the most common characters e t a o to the layer 0 and the numbers 1 2 3 4 to layer 1? In essence

e t
1 2

would become

e t
a o

or something similar, but all the common alphas would be put into the base layer? (This example is missing the modifier key to change the layer, but you can imagine it's there).

I kind of would have thought, that grouped_layers: 1 would mean that the base layer e t 1 2 would be optimized independently from the layer 1 a o 3 4, but it would not allow symbols to move from one layer to another. But that is the case? Does the grouped_layers: 2 then allow layer 0 to exchange symbols with layer 2 during optimization..?

[dariogoetz]

can key from layer 0 go freely to layer 1, and if so, how?

Regarding to this. First thanks for the examples, but I still ask for a confirmation. Let's say I have a 4-key keyboard. And I have two layers, and I want to put there symbols e t a o 1 2 3 4. I put to the base layout:

base_layout:
  keys:
    - - ["e", "a"]
      - ["t", "o"]
    - - ["1", "3"]
      - ["2", "4"]

And I run the optimizer. Will the optimizer then move the most common characters e t a o to the layer 0 and the numbers 1 2 3 4 to layer 1? In essence

e t
1 2

would become

e t
a o

or something similar, but all the common alphas would be put into the base layer? (This example is missing the modifier key to change the layer, but you can imagine it's there).

If grouped_layers: 1 and if the optimizer deemed that less costly, then yes, that would happen.

If, however, grouped_layers: 2, then the a would be "glued" to the e - they would form a "group" - (and t to o and 1 to 3 and 2 to 4) and it would only generate a permutation of
e t
1 2
on the first layer.

I kind of would have thought, that grouped_layers: 1 would mean that the base layer e t 1 2 would be optimized independently from the layer 1 a o 3 4, but it would not allow symbols to move from one layer to another. But that is the case? Does the grouped_layers: 2 then allow layer 0 to exchange symbols with layer 2 during optimization..?

What you have in mind is not possible with the current implementation (i.e. optimizing within layers independently from each other). One can either optimize the layers together (meaning that the symbols defined in the base_layout stay together) or optimize across layers (where symbols move freely within and across layers).

And yes, grouped_layers: 2 allows symbols to move between layer 0 and layer 2 (or respectively between layer 1 and layer 3 together with their "group partners").

PS:
I guess the name "grouped layout generator" is quite misleading... Could have done a better job there.

[fohrloop]

Thanks a lot for the confirmation!