MSAbstractLaneChangeModel.h

Go to the documentation of this file.

/****************************************************************************/
// Eclipse SUMO, Simulation of Urban MObility; see https://eclipse.org/sumo
// Copyright (C) 2001-2018 German Aerospace Center (DLR) and others.
// This program and the accompanying materials
// are made available under the terms of the Eclipse Public License v2.0
// which accompanies this distribution, and is available at
// http://www.eclipse.org/legal/epl-v20.html
// SPDX-License-Identifier: EPL-2.0
/****************************************************************************/
// Interface for lane-change models
/****************************************************************************/
#ifndef MSAbstractLaneChangeModel_h
#define MSAbstractLaneChangeModel_h

// ===========================================================================
// included modules
// ===========================================================================
#include <config.h>

#include <microsim/MSGlobals.h>
#include <microsim/MSVehicle.h>

class MSLane;

// ===========================================================================
// used enumeration
// ===========================================================================

// ===========================================================================
// class definitions
// ===========================================================================
class MSAbstractLaneChangeModel {
public:

    class MSLCMessager {
    public:
        MSLCMessager(MSVehicle* leader,  MSVehicle* neighLead, MSVehicle* neighFollow)
            : myLeader(leader), myNeighLeader(neighLead),
              myNeighFollower(neighFollow) { }


        ~MSLCMessager() { }


        void* informLeader(void* info, MSVehicle* sender) {
            assert(myLeader != 0);
            return myLeader->getLaneChangeModel().inform(info, sender);
        }


        void* informNeighLeader(void* info, MSVehicle* sender) {
            assert(myNeighLeader != 0);
            return myNeighLeader->getLaneChangeModel().inform(info, sender);
        }


        void* informNeighFollower(void* info, MSVehicle* sender) {
            assert(myNeighFollower != 0);
            return myNeighFollower->getLaneChangeModel().inform(info, sender);
        }


    private:
        MSVehicle* myLeader;
        MSVehicle* myNeighLeader;
        MSVehicle* myNeighFollower;

    };

    struct StateAndDist {
        // @brief LaneChangeAction flags
        int state;
        // @brief Lateral distance to be completed in the next step
        double latDist;
        // @brief Full lateral distance required for the completion of the envisioned maneuver
        double maneuverDist;
        // @brief direction that was checked
        int dir;

        StateAndDist(int _state, double _latDist, double _targetDist, int _dir) :
            state(_state),
            latDist(_latDist),
            maneuverDist(_targetDist),
            dir(_dir) {}

        bool sameDirection(const StateAndDist& other) const {
            return latDist * other.latDist > 0;
        }
    };

    void static initGlobalOptions(const OptionsCont& oc);

    static MSAbstractLaneChangeModel* build(LaneChangeModel lcm, MSVehicle& vehicle);

    inline static bool haveLateralDynamics() {
        return MSGlobals::gLateralResolution > 0 || MSGlobals::gLaneChangeDuration > 0;
    }

    virtual LaneChangeModel getModelID() const = 0;

    static bool haveLCOutput() {
        return myLCOutput;
    }

    static bool outputLCStarted() {
        return myLCStartedOutput;
    }

    static bool outputLCEnded() {
        return myLCEndedOutput;
    }

    MSAbstractLaneChangeModel(MSVehicle& v, const LaneChangeModel model);

    virtual ~MSAbstractLaneChangeModel();

    inline int getOwnState() const {
        return myOwnState;
    }

    inline int getPrevState() const {
        return myPreviousState2;
    }

    virtual void setOwnState(const int state);

    void setManeuverDist(const double dist);
    double getManeuverDist() const;

    virtual void updateSafeLatDist(const double travelledLatDist);

    const std::pair<int, int>& getSavedState(const int dir) const {
        return mySavedStates.find(dir)->second;
    }

    bool hasSavedState(const int dir) const {
        return mySavedStates.find(dir) != mySavedStates.end();
    }

    void saveLCState(const int dir, const int stateWithoutTraCI, const int state) {
        mySavedStates[dir] = std::make_pair(stateWithoutTraCI | myCanceledStates[dir], state);
    }

    void setFollowerGaps(CLeaderDist follower, double secGap);
    void setLeaderGaps(CLeaderDist, double secGap);
    void setOrigLeaderGaps(CLeaderDist, double secGap);
    void setFollowerGaps(const MSLeaderDistanceInfo& vehicles);
    void setLeaderGaps(const MSLeaderDistanceInfo& vehicles);
    void setOrigLeaderGaps(const MSLeaderDistanceInfo& vehicles);

