示例#1
0
def sarsa_epsilon_greedy( environment,  learn_tracker=None, # track progress of learning
                          initial_Qsa=0.0, # init non-terminal_set of V(s) (terminal_set=0.0)
                          initial_action_value_coll=None, # if input, use it.
                          read_pickle_file='', 
                          save_pickle_file='',
                          use_list_of_start_states=False, # use list OR single start state of environment.
                          do_summ_print=True, show_last_change=True, fmt_Q='%g', fmt_R='%g',
                          pcent_progress_print=10,
                          show_banner = True,
                          max_num_episodes=1000, min_num_episodes=10, max_abserr=0.001, 
                          gamma=0.9,
                          iteration_prints=0,
                          max_episode_steps=sys.maxsize,
                          epsilon=0.1, const_epsilon=True, epsilon_half_life=200,
                          alpha=0.1, const_alpha=True, alpha_half_life=200,
                          N_episodes_wo_decay=0):
    """
    ... GIVEN AN ENVIRONMENT ... 
    apply SARSA Temporal Difference to find the OPTIMAL POLICY and STATE VALUES
    
    Returns: Policy and ActionValueColl objects
    
    Use Episode Discounted Returns to find V(s), State-Value Function
    
    Terminates when abserr < max_abserr
    
    Assume that V(s), action_value_coll, has been initialized prior to call.
    
    Assume environment attached to policy will have method "get_any_action_state_hash"
    in order to begin at any action state.
    
    CREATES BOTH policy AND action_value_coll OBJECTS.
    """
    
    # create EpsilonGreedy, Alpha and ActionValueColl objects
    eg = EpsilonGreedy(epsilon=epsilon, const_epsilon=const_epsilon, half_life=epsilon_half_life,
                       N_episodes_wo_decay=N_episodes_wo_decay)

    
    alpha_obj = Alpha( alpha=alpha, const_alpha=const_alpha, half_life=alpha_half_life )


    if initial_action_value_coll is None:
        action_value_coll = ActionValueColl( environment, init_val=initial_Qsa )
    else:
        action_value_coll = initial_action_value_coll
    #action_value_coll.summ_print()
    num_s_hash = len( environment.get_all_action_state_hashes() )

    if read_pickle_file:
        action_value_coll.init_from_pickle_file( read_pickle_file )
    
    if do_summ_print:
        print('================== EPSILON GREEDY DEFINED AS ========================')
        eg.summ_print()
        
        print('================== LEARNING RATE DEFINED AS ========================')
        alpha_obj.summ_print()
    
    if show_banner:
        s = 'Starting a Maximum of %i SARSA Epsilon Greedy Episodes'%max_num_episodes +\
            '\nfor "%s" with Gamma = %g, Alpha = %g'%( environment.name, gamma, alpha_obj() )
        banner(s, banner_char='', leftMargin=0, just='center')
        
    # Iterate over a list of known possible start states
    if use_list_of_start_states:
        loop_stateL = environment.limited_start_state_list()
    else:
        #loop_stateL = [ random.choice( environment.limited_start_state_list() ) ]
        loop_stateL = [ environment.start_state_hash ]
        
    if show_banner:
        print('======================= Iterating over Start States ==================================')
        print( loop_stateL )
        print('======================================================================================')

        
    # set counter and flag
    episode_loop_counter = 0
    keep_looping = True
    
    progress_str = ''
    while (episode_loop_counter<=max_num_episodes-1) and keep_looping :
            
        keep_looping = False
        abserr = 0.0 # calculated below as part of termination criteria
        Nterminal_episodes = set() # tracks if start_hash got to terminal_set or max_num_episodes
        
        for start_hash in loop_stateL:
            episode_loop_counter += 1
            if episode_loop_counter > max_num_episodes:
                break
            
            if learn_tracker is not None:
                learn_tracker.add_new_episode()
            
            s_hash = start_hash
            a_desc = action_value_coll.get_best_eps_greedy_action( s_hash, epsgreedy_obj=eg )
            
            for n_episode_steps in range( max_episode_steps ):
                
                # Begin an episode
                if a_desc is None:
                    Nterminal_episodes.add( start_hash )
                    print('break for a_desc==None')
                    break
                else:
                    sn_hash, reward = environment.get_action_snext_reward( s_hash, a_desc )
                    if learn_tracker is not None:
                        learn_tracker.add_sarsn_to_current_episode( s_hash, a_desc, 
                                                                    reward, sn_hash)
                    
                    if sn_hash is None:
                        Nterminal_episodes.add( start_hash )
                        print('break for sn_hash==None')
                        break
                    else:
                        an_desc = action_value_coll.get_best_eps_greedy_action( sn_hash, 
                                                                                epsgreedy_obj=eg )
            
                        action_value_coll.sarsa_update( s_hash=s_hash, a_desc=a_desc, 
                                                        alpha=alpha_obj(), gamma=gamma, 
                                                        sn_hash=sn_hash, an_desc=an_desc, 
                                                        reward=reward)
                        
                        if sn_hash in environment.terminal_set:
                            Nterminal_episodes.add( start_hash )
                            if (n_episode_steps==0) and (num_s_hash>2):
                                print('1st step break for sn_hash in terminal_set', sn_hash, 
                                      ' s_hash=%s'%str(s_hash), ' a_desc=%s'%str(a_desc))
                            break
                        s_hash = sn_hash
                        a_desc = an_desc
        
        # increment episode counter on EpsilonGreedy and Alpha objects
        eg.inc_N_episodes()
        alpha_obj.inc_N_episodes()
                
        abserr = action_value_coll.get_biggest_action_state_err()
        if abserr > max_abserr:
            keep_looping = True
            
        if episode_loop_counter < min_num_episodes:
            keep_looping = True # must loop for min_num_episodes at least
            
        pc_done = 100.0 * float(episode_loop_counter) / float(max_num_episodes)
        
        if pcent_progress_print > 0:
            out_str = '%3i%%'%( pcent_progress_print*(int(pc_done/float(pcent_progress_print)) ) )
        else:
            out_str = progress_str
        
        if out_str != progress_str:
            #score = environment.get_policy_score( policy=policy, start_state_hash=None, step_limit=1000)
            #print(out_str, ' score=%s'%str(score), ' = (r_sum, n_steps, msg)', end=' ')
            
            print(out_str, end=' ')
            print( 'Nterminal episodes =', len(Nterminal_episodes),' of ', len(loop_stateL))
            progress_str = out_str
    #print()
    
    policy = action_value_coll.get_policy()
    
    if do_summ_print:
        s = ''
        if episode_loop_counter >= max_num_episodes:
            s = '   (NOTE: STOPPED ON MAX-ITERATIONS)'

        print( 'Exited Epsilon Greedy, TD(0) Value Iteration', s )
        print( '   # episodes      =', episode_loop_counter, ' (min limit=%i)'%min_num_episodes, ' (max limit=%i)'%max_num_episodes )
        print( '   gamma           =', gamma )
        print( '   estimated err   =', abserr )
        print( '   Error limit     =', max_abserr )
        print( 'Nterminal episodes =', len(Nterminal_episodes),' of ', len(loop_stateL))
    
        action_value_coll.summ_print(show_last_change=show_last_change, fmt_Q=fmt_Q )
        policy.summ_print(  environment=environment, verbosity=0, show_env_states=False  )
        
        try: # sims may not have a layout_print
            environment.layout_print( vname='reward', fmt=fmt_R, show_env_states=False, none_str='*')
        except:
            pass

        print('================== EPSILON GREEDY DEFINED AS ========================')
        eg.summ_print()
        
        print('================== LEARNING RATE DEFINED AS ========================')
        alpha_obj.summ_print()

    if save_pickle_file:
        policy.save_to_pickle_file( save_pickle_file )
        action_value_coll.save_to_pickle_file( save_pickle_file )
        
    return policy, action_value_coll #, steps_per_episodeL, reward_sum_per_episodeL
