YAML configuration files and schemas

YAML Ain’t Markup Language (YAML) is a human-readable data serialization language, which we use to configure the algorithms in this project, yaml-cpp. The application expects the user to adhere to a very specific layout of the configuration file. For some advanced algorithms like mimir::algorithm::PursePlanner, care must be taken when specifying the configuration. To help the practitioner, we make use of schemas to dynamically validate the configuration files, forked from yavl-cpp-cmake. The YAML validation ensures that the provided YAML structure contains the expected entries, as well as data types. A data type can be one of: string, double, float, bool, uint64, int64, int, uint, int16, uint16, int8, uint8, enum.

Under normal circumstances the schema is internal to the program, but for mimir::algorithm::PursePlanner it is dynamic in nature, because the settings are propagated to transitive dependencies and changes depending on chosen low-level algorithms (e.g. linear solver). The user needs to expand the schema, which currently resides within the same YAML document as the configuration itself. Below, we present a simple YAML file and its schema, so that a practitioner can grasp the concept when populating the required schema according settings of transitive dependencies.

The YAML in Listing 1 has schema Listing 2.

Listing 1 (YAML snippet)

settings:
  plot: true
  time_step_ms: 3000
  nlp:
    vars: [1, 2, 3]

Listing 2 (Schema for YAML snippet)

map:
  settings:
    map:
      plot: [bool: ]
      time_step_ms: [int32: ]
      nlp:
    map:
      vars:
        list: [double: ]

Purse planner configuration schema

The schema for the mimir::algorithm::PursePlanner is given in Listing 3. We split each root map of Fig. 10 into separate diagrams, as shown in Fig. 11, Fig. 12, Fig. 13, Fig. 14, Fig. 15, including also Fig. 16 and Fig. 17.

Fig. 10 Schema root entries.

Fig. 11 Schema initial condition.

Fig. 12 Schema parameters.

Fig. 13 Schema inputs.

Fig. 14 Schema outputs.

Fig. 15 Schema settings.

Fig. 16 Schema for formulation settings.

Fig. 17 Schema for discretization settings, shooting.

Listing 3 (Schema for Purse planner configuration)

map:
  initial_condition:       { map: { x0: { list: [double: ] }}}
  parameters:
    map:
      setting_speed_U_v:   { map: { topic: [string: ], id: [string: ], default: [double: ] }}
      setting_radii:       { map: { topic: [string: ], id: [string: ], default: { list: [double: ] }}}
      aim_distance_D_s:    { map: { topic: [string: ], id: [string: ], default: [double: ] }}
      fish_margin_d_f:     { map: { topic: [string: ], id: [string: ], default: [double: ] }}
      leadline_tau_ll_z_d: { map: { topic: [string: ], id: [string: ], default: { list: [double: ] }}}
      sink_margin_z_min:   { map: { topic: [string: ], id: [string: ], default: [double: ] }}
      current_surface:     { map: { topic: [string: ], default: { list: [double: ] }}}
      current_fish:        { map: { topic: [string: ], default: { list: [double: ] }}}
      fish_velocity_over_ground: { map: { topic: [string: ], default: { list: [double: ] }}}
      fish_depth_z_s:      { map: { topic: [string: ], id: [string: ], default: [double: ] }}
  inputs:
    map:
      GPS_origin:          { map: { topic: [string: ], default: { list: [double: ] }}}
      vessel_pos_info:     { map: { topic: [string: ] }}
      vessel_gyro_info:    { map: { topic: [string: ] }}
      fish_pos_info:       { map: { topic: [string: ] }}
      fish_relative_pos:   { map: { topic: [string: ] }}
      keep_solution:       { map: { topic: [string: ] }}
  outputs:
    map:
      id: [string: ]
      trajectory_vessel:   { map: { topic: [string: ] }}
      trajectory_vessel_rot:   { map: { topic: [string: ] }}
      trajectory_fish:     { map: { topic: [string: ] }}
      nlp_config:          { map: { topic: [string: ] }}
      nlp_stats:           { map: { topic: [string: ] }}
      vessel_speed:        { map: { topic: [string: ] }}
      vessel_course_rate:  { map: { topic: [string: ] }}
      deploy_position:     { map: { topic: [string: ] }}
      collide_position:    { map: { topic: [string: ] }}
      collide_time:        { map: { topic: [string: ] }}
  settings:
    map:
      plot: [bool: ]
      time_step_ms: [int32: ]
      nlp:
    map:
      formulation:
        map:
          heading_rot_max: [double: ]  # Rate of turn vessel heading [rad/s]
          heading_acc_max: [double: ]  # Heading acceleration [rad/s^2]
          deploy_clockwise: [bool: ]   # Clockwise: true, Counter-clockwise: false
          decision_parameters:
            map:
              ellipse:
                map:
                  along: { list: [double: ] } # min, max along-track placement
                  across: { list: [double: ] } # min, max cross-track placement
          subsystem:
            map:
              x_1:
                map:
                  gamma: [double: ]           # Gain for path constrained particle
                  k_d: [double: ]             # Prop. feedback deployment arc length
                  k_pd: [double: ]            # Prop. feedback post deploy arc length >>k_d
                  Delta_chi: [double: ]       # Rendezvous for tilde chi (should be < 1)
                  Delta: [double: ]           # Lookahead distance, large is conservative
                  deploy_vicinity: [double: ] # Max. dist. between vehicle and deploy point
                  omega_max: [double: ]       # Max-ish rate of turn (might be violated)
          objective:
            map:
              terminal:
                map:
                  time_penalty: [double: ]    # Minimize time to arrive at deploy
                  tdiff_penalty: [double: ]   # MPCC dual variable to enforce max(t_diff,0)
                  fish_trap_slack: [double: ] # Penalize slack for fish dist. at deployed
      with_callback: [bool: ]
      solver:
        map:
          name: [string: ]
          options:
            *ipopt-schema
      discretization:
        x_1:
          *shoot-schema
        x_2:
          *shoot-schema
      integrator:
    map:
      name: [string: ]
      options:
        map:
          print_stats: [bool: ]
          #abstol: [double: ]
          collocation_scheme: [string: ]      # collocation
          interpolation_order: [uint: ]       # collocation
          number_of_finite_elements: [uint: ] # collocation