    virtual void prepareStep() {
        myCanceledStates[-1] = LCA_NONE;
        myCanceledStates[0] = LCA_NONE;
        myCanceledStates[1] = LCA_NONE;
        saveLCState(-1, LCA_UNKNOWN, LCA_UNKNOWN);
        saveLCState(0, LCA_UNKNOWN, LCA_UNKNOWN);
        saveLCState(1, LCA_UNKNOWN, LCA_UNKNOWN);
        myLastLateralGapRight = NO_NEIGHBOR;
        myLastLateralGapLeft = NO_NEIGHBOR;
        if (!myDontResetLCGaps) {
            myLastLeaderGap = NO_NEIGHBOR;
            myLastLeaderSecureGap = NO_NEIGHBOR;
            myLastFollowerGap = NO_NEIGHBOR;
            myLastFollowerSecureGap = NO_NEIGHBOR;
            myLastOrigLeaderGap = NO_NEIGHBOR;
            myLastOrigLeaderSecureGap = NO_NEIGHBOR;
        }
        myCommittedSpeed = 0;
    }

    virtual int wantsChange(
        int laneOffset,
        MSAbstractLaneChangeModel::MSLCMessager& msgPass, int blocked,
        const std::pair<MSVehicle*, double>& leader,
        const std::pair<MSVehicle*, double>& neighLead,
        const std::pair<MSVehicle*, double>& neighFollow,
        const MSLane& neighLane,
        const std::vector<MSVehicle::LaneQ>& preb,
        MSVehicle** lastBlocked,
        MSVehicle** firstBlocked) {
        UNUSED_PARAMETER(laneOffset);
        UNUSED_PARAMETER(&msgPass);
        UNUSED_PARAMETER(blocked);
        UNUSED_PARAMETER(&leader);
        UNUSED_PARAMETER(&neighLead);
        UNUSED_PARAMETER(&neighFollow);
        UNUSED_PARAMETER(&neighLane);
        UNUSED_PARAMETER(&preb);
        UNUSED_PARAMETER(lastBlocked);
        UNUSED_PARAMETER(firstBlocked);
        throw ProcessError("Method not implemented by model " + toString(myModel));
    };

    virtual int wantsChangeSublane(
        int laneOffset,
        LaneChangeAction alternatives,
        const MSLeaderDistanceInfo& leaders,
        const MSLeaderDistanceInfo& followers,
        const MSLeaderDistanceInfo& blockers,
        const MSLeaderDistanceInfo& neighLeaders,
        const MSLeaderDistanceInfo& neighFollowers,
        const MSLeaderDistanceInfo& neighBlockers,
        const MSLane& neighLane,
        const std::vector<MSVehicle::LaneQ>& preb,
        MSVehicle** lastBlocked,
        MSVehicle** firstBlocked,
        double& latDist, double& targetDistLat, int& blocked) {
        UNUSED_PARAMETER(laneOffset);
        UNUSED_PARAMETER(alternatives);
        UNUSED_PARAMETER(&leaders);
        UNUSED_PARAMETER(&followers);
        UNUSED_PARAMETER(&blockers);
        UNUSED_PARAMETER(&neighLeaders);
        UNUSED_PARAMETER(&neighFollowers);
        UNUSED_PARAMETER(&neighBlockers);
        UNUSED_PARAMETER(&neighLane);
        UNUSED_PARAMETER(&preb);
        UNUSED_PARAMETER(lastBlocked);
        UNUSED_PARAMETER(firstBlocked);
        UNUSED_PARAMETER(latDist);
        UNUSED_PARAMETER(targetDistLat);
        UNUSED_PARAMETER(blocked);
        throw ProcessError("Method not implemented by model " + toString(myModel));
    }

    virtual void updateExpectedSublaneSpeeds(const MSLeaderDistanceInfo& ahead, int sublaneOffset, int laneIndex) {
        UNUSED_PARAMETER(&ahead);
        UNUSED_PARAMETER(sublaneOffset);
        UNUSED_PARAMETER(laneIndex);
        throw ProcessError("Method not implemented by model " + toString(myModel));
    }