示例#2
0
def mc_epsilon_greedy(
        environment,
        initial_policy='default',  # can be 'default', 'random', policy_dictionary
        read_pickle_file='',
        save_pickle_file='',
        use_list_of_start_states=True,  # use list OR single start state of environment.
        iter_all_start_actions=False,  # pick random or iterate all starting actions
        first_visit=True,
        do_summ_print=True,
        showRunningAve=False,
        fmt_Q='%g',
        fmt_R='%g',
        show_initial_policy=True,
        max_num_episodes=1000,
        min_num_episodes=10,
        max_abserr=0.001,
        gamma=0.9,
        iteration_prints=0,
        max_episode_steps=10000,
        epsilon=0.1,
        const_epsilon=True,
        half_life=200,
        N_episodes_wo_decay=0):
    """
    ... GIVEN AN ENVIRONMENT ... 
    apply Monte Carlo Exploring Starts to find the OPTIMAL POLICY
    
    Returns: Policy and ActionValueRunAveColl objects
    
    Use Episode Discounted Returns to find Q(s,a), Action-Value Function
    
    Terminates when abserr < max_abserr
    
    Assume that Q(s,a), action_value_ave, has been initialized prior to call.
    
    Assume environment attached to policy will have method "get_any_action_state_hash"
    in order to begin at any action state.
    
    CREATES BOTH policy AND action_value OBJECTS.
    """

    eps_greedy = EpsilonGreedy(epsilon=epsilon,
                               const_epsilon=const_epsilon,
                               half_life=half_life,
                               N_episodes_wo_decay=N_episodes_wo_decay)

    # create Policy and ActionValueRunAveColl objects
    policy = Policy(environment=environment)
    if initial_policy == 'default':
        print('Initializing Policy to "default" in mc_epsilon_greedy')
        policy.learn_a_legal_action_from_env(env=environment)
        policy.set_policy_from_piD(environment.get_default_policy_desc_dict())
    elif initial_policy == 'random':
        print('Initializing Policy to "random" in mc_epsilon_greedy')
        policy.intialize_policy_to_random(env=environment)
    else:
        print('Initializing Policy to "custom policy" in mc_epsilon_greedy')
        policy.learn_a_legal_action_from_env(env=environment)
        policy.set_policy_from_piD(initial_policy)

    action_value_ave = ActionValueRunAveColl(environment)
    action_value_ave.init_Qsa_to_zero(
    )  # Terminal states w/o an action are NOT included
    #action_value_ave.summ_print()

    if read_pickle_file:
        policy.init_from_pickle_file(read_pickle_file)
        action_value_ave.init_from_pickle_file(read_pickle_file)

    if do_summ_print:
        if show_initial_policy:
            print(
                '=============== STARTING WITH THE INITIAL POLICY ===================='
            )
            policy.summ_print(verbosity=0,
                              environment=environment,
                              show_env_states=False,
                              none_str='*')

        print(
            '================== EPSILON GREEDY DEFINED AS ========================'
        )
        eps_greedy.summ_print()

    s = 'Starting a Maximum of %i Monte Carlo Epsilon Greedy\nfor "%s" with Gamma = %g'%\
        (max_num_episodes, environment.name, gamma)
    banner(s, banner_char='', leftMargin=0, just='center')

    # create an Episode object for getting returns
    episode = Episode(environment.name + ' Episode')

    # set counter and flag
    num_episodes = 0
    keep_looping = True

    limited_start_stateL = environment.limited_start_state_list()

    progress_str = ''
    while (num_episodes <= max_num_episodes - 1) and keep_looping:

        keep_looping = False
        abserr = 0.0  # calculated below as part of termination criteria
        Nterminal_episodes = set()

        # Iterate over a list of known possible start states
        if use_list_of_start_states:
            loop_stateL = limited_start_stateL
            random.shuffle(loop_stateL)
        else:
            #loop_stateL = [ random.choice( limited_start_stateL ) ]
            loop_stateL = [environment.start_state_hash]

        for start_hash in loop_stateL:

            if iter_all_start_actions:  # Iterate over ALL ACTIONS of start_hash
                a_descL = environment.get_state_legal_action_list(start_hash)
            else:
                a_desc = policy.get_single_action(start_hash)
                # if not iterating all actions, make sure first action has eps-greedy applied
                a_desc = eps_greedy(
                    a_desc,
                    environment.get_state_legal_action_list(start_hash))
                a_descL = [a_desc]
            # randomize action order
            random.shuffle(a_descL)

            for a_desc in a_descL:

                # break from inner loop if max_num_episodes is hit.
                if num_episodes >= max_num_episodes:
                    break

                make_episode(start_hash,
                             policy,
                             environment,
                             environment.terminal_set,
                             episode=episode,
                             first_a_desc=a_desc,
                             max_steps=max_episode_steps,
                             eps_greedy=eps_greedy)
                eps_greedy.inc_N_episodes()
                num_episodes += 1

                if episode.is_done():
                    Nterminal_episodes.add(start_hash)

                for dr in episode.get_rev_discounted_returns(
                        gamma=gamma, first_visit=first_visit, visit_type='SA'):
                    # look at each step from episode and calc average Q(s,a)
                    (s, a, r, sn, G) = dr
                    action_value_ave.add_val(s, a, G)

                    aL = environment.get_state_legal_action_list(s)
                    if aL:
                        best_a_desc, best_a_val = aL[0], float('-inf')
                        bestL = [best_a_desc]
                        for a in aL:
                            q = action_value_ave.get_ave(s, a)
                            if q > best_a_val:
                                best_a_desc, best_a_val = a, q
                                bestL = [a]
                            elif q == best_a_val:
                                bestL.append(a)
                        best_a_desc = random.choice(bestL)
                        policy.set_sole_action(s, best_a_desc)

        abserr = action_value_ave.get_biggest_action_state_err()
        if abserr > max_abserr:
            keep_looping = True

        if num_episodes < min_num_episodes:
            keep_looping = True  # must loop for min_num_episodes at least

        pc_done = 100.0 * float(num_episodes) / float(max_num_episodes)
        out_str = '%3i%%' % (5 * (int(pc_done / 5.0)))
        if out_str != progress_str:
            score = environment.get_policy_score(policy=policy,
                                                 start_state_hash=None,
                                                 step_limit=1000)
            print(out_str,
                  ' score=%s' % str(score),
                  ' = (r_sum, n_steps, msg)',
                  end=' ')
            print('Nterminal episodes =', len(Nterminal_episodes), ' of ',
                  len(loop_stateL))
            progress_str = out_str
    print()
    if do_summ_print:
        s = ''
        if num_episodes >= max_num_episodes:
            s = '   (NOTE: STOPPED ON MAX-ITERATIONS)'

        print('Exited Epsilon Greedy, MC First-Visit Value Iterations', s)
        print('   num episodes    =', num_episodes,
              ' (min limit=%i)' % min_num_episodes,
              ' (max limit=%i)' % max_num_episodes)
        print('   gamma           =', gamma)
        print('   estimated err   =', abserr)
        print('   Error limit     =', max_abserr)
        print('Nterminal episodes =', len(Nterminal_episodes), ' of ',
              len(loop_stateL))

        action_value_ave.summ_print(showRunningAve=showRunningAve, fmt_Q=fmt_Q)
        policy.summ_print(environment=environment,
                          verbosity=0,
                          show_env_states=False)

        try:  # sims may not have a layout_print
            environment.layout_print(vname='reward',
                                     fmt=fmt_R,
                                     show_env_states=False,
                                     none_str='*')
        except:
            pass

    if save_pickle_file:
        policy.save_to_pickle_file(save_pickle_file)
        action_value_ave.save_to_pickle_file(save_pickle_file)

    return policy, action_value_ave
