MSAbstractLaneChangeModel.h

Go to the documentation of this file.

/****************************************************************************/
// Eclipse SUMO, Simulation of Urban MObility; see https://eclipse.dev/sumo
// Copyright (C) 2001-2024 German Aerospace Center (DLR) and others.
// This program and the accompanying materials are made available under the
// terms of the Eclipse Public License 2.0 which is available at
// https://www.eclipse.org/legal/epl-2.0/
// This Source Code may also be made available under the following Secondary
// Licenses when the conditions for such availability set forth in the Eclipse
// Public License 2.0 are satisfied: GNU General Public License, version 2
// or later which is available at
// https://www.gnu.org/licenses/old-licenses/gpl-2.0-standalone.html
// SPDX-License-Identifier: EPL-2.0 OR GPL-2.0-or-later
/****************************************************************************/
// Interface for lane-change models
/****************************************************************************/
#pragma once
#include <config.h>
 
#include <microsim/MSGlobals.h>
#include <microsim/MSLeaderInfo.h>
#include <microsim/MSVehicle.h>
 
 
// ===========================================================================
// class declarations
// ===========================================================================
class MSLane;
class SUMOSAXAttributes;
 
 
// ===========================================================================
// 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);
 
    virtual LaneChangeModel getModelID() const = 0;
 
    virtual void saveState(OutputDevice& out) const;
 
    virtual void loadState(const SUMOSAXAttributes& attrs);
 
    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;
    double getPreviousManeuverDist() const;
 
    virtual void updateSafeLatDist(const double travelledLatDist);
 
    const std::pair<int, int>& getSavedState(const int dir) const {
        if (dir == -1) {
            return mySavedStateRight;
        } else if (dir == 0) {
            return mySavedStateCenter;
        } else {
            return mySavedStateLeft;
        }
    }
 
    void saveLCState(const int dir, int stateWithoutTraCI, const int state) {
        int canceledStrategic = getCanceledState(dir);
        // avoid conflicting directions
        if ((canceledStrategic & LCA_WANTS_LANECHANGE_OR_STAY) != 0) {
            stateWithoutTraCI = canceledStrategic;
        }
        const auto pair = std::make_pair(stateWithoutTraCI, state);
        if (dir == -1) {
            mySavedStateRight = pair;
        } else if (dir == 0) {
            mySavedStateCenter = pair;
        } else {
            mySavedStateLeft = pair;
        }
    }
 
    void saveNeighbors(const int dir, const MSLeaderDistanceInfo& followers, const MSLeaderDistanceInfo& leaders);
 
    void saveNeighbors(const int dir, const std::pair<MSVehicle* const, double>& follower, const std::pair<MSVehicle* const, double>& leader);
 
    void clearNeighbors();
 
    const std::shared_ptr<MSLeaderDistanceInfo> getFollowers(const int dir);
 
    const std::shared_ptr<MSLeaderDistanceInfo> getLeaders(const int dir);
 
    int& getCanceledState(const int dir) {
        if (dir == -1) {
            return myCanceledStateRight;
        } else if (dir == 0) {
            return myCanceledStateCenter;
        } else {
            return myCanceledStateLeft;
        }
    }
 
    bool isStrategicBlocked() const;
 
    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();
 
    virtual int wantsChange(
        int laneOffset,
        MSAbstractLaneChangeModel::MSLCMessager& msgPass, int blocked,
        const std::pair<MSVehicle*, double>& leader,
        const std::pair<MSVehicle*, double>& follower,
        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(&follower);
        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;
 
    /* @brief called once when the vehicle moves to a new lane in an "irregular"  way (i.e. by teleporting)
     * resets custom variables of each child implementation */
    virtual void resetState() {};
 
    virtual double getSafetyFactor() const {
        return 1.0;
    }
 
    virtual double getOppositeSafetyFactor() 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;
 
    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, bool urgent) 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 calcAngleOffset();
 
    inline double getAngleOffset() const {
        return myAngleOffset;
    }
 
    inline void setAngleOffset(const double angleOffset) {
        myAngleOffset = angleOffset;
    }
 
    inline void setPreviousAngleOffset(const double angleOffset) {
        myPreviousAngleOffset = angleOffset;
    }
 
    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. */
    MSLane* 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 bool saveBlockerLength(double /* length */, double /* foeLeftSpace */) {
        return true;
    }
 
    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, double maneuverDist = 0);
 
    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;
    }
 
    int getNormalizedLaneIndex();
 
    double getCommittedSpeed() const {
        return myCommittedSpeed;
    }
 
    double getSpeedLat() const {
        return mySpeedLat;
    }
 
    /* @brief reset the angle (in case no lane changing happens in this step
     * and the maneuver was finished in the previous step) */
    virtual void resetSpeedLat();
 
    double getAccelerationLat() const {
        return myAccelerationLat;
    }
 
    void setSpeedLat(double speedLat);
 
    virtual double computeSpeedLat(double latDist, double& maneuverDist, bool urgent) const;
 
    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) + "'");
    }
 
    virtual double getExtraReservation(int /*bestLaneOffset*/) const {
        return 0;
    }
 
    void checkTraCICommands();
 
    double getForwardPos() const;
 
    bool hasBlueLight() const {
        return myHaveBlueLight;
    }
 
    virtual LatAlignmentDefinition getDesiredAlignment() const {
        return myVehicle.getVehicleType().getPreferredLateralAlignment();
    }
 
    static const double NO_NEIGHBOR;
 