    virtual StateAndDist decideDirection(StateAndDist sd1, StateAndDist sd2) const {
        UNUSED_PARAMETER(sd1);
        UNUSED_PARAMETER(sd2);
        throw ProcessError("Method not implemented by model " + toString(myModel));
    }

    virtual void* inform(void* info, MSVehicle* sender) = 0;

    virtual double patchSpeed(const double min, const double wanted, const double max,
                              const MSCFModel& cfModel) = 0;

    /* @brief called once when the primary lane of the vehicle changes (updates
     * the custom variables of each child implementation */
    virtual void changed() = 0;


    virtual double getSafetyFactor() const {
        return 1.0;
    }

    virtual bool debugVehicle() const {
        return false;
    }

    void changedToOpposite();

    void unchanged() {
        if (myLastLaneChangeOffset > 0) {
            myLastLaneChangeOffset += DELTA_T;
        } else if (myLastLaneChangeOffset < 0) {
            myLastLaneChangeOffset -= DELTA_T;
        }
    }

    MSLane* getShadowLane() const {
        return myShadowLane;
    }

    MSLane* getShadowLane(const MSLane* lane) const;

    MSLane* getShadowLane(const MSLane* lane, double posLat) const;

    void setShadowLane(MSLane* lane) {
        myShadowLane = lane;
    }

    const std::vector<MSLane*>& getShadowFurtherLanes() const {
        return myShadowFurtherLanes;
    }

    const std::vector<double>& getShadowFurtherLanesPosLat() const {
        return myShadowFurtherLanesPosLat;
    }

    MSLane* getTargetLane() const {
        return myTargetLane;
    }

    const std::vector<MSLane*>& getFurtherTargetLanes() const {
        return myFurtherTargetLanes;
    }

    inline SUMOTime getLastLaneChangeOffset() const {
        return myLastLaneChangeOffset;
    }


    inline bool pastMidpoint() const {
        return myLaneChangeCompletion >= 0.5;
    }

    SUMOTime remainingTime() const;

    virtual double estimateLCDuration(const double speed, const double remainingManeuverDist, const double decel) const;

    inline bool isChangingLanes() const {
        return myLaneChangeCompletion < (1 - NUMERICAL_EPS);
    }

    inline double getLaneChangeCompletion() const {
        return myLaneChangeCompletion;
    }

    inline int getLaneChangeDirection() const {
        return myLaneChangeDirection;
    }

    int getShadowDirection() const;

    double getAngleOffset() const;

    inline bool alreadyChanged() const {
        return myAlreadyChanged;
    }

    void resetChanged() {
        myAlreadyChanged = false;
    }

    bool startLaneChangeManeuver(MSLane* source, MSLane* target, int direction);

    void memorizeGapsAtLCInit();
    void clearGapsAtLCInit();

    /* @brief continue the lane change maneuver and return whether the midpoint
     * was passed in this step
     */
    bool updateCompletion();

    /* @brief update lane change shadow after the vehicle moved to a new lane */
    void updateShadowLane();

    /* @brief update lane change reservations after the vehicle moved to a new lane
     * @note  The shadow lane should always be updated before updating the target lane. */
    void updateTargetLane();

    /* @brief Determines the lane which the vehicle intends to enter during its current action step.
     *        targetDir is set to the offset of the returned lane with respect to the vehicle'a current lane. */
    MSLane* determineTargetLane(int& targetDir) const;

    /* @brief finish the lane change maneuver
     */
    void endLaneChangeManeuver(const MSMoveReminder::Notification reason = MSMoveReminder::NOTIFICATION_LANE_CHANGE);

    /* @brief clean up all references to the shadow vehicle
     */
    void cleanupShadowLane();

    /* @brief clean up all references to the vehicle on its target lanes
     */
    void cleanupTargetLane();

    virtual void saveBlockerLength(double length) {
        UNUSED_PARAMETER(length);
    }

    void setShadowPartialOccupator(MSLane* lane) {
        myPartiallyOccupatedByShadow.push_back(lane);
    }

    void setNoShadowPartialOccupator(MSLane* lane) {
        myNoPartiallyOccupatedByShadow.push_back(lane);
    }

    void primaryLaneChanged(MSLane* source, MSLane* target, int direction);

    void laneChangeOutput(const std::string& tag, MSLane* source, MSLane* target, int direction);