示例#3
0
class SA_SemiGradAgent(object):
    """
    SARSA or Qlearning semi-gradient agent for linear function approximator.
    """
    def __init__(
        self,
        environment,
        learn_tracker=None,  # track progress of learning
        sa_linear_function=None,  # if input, use it.
        update_type='sarsa',  # can be 'sarsa', 'qlearn'
        read_pickle_file='',
        save_pickle_file='',
        do_summ_print=True,
        show_last_change=True,
        pcent_progress_print=10,
        show_banner=True,
        gamma=0.9,
        iteration_prints=0,
        max_episode_steps=sys.maxsize,
        epsilon=0.1,  # can be constant or EpsilonGreedy object
        alpha=0.1):  # can be constant or Alpha object
        """
        ... GIVEN AN ENVIRONMENT ... 
        Use basic SARSA or Qlearning algorithm to solve for linear approximation of
        STATE-ACTION VALUES, Q(s,a)
        
        Each action is forced to be a DETERMINISTIC action leading to one state and reward.
        (If the next state or reward changes, only the new values will be considered)
            
        attribute: self.action_value_linfunc is the linear approximation, Q(s,a) object
        
        A DETERMINISTIC policy can be created externally from the self.action_value_linfunc attribute.
        """
        self.environment = environment
        self.learn_tracker = learn_tracker
        self.save_pickle_file = save_pickle_file

        self.do_summ_print = do_summ_print
        self.show_last_change = show_last_change
        self.pcent_progress_print = pcent_progress_print

        self.gamma = gamma
        self.iteration_prints = iteration_prints
        self.max_episode_steps = max_episode_steps

        self.num_episodes = 0
        self.num_updates = 0

        # if input epsilon is a float, use it to create an EpsilonGreedy object
        if type(epsilon) == type(0.1):
            self.epsilon_obj = EpsilonGreedy(epsilon=epsilon,
                                             const_epsilon=True)
        else:
            self.epsilon_obj = epsilon

        # if input alpha is a float, use it to create an Alpha object
        if type(alpha) == type(0.1):
            self.alpha_obj = Alpha(alpha=alpha, const_alpha=True)
        else:
            self.alpha_obj = alpha

        # create the action_value_linfunc for the environment.
        self.action_value_linfunc = sa_linear_function
        self.update_type = update_type

        if read_pickle_file:
            self.action_value_linfunc.init_from_pickle_file(read_pickle_file)

        if do_summ_print:
            print(
                '================== EPSILON GREEDY DEFINED AS ========================'
            )
            self.epsilon_obj.summ_print()

            print(
                '================== LEARNING RATE DEFINED AS ========================'
            )
            self.alpha_obj.summ_print()

        if show_banner:
            s = 'Starting a Maximum of %i %s Semi-Gradient Epsilon Greedy Steps/Episode'%(self.max_episode_steps, update_type.upper()) +\
                '\nfor "%s" with Gamma = %g, Alpha = %g'%( environment.name, self.gamma, self.alpha_obj() )
            banner(s, banner_char='', leftMargin=0, just='center')

    def run_episode(self, start_state, iter_sarsn=None):
        """
        Run a single episode of SARSA or Qlearning Semi-Gradient algorithm
        If iter_sarsn is input, use it instead of action_value_linfunc calculations.
        (Note: the start_state should NOT be in terminal_set if iter_sarsn is input.)
        """

        # increment episode counters
        self.num_episodes += 1
        self.epsilon_obj.inc_N_episodes()
        self.alpha_obj.inc_N_episodes()

        if self.learn_tracker is not None:
            self.learn_tracker.add_new_episode()

        # do SARSA or Qlearning Semi-Gradient loops until sn_hash in terminal_set
        s_hash = start_state

        n_steps_in_episode = 1
        while s_hash not in self.environment.terminal_set:

            if iter_sarsn is None:
                # get best epsilon-greedy action
                a_desc = self.action_value_linfunc.get_best_eps_greedy_action( \
                                                s_hash, epsgreedy_obj=self.epsilon_obj )
                # check for bad action value
                if a_desc is None:
                    print('break for a_desc==None at s_hash=%s' % str(s_hash))
                    break

                # get next state and reward
                sn_hash, reward = self.environment.get_action_snext_reward(
                    s_hash, a_desc)
            else:
                # retracing an existing episode
                s_hash, a_desc, reward, sn_hash = next(iter_sarsn)

            if self.learn_tracker is not None:
                self.learn_tracker.add_sarsn_to_current_episode(
                    s_hash, a_desc, reward, sn_hash)

            if sn_hash is None:
                print('break for sn_hash==None, #steps=', n_steps_in_episode,
                      ' s_hash=%s' % str(s_hash), ' a_desc=%s' % str(a_desc))
                break

            # do RL update of Q(s,a) value
            if self.update_type == 'sarsa':
                an_desc = self.action_value_linfunc.get_best_eps_greedy_action( \
                                                sn_hash, epsgreedy_obj=self.epsilon_obj )

                self.action_value_linfunc.sarsa_update(s_hash=s_hash,
                                                       a_desc=a_desc,
                                                       alpha=self.alpha_obj(),
                                                       gamma=self.gamma,
                                                       sn_hash=sn_hash,
                                                       an_desc=an_desc,
                                                       reward=reward)
            elif self.update_type == 'qlearn':

                self.action_value_linfunc.qlearning_update(
                    s_hash=s_hash,
                    a_desc=a_desc,
                    alpha=self.alpha_obj(),
                    gamma=self.gamma,
                    sn_hash=sn_hash,
                    reward=reward)

            self.num_updates += 1

            # keep a lid on the max number of episode steps.
            if n_steps_in_episode >= self.max_episode_steps:
                break

            # get ready for next loop
            n_steps_in_episode += 1
            s_hash = sn_hash

        #print(n_steps_in_episode, end=' ')

    def summ_print(self, long=True):  # pragma: no cover
        """Show State objects in sorted state_hash order."""
        print('___ Policy Evaluation Agent Summary ___')
        print('    Environment        = %s' % self.environment.name)
        print('    Update Type        = %s' % self.update_type)
        print('    Number of Episodes = %g' % self.num_episodes)

        print(
            '================== EPSILON GREEDY FINAL ========================')
        self.epsilon_obj.summ_print()

        print(
            '================== LEARNING RATE FINAL ========================')
        self.alpha_obj.summ_print()
