spot/spot/twaalgos/synthesis.hh

// -*- coding: utf-8 -*-
// Copyright (C) 2020-2021 Laboratoire de Recherche et
// Développement de l'Epita (LRDE).
//
// This file is part of Spot, a model checking library.
//
// Spot is free software; you can redistribute it and/or modify it
// under the terms of the GNU General Public License as published by
// the Free Software Foundation; either version 3 of the License, or
// (at your option) any later version.
//
// Spot is distributed in the hope that it will be useful, but WITHOUT
// ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
// or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public
// License for more details.
//
// You should have received a copy of the GNU General Public License
// along with this program.  If not, see <http://www.gnu.org/licenses/>.

#pragma once

#include <spot/twa/twagraph.hh>
#include <spot/twaalgos/game.hh>
#include <bddx.h>

namespace spot
{
  /// \brief make each transition (conditionally, see do__simpify)
  ///        a 2-step transition
  ///
  /// Given a set of atomic propositions I, split each transition
  ///     p -- cond --> q                cond in 2^2^AP
  /// into a set of transitions of the form
  ///     p -- {a} --> (p,a) -- o --> q
  /// for each a in cond \cap 2^2^I
  /// and where o = (cond & a) \cap 2^2^(O)
  ///
  /// By definition, the states p are deterministic,
  /// only the states of the form
  /// (p,a) may be non-deterministic.
  /// This function is used to transform an automaton into a turn-based game in
  /// the context of LTL reactive synthesis.
  /// \param aut          automaton to be transformed
  /// \param output_bdd   conjunction of all output AP, all APs not present
  ///                     are treated as inputs
  /// \param complete_env Whether the automaton should be complete for the
  ///                     environment, i.e. the player of I
  /// \param do_simplify  If a state has a single outgoing transition
  ///                     we do not necessarily have to split it
  ///                     to solve the game
  /// \note: This function also computes the state players
  /// \note: If the automaton is to be completed for both env and player
  ///        then egdes between the sinks will be added
  /// (assuming that the environnement/player of I) plays first
  SPOT_API twa_graph_ptr
  split_2step(const const_twa_graph_ptr& aut,
              const bdd& output_bdd, bool complete_env, bool do_simplify);

  /// \brief the reverse of split_2step
  ///
  /// \note: This function relies on the named property "state-player"
  SPOT_API twa_graph_ptr
  unsplit_2step(const const_twa_graph_ptr& aut);


  /// \brief Creates a game from a specification and a set of
  /// output propositions
  ///
  /// \param f The specification given as LTL/PSL formula
  /// \param all_outs The names of all output propositions
  /// \param gi game_info structure
  /// \note All propositions in the formula that do not appear in all_outs
  /// arer treated as input variables.
  SPOT_API twa_graph_ptr
  create_game(const formula& f,
              const std::vector<std::string>& all_outs,
              game_info& gi);

  /// \brief create_game called with default options
  SPOT_API twa_graph_ptr
  create_game(const formula& f,
              const std::vector<std::string>& all_outs);

  /// \brief Like create_game but formula given as string
  SPOT_API twa_graph_ptr
  create_game(const std::string& f,
              const std::vector<std::string>& all_outs,
              game_info& gi);

  /// \brief create_game called with default options
  SPOT_API twa_graph_ptr
  create_game(const std::string& f,
              const std::vector<std::string>& all_outs);

  /// \brief Takes a solved game and restricts the automaton to the
  ///        winning strategy of the player
  ///
  /// \param arena        twa_graph with named properties "state-player",
  ///                     "strategy" and "state-winner"
  /// \param unsplit      Whether or not to unsplit the automaton
  /// \param keep_acc     Whether or not keep the acceptance condition
  /// \return             the resulting twa_graph
  SPOT_API spot::twa_graph_ptr
  apply_strategy(const spot::twa_graph_ptr& arena,
                 bool unsplit, bool keep_acc);

  /// \brief Minimizes a strategy. Strategies are infact
  /// Mealy machines. So we can use techniques designed for them
  ///
  /// \param strat The machine to minimize
  /// \param min_lvl How to minimize the machine:
  ///                0: No minimization, 1: Minimizing it like an DFA,
  ///                means the language is preserved, 2: Inclusion with
  ///                output assignement, 3: Exact minimization using
  ///                SAT solving, 4: SAT solving with DFA minimization as
  ///                preprocessing, 5: SAT solving using inclusion based
  ///                 minimization with output assignment as preprocessing
  /// \note min_lvl 1 and 2 work more efficiently on UNSPLIT strategies,
  ///       whereas min_lvl 3, 4 and 5 mandate a SPLIT strategy
  SPOT_API void
  minimize_strategy_here(twa_graph_ptr& strat, int min_lvl);

  ///\brief Like minimize_strategy_here
  SPOT_API twa_graph_ptr
  minimize_strategy(const_twa_graph_ptr& strat, int min_lvl);


  /// \brief creates a strategy from a solved game taking into account the
  ///        options given in gi
  SPOT_API twa_graph_ptr
  create_strategy(twa_graph_ptr arena, game_info& gi);

  /// \brief Like create_strategy but with default options
  SPOT_API twa_graph_ptr
  create_strategy(twa_graph_ptr arena);


  /// \brief A struct that represents different types of strategy like
  ///        objects
  struct SPOT_API
  strategy_like_t
  {
    //  -1 : Unrealizable
    //  0 : Unknown
    //  1 : Realizable -> regular strat
    //  2 : Realizable -> strat is DTGBA and a glob_cond // todo
    int success;
    twa_graph_ptr strat_like;
    bdd glob_cond;
  };


  /// \brief Seeks to decompose a formula into independently synthesizable
  /// sub-parts. The conjunction of all sub-parts then
  /// satisfies the specification
  ///
  /// The algorithm is largely based on \cite{finkbeiner2021specification}.
  /// \param f the formula to split
  /// \param outs vector with the names of all output propositions
  /// \return A vector of pairs holding a subformula and the used output
  ///  propositions each.
  SPOT_API std::pair<std::vector<formula>, std::vector<std::set<formula>>>
  split_independant_formulas(formula f, const std::vector<std::string>& outs);

  /// \brief Like split_independant_formulas but the formula given as string
  SPOT_API std::pair<std::vector<formula>, std::vector<std::set<formula>>>
  split_independant_formulas(const std::string& f,
                             const std::vector<std::string>& outs);

  /// \brief Creates a strategy for the formula given by calling all
  ///        intermediate steps
  ///
  /// For certain formulas, we can ''bypass'' the traditional way
  /// and find directly a strategy or some other representation of a
  /// winning condition without translating the formula as such.
  /// If no such simplifications can be made, it executes the usual way.
  /// \param f The formula to synthesize a strategy for
  /// \param output_aps A vector with the name of all output properties.
  ///                   All APs not named in this vector are treated as inputs
  SPOT_API strategy_like_t
  try_create_direct_strategy(formula f,
                             const std::vector<std::string>& output_aps,
                             game_info& gi);

}