protected:
    virtual bool congested(const MSVehicle* const neighLeader);
 
    virtual bool predInteraction(const std::pair<MSVehicle*, double>& leader);
 
    virtual bool avoidOvertakeRight() const;
 
    bool cancelRequest(int state, int laneOffset);
 
    double getMaxSpeedLat2() const;
 
    void addLCSpeedAdvice(const double vSafe, bool ownAdvice = true);
 
 
protected:
    MSVehicle& myVehicle;
 
    int myOwnState;
    int myPreviousState;
    int myPreviousState2;
 
    std::pair<int, int> mySavedStateRight;
    std::pair<int, int> mySavedStateCenter;
    std::pair<int, int> mySavedStateLeft;
    int myCanceledStateRight;
    int myCanceledStateCenter;
    int myCanceledStateLeft;
 
    std::shared_ptr<MSLeaderDistanceInfo> myLeftFollowers;
    std::shared_ptr<MSLeaderDistanceInfo> myLeftLeaders;
    std::shared_ptr<MSLeaderDistanceInfo> myRightFollowers;
    std::shared_ptr<MSLeaderDistanceInfo> myRightLeaders;
 
    double mySpeedLat;
 
    double myAccelerationLat;
 
    double myAngleOffset;
 
    double myPreviousAngleOffset;
 
    double myCommittedSpeed;
 
    double myLaneChangeCompletion;
 
    int myLaneChangeDirection;
 
    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;
 
    inline const MSCFModel& getCarFollowModel() const {
        return myVehicle.getCarFollowModel();
    }
 
    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;
    double myLastLeaderSpeed;
    double myLastFollowerSpeed;
    double myLastOrigLeaderSpeed;
 
    bool myDontResetLCGaps;
 
    // @brief the maximum lateral speed for non-strategic changes when standing
    double myMaxSpeedLatStanding;
    // @brief the factor of maximum lateral speed to longitudinal speed for non-strategic changes
    double myMaxSpeedLatFactor;
    // @brief the maximum lateral maneuver distance when standing
    double myMaxDistLatStanding;
    // @brief factor for lane keeping imperfection
    double mySigma;
    // allow overtaking right even though it is prohibited
    double myOvertakeRightParam;
 
    bool myHaveBlueLight;
 
    /* @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);
 
    /* @brief vector of LC-related acceleration recommendations combined with a
     * boolean to indicate whether the advice is from ego or someone else.
     * Filled in wantsChange() and applied in patchSpeed() */
    std::vector<std::pair<double, bool> > myLCAccelerationAdvices;
 
    static bool myAllowOvertakingRight;
 
    static bool myLCOutput;
    static bool myLCStartedOutput;
    static bool myLCEndedOutput;
    static bool myLCXYOutput;
 
 
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;
 
    double myManeuverDist;
 
    double myPreviousManeuverDist;
 
 
private:
    MSAbstractLaneChangeModel& operator=(const MSAbstractLaneChangeModel& s);
};