示例#4
0
class DynaQAgent(object):
    """
    DynaQ Agent.
    """
    def __init__(
        self,
        environment,
        learn_tracker=None,  # track progress of learning
        initial_Qsa=0.0,  # init non-terminal_set of V(s) (terminal_set=0.0)
        initial_action_value_coll=None,  # if input, use it.
        read_pickle_file='',
        save_pickle_file='',
        do_summ_print=True,
        show_last_change=True,
        pcent_progress_print=10,
        show_banner=True,
        gamma=0.9,
        iteration_prints=0,
        max_episode_steps=sys.maxsize,
        epsilon=0.1,  # can be constant or EpsilonGreedy object
        alpha=0.1):  # can be constant or Alpha object
        """
        ... GIVEN AN ENVIRONMENT ... 
        Use basic Dyna-Q algorithm to solve for STATE-ACTION VALUES, Q(s,a)
        
        Each action is forced to be a DETERMINISTIC action leading to one state and reward.
        (If the next state or reward changes, only the new values will be considered)
            
        attribute: self.action_value_coll is the ActionValueColl, Q(s,a) object
        
        A DETERMINISTIC policy can be created externally from the self.action_value_coll attribute.
        """
        self.environment = environment
        self.learn_tracker = learn_tracker
        self.save_pickle_file = save_pickle_file

        self.do_summ_print = do_summ_print
        self.show_last_change = show_last_change
        self.pcent_progress_print = pcent_progress_print

        self.gamma = gamma
        self.iteration_prints = iteration_prints
        self.max_episode_steps = max_episode_steps

        self.num_episodes = 0
        self.num_updates = 0

        # if input epsilon is a float, use it to create an EpsilonGreedy object
        if type(epsilon) == type(0.1):
            self.epsilon_obj = EpsilonGreedy(epsilon=epsilon,
                                             const_epsilon=True)
        else:
            self.epsilon_obj = epsilon

        # if input alpha is a float, use it to create an Alpha object
        if type(alpha) == type(0.1):
            self.alpha_obj = Alpha(alpha=alpha, const_alpha=True)
        else:
            self.alpha_obj = alpha

        # create the action_value_coll for the environment.
        if initial_action_value_coll is None:
            self.action_value_coll = ActionValueColl(environment,
                                                     init_val=initial_Qsa)
        else:
            self.action_value_coll = initial_action_value_coll

        if read_pickle_file:
            self.action_value_coll.init_from_pickle_file(read_pickle_file)

        # initialize the model that will build from experience
        # do not build full model description on Model init, states not visited
        #  by the RL portion will have no returns values.
        self.model = Model(environment, build_initial_model=False)
        #for s_hash, aD in self.action_value_coll.QsaD.items():
        #    for a_desc, Q in aD.items():
        #        self.model.add_action( s_hash, a_desc )

        if do_summ_print:
            print(
                '================== EPSILON GREEDY DEFINED AS ========================'
            )
            self.epsilon_obj.summ_print()

            print(
                '================== LEARNING RATE DEFINED AS ========================'
            )
            self.alpha_obj.summ_print()

        if show_banner:
            s = 'Starting a Maximum of %i Dyna-Q Epsilon Greedy Steps/Episode'%self.max_episode_steps +\
                '\nfor "%s" with Gamma = %g, Alpha = %g'%( environment.name, self.gamma, self.alpha_obj() )
            banner(s, banner_char='', leftMargin=0, just='center')

    def run_episode(self, start_state, Nplanning_loops=5, iter_sarsn=None):
        """
        Run a single episode of Dyna-Q algorithm
        If iter_sarsn is input, use it instead of action_value_coll calculations.
        (Note: the start_state should NOT be in terminal_set if iter_sarsn is input.)
        """

        # increment episode counters
        self.num_episodes += 1
        self.epsilon_obj.inc_N_episodes()
        self.alpha_obj.inc_N_episodes()

        if self.learn_tracker is not None:
            self.learn_tracker.add_new_episode()

        # do dyna_q loops until sn_hash in terminal_set
        s_hash = start_state

        n_steps_in_episode = 1
        while s_hash not in self.environment.terminal_set:

            if iter_sarsn is None:
                # get best epsilon-greedy action
                a_desc = self.action_value_coll.get_best_eps_greedy_action( \
                                                s_hash, epsgreedy_obj=self.epsilon_obj )
                # check for bad action value
                if a_desc is None:
                    print('break for a_desc==None at s_hash=%s' % str(s_hash))
                    break

                # get next state and reward
                sn_hash, reward = self.environment.get_action_snext_reward(
                    s_hash, a_desc)
            else:
                # retracing an existing episode
                s_hash, a_desc, reward, sn_hash = next(iter_sarsn)

            if self.learn_tracker is not None:
                self.learn_tracker.add_sarsn_to_current_episode(
                    s_hash, a_desc, reward, sn_hash)

            if sn_hash is None:
                print('break for sn_hash==None, #steps=', n_steps_in_episode,
                      ' s_hash=%s' % str(s_hash), ' a_desc=%s' % str(a_desc))
                break

            # do RL update of Q(s,a) value
            self.action_value_coll.qlearning_update(s_hash=s_hash,
                                                    a_desc=a_desc,
                                                    sn_hash=sn_hash,
                                                    alpha=self.alpha_obj(),
                                                    gamma=self.gamma,
                                                    reward=reward)
            self.num_updates += 1
            # give the above experience to the model
            self.model.add_action(s_hash, a_desc)

            # force DETERMINISTIC next state and reward.
            self.model.save_deterministic_action_results(s_hash,
                                                         a_desc,
                                                         sn_hash,
                                                         reward_val=reward)

            # do NOT use simple save_action_results... it allows NON-DETERMINISTIC next state.
            #self.model.save_action_results( s_hash, a_desc, sn_hash, reward_val=reward)

            # --------------------------------- Planning Loop ------------------------
            # make Nplanning_loops calls to model
            for n_plan in range(Nplanning_loops):
                s_model = self.model.get_random_state()
                #print(s_model, end=' ')

                # vanilla DynaQ
                a_model = self.model.get_random_action(s_model)

                #sn_model, r_model = self.environment.get_action_snext_reward( s_model, a_model )
                sn_model, r_model = self.model.get_sample_sn_r(
                    s_model, a_model)

                # update for the DynaQ  results.
                self.action_value_coll.qlearning_update(s_hash=s_model,
                                                        a_desc=a_model,
                                                        sn_hash=sn_model,
                                                        alpha=self.alpha_obj(),
                                                        gamma=self.gamma,
                                                        reward=r_model)
                self.num_updates += 1

            # keep a lid on the max number of episode steps.
            if n_steps_in_episode >= self.max_episode_steps:
                break

            # get ready for next loop
            n_steps_in_episode += 1
            s_hash = sn_hash

        #print(n_steps_in_episode, end=' ')

    def summ_print(self, long=True):  # pragma: no cover
        """Show State objects in sorted state_hash order."""
        print('___ Policy Evaluation Agent Summary ___')
        print('    Environment        = %s' % self.environment.name)
        print('    Number of Episodes = %g' % self.num_episodes)