    virtual bool sublaneChangeCompleted(const double latDist) const {
        UNUSED_PARAMETER(latDist);
        throw ProcessError("Method not implemented by model " + toString(myModel));
    }

    void setShadowApproachingInformation(MSLink* link) const;
    void removeShadowApproachingInformation() const;

    bool isOpposite() const {
        return myAmOpposite;
    }

    double getCommittedSpeed() const {
        return myCommittedSpeed;
    }

    double getSpeedLat() const {
        return mySpeedLat;
    }

    void setSpeedLat(double speedLat) {
        mySpeedLat = speedLat;
    }

    virtual double computeSpeedLat(double latDist, double& maneuverDist);

    virtual double getAssumedDecelForLaneChangeDuration() const;

    virtual std::string getParameter(const std::string& key) const {
        throw InvalidArgument("Parameter '" + key + "' is not supported for laneChangeModel of type '" + toString(myModel) + "'");
    }

    virtual void setParameter(const std::string& key, const std::string& value) {
        UNUSED_PARAMETER(value);
        throw InvalidArgument("Setting parameter '" + key + "' is not supported for laneChangeModel of type '" + toString(myModel) + "'");
    }


    void checkTraCICommands();

    static const double NO_NEIGHBOR;

protected:
    virtual bool congested(const MSVehicle* const neighLeader);

    virtual bool predInteraction(const std::pair<MSVehicle*, double>& leader);

    bool cancelRequest(int state, int laneOffset);


protected:
    MSVehicle& myVehicle;

    int myOwnState;
    int myPreviousState;
    int myPreviousState2;

    std::map<int, std::pair<int, int> > mySavedStates;
    std::map<int, int> myCanceledStates;

    double mySpeedLat;

    double myCommittedSpeed;

    double myLaneChangeCompletion;

    int myLaneChangeDirection;

    double myManeuverDist;

    bool myAlreadyChanged;

    MSLane* myShadowLane;
    /* @brief Lanes that are partially (laterally) occupied by the back of the
     * vehicle (analogue to MSVehicle::myFurtherLanes) */
    std::vector<MSLane*> myShadowFurtherLanes;
    std::vector<double> myShadowFurtherLanesPosLat;


    MSLane* myTargetLane;

    /* @brief Further upstream lanes that are affected by the vehicle's maneuver (analogue to MSVehicle::myFurtherLanes)
     * @note  If myTargetLane==nullptr, we may assume myFurtherTargetLanes.size()==0, otherwise we have
     *        myFurtherTargetLanes.size() == myVehicle.getFurtherLanes.size()
     *        Here it may occur that an element myFurtherTargetLanes[i]==nullptr if myFurtherLanes[i] has
     *        no parallel lane in the change direction.
     *  */
    std::vector<MSLane*> myFurtherTargetLanes;

    const MSCFModel& myCarFollowModel;

    const LaneChangeModel myModel;

    std::vector<MSLane*> myPartiallyOccupatedByShadow;

    /* @brief list of lanes where there is no shadow vehicle partial occupator
     * (when changing to a lane that has no predecessor) */
    std::vector<MSLane*> myNoPartiallyOccupatedByShadow;

    double myLastLateralGapLeft;
    double myLastLateralGapRight;

    double myLastLeaderGap;
    double myLastFollowerGap;
    double myLastLeaderSecureGap;
    double myLastFollowerSecureGap;
    double myLastOrigLeaderGap;
    double myLastOrigLeaderSecureGap;

    bool myDontResetLCGaps;

    // @brief the maximum lateral speed when standing
    double myMaxSpeedLatStanding;
    // @brief the factor of maximum lateral speed to longitudinal speed
    double myMaxSpeedLatFactor;

    /* @brief to be called by derived classes in their changed() method.
     * If dir=0 is given, the current value remains unchanged */
    void initLastLaneChangeOffset(int dir);

    static bool myAllowOvertakingRight;

    static bool myLCOutput;
    static bool myLCStartedOutput;
    static bool myLCEndedOutput;


private:
    /* @brief information how long ago the vehicle has performed a lane-change,
     * sign indicates direction of the last change
     */
    SUMOTime myLastLaneChangeOffset;

    mutable std::vector<MSLink*> myApproachedByShadow;

    bool myAmOpposite;


private:
    MSAbstractLaneChangeModel& operator=(const MSAbstractLaneChangeModel& s);
};


#endif

/****************************************************************************/