MSLink.h

Go to the documentation of this file.

/****************************************************************************/
// Eclipse SUMO, Simulation of Urban MObility; see https://eclipse.dev/sumo
// Copyright (C) 2002-2026 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
/****************************************************************************/
// A connection between lanes
/****************************************************************************/
#pragma once
#include <config.h>
 
#include <vector>
#include <set>
#include <utils/common/SUMOTime.h>
#include <utils/common/SUMOVehicleClass.h>
#include <utils/vehicle/SUMOVehicle.h>
#include <utils/xml/SUMOXMLDefinitions.h>
#include "MSLane.h"
 
 
// ===========================================================================
// class declarations
// ===========================================================================
class MSLane;
class MSJunction;
class MSVehicle;
class MSPerson;
class OutputDevice;
class MSTrafficLightLogic;
 
 
// ===========================================================================
// class definitions
// ===========================================================================
class MSLink {
public:
 
    enum LinkLeaderFlag {
        LL_IN_THE_WAY = 1 << 0,
        LL_FROM_LEFT = 1 << 1,
        LL_SAME_SOURCE = 1 << 2,
        LL_SAME_TARGET = 1 << 3
    };
 
    struct LinkLeader {
        LinkLeader(MSVehicle* _veh, double _gap, double _distToCrossing, int _llFlags = LL_FROM_LEFT, double _latOffst = 0) :
            vehAndGap(std::make_pair(_veh, _gap)),
            distToCrossing(_distToCrossing),
            llFlags(_llFlags),
            latOffset(_latOffst)
        { }
 
        inline bool fromLeft() const {
            return (llFlags & LL_FROM_LEFT) != 0;
        }
        inline bool inTheWay() const {
            return (llFlags & LL_IN_THE_WAY) != 0;
        }
        inline bool sameTarget() const {
            return (llFlags & LL_SAME_TARGET) != 0;
        }
        inline bool sameSource() const {
            return (llFlags & LL_SAME_SOURCE) != 0;
        }
 
        std::pair<MSVehicle*, double> vehAndGap;
        double distToCrossing;
        int llFlags;
        double latOffset;
 
    };
 
    typedef std::vector<LinkLeader> LinkLeaders;
 
    struct ApproachingVehicleInformation {
        ApproachingVehicleInformation(const SUMOTime _arrivalTime, const SUMOTime _leavingTime,
                                      const double _arrivalSpeed, const double _leaveSpeed,
                                      const bool _willPass,
                                      const double _arrivalSpeedBraking,
                                      const SUMOTime _waitingTime,
                                      const double _dist,
                                      const double _speed,
                                      const double _latOffset
                                     ) :
            arrivalTime(_arrivalTime), leavingTime(_leavingTime),
            arrivalSpeed(_arrivalSpeed), leaveSpeed(_leaveSpeed),
            willPass(_willPass),
            arrivalSpeedBraking(_arrivalSpeedBraking),
            waitingTime(_waitingTime),
            dist(_dist),
            speed(_speed),
            latOffset(_latOffset) {
        }
 
        const SUMOTime arrivalTime;
        const SUMOTime leavingTime;
        const double arrivalSpeed;
        const double leaveSpeed;
        const bool willPass;
        const double arrivalSpeedBraking;
        const SUMOTime waitingTime;
        const double dist;
        const double speed;
        const double latOffset;
 
    };
 
    struct ApproachingPersonInformation {
        ApproachingPersonInformation(const SUMOTime _arrivalTime, const SUMOTime _leavingTime) :
            arrivalTime(_arrivalTime), leavingTime(_leavingTime) {}
        const SUMOTime arrivalTime;
        const SUMOTime leavingTime;
    };
 
    typedef std::map<const SUMOVehicle*, const ApproachingVehicleInformation, ComparatorNumericalIdLess> ApproachInfos;
    typedef std::vector<const SUMOTrafficObject*> BlockingFoes;
    typedef std::map<const MSPerson*, ApproachingPersonInformation> PersonApproachInfos;
 
    enum ConflictFlag {
        CONFLICT_DEFAULT,
        CONFLICT_DUMMY_MERGE,
        CONFLICT_NO_INTERSECTION,
        CONFLICT_STOP_AT_INTERNAL_JUNCTION,
        CONFLICT_SIBLING_CONTINUATION
    };
 
    struct ConflictInfo {
 
        ConflictInfo(double lbc, double cs, ConflictFlag fl = CONFLICT_DEFAULT) :
            foeConflictIndex(-1),
            lengthBehindCrossing(lbc),
            conflictSize(cs),
            flag(fl)
        {}
        int foeConflictIndex;
        double lengthBehindCrossing;
        double conflictSize;
 
        ConflictFlag flag;
 
        double getFoeLengthBehindCrossing(const MSLink* foeExitLink) const;
        double getFoeConflictSize(const MSLink* foeExitLink) const;
        double getLengthBehindCrossing(const MSLink* exitLink) const;
    };
 
    struct CustomConflict {
        CustomConflict(const MSLane* f, const MSLane* t, double s, double e) :
            from(f), to(t), startPos(s), endPos(e) {}
        const MSLane* from;
        const MSLane* to;
        double startPos;
        double endPos;
    };
 
    struct ComparatorNumericalLaneIdLess {
        bool operator()(const MSLink* const a, const MSLink* const b) const {
            return (a->getLane()->getNumericalID() < b->getLane()->getNumericalID())
                   || (a->getLane()->getNumericalID() == b->getLane()->getNumericalID() && a->getIndex() < b->getIndex());
        }
    };
 
 
    MSLink(MSLane* predLane,
           MSLane* succLane,
           MSLane* via,
           LinkDirection dir,
           LinkState state,
           double length,
           double foeVisibilityDistance,
           bool keepClear,
           MSTrafficLightLogic* logic,
           int tlLinkIdx,
           bool indirect);
 
 
    ~MSLink();
 
    void addCustomConflict(const MSLane* from, const MSLane* to, double startPos, double endPos);
 
    void setRequestInformation(int index, bool hasFoes, bool isCont,
                               const std::vector<MSLink*>& foeLinks, const std::vector<MSLane*>& foeLanes,
                               MSLane* internalLaneBefore = 0);
 
    void addWalkingAreaFoe(const MSLane* lane) {
        myWalkingAreaFoe = lane;
    }
 
    void addWalkingAreaFoeExit(const MSLane* lane) {
        myWalkingAreaFoeExit = lane;
    }
 
    const MSLane* getWalkingAreaFoe() {
        return myWalkingAreaFoe;
    }
    const MSLane* getWalkingAreaFoeExit() {
        return myWalkingAreaFoeExit;
    }
 
    void setApproaching(const SUMOVehicle* approaching, const SUMOTime arrivalTime,
                        const double arrivalSpeed, const double leaveSpeed, const bool setRequest,
                        const double arrivalSpeedBraking,
                        const SUMOTime waitingTime, double dist, double latOffset);
 
    void setApproaching(const SUMOVehicle* approaching, ApproachingVehicleInformation ai);
 
    void setApproachingPerson(const MSPerson* approaching, const SUMOTime arrivalTime, const SUMOTime leaveTime);
 
    void removeApproaching(const SUMOVehicle* veh);
 
    void removeApproachingPerson(const MSPerson* person);
 
    /* @brief return information about this vehicle if it is registered as
     * approaching (dummy values otherwise)
     * @note used for visualisation of link items */
    ApproachingVehicleInformation getApproaching(const SUMOVehicle* veh) const;
    const ApproachingVehicleInformation* getApproachingPtr(const SUMOVehicle* veh) const;
 
    const ApproachInfos& getApproaching() const {
        return myApproachingVehicles;
    }
 
    const PersonApproachInfos* getApproachingPersons() const {
        return myApproachingPersons;
    }
 
    void clearState();
 
    bool opened(SUMOTime arrivalTime, double arrivalSpeed, double leaveSpeed, double vehicleLength,
                double impatience, double decel, SUMOTime waitingTime,
                double posLat = 0,
                BlockingFoes* collectFoes = nullptr,
                bool ignoreRed = false,
                const SUMOTrafficObject* ego = nullptr,
                double dist = -1) const;
 
    bool blockedAtTime(SUMOTime arrivalTime, SUMOTime leaveTime, double arrivalSpeed, double leaveSpeed,
                       bool sameTargetLane, double impatience, double decel, SUMOTime waitingTime,
                       BlockingFoes* collectFoes = nullptr, const SUMOTrafficObject* ego = nullptr, bool lastWasContRed = false, double dist = -1) const;
 
 
    bool hasApproachingFoe(SUMOTime arrivalTime, SUMOTime leaveTime, double speed, double decel) const;
 
    std::pair<const SUMOVehicle*, const MSLink*>  getFirstApproachingFoe(const MSLink* wrapAround) const;
 
    MSJunction* getJunction() const {
        return myJunction;
    }
 
 
    LinkState getState() const {
        return myState;
    }
 
 
    LinkState getOffState() const {
        return myOffState;
    }
 
    LinkState getLastGreenState() const {
        return myLastGreenState;
    }
 
 
    //@brief Returns the time of the last state change
    inline SUMOTime getLastStateChange() const {
        return myLastStateChange;
    }
 
 
    inline LinkDirection getDirection() const {
        return myDirection;
    }
 
 
 
    void setTLState(LinkState state, SUMOTime t);
 
    void setTLLogic(const MSTrafficLightLogic* logic);
 
    inline MSLane* getLane() const {
        return myLane;
    }
 
 
    inline int getIndex() const {
        return myIndex;
    }
 
    inline int getTLIndex() const {
        return myTLIndex;
    }
 
    inline const MSTrafficLightLogic* getTLLogic() const {
        return myLogic;
    }
 
    inline bool havePriority() const {
        return myState >= 'A' && myState <= 'Z';
    }
 
    inline bool haveOffPriority() const {
        return myOffState >= 'A' && myOffState <= 'Z';
    }
 
    inline bool haveRed() const {
        return myState == LINKSTATE_TL_RED || myState == LINKSTATE_TL_REDYELLOW;
    }
 
    inline bool haveYellow() const {
        return myState == LINKSTATE_TL_YELLOW_MINOR || myState == LINKSTATE_TL_YELLOW_MAJOR;
    }
 
    inline bool haveGreen() const {
        return myState == LINKSTATE_TL_GREEN_MAJOR || myState == LINKSTATE_TL_GREEN_MINOR;
    }
 
    inline bool mustStop() const {
        return myState == LINKSTATE_STOP || myState == LINKSTATE_ALLWAY_STOP;
    }
 
    inline bool isTLSControlled() const {
        return myLogic != 0;
    }
 
    inline bool isTurnaround() const {
        return myDirection == LinkDirection::TURN || myDirection == LinkDirection::TURN_LEFTHAND;
    }
 
    double getLength() const {
        return myLength;
    }
 
 
    double getFoeVisibilityDistance() const {
        return myFoeVisibilityDistance;
    }
 
    double getDistToFoePedCrossing() const {
        return myDistToFoePedCrossing;
    }
 
    bool hasFoes() const {
        return myHasFoes;
    }
 
    // @brief return whether the vehicle may continute past this link to wait within the intersection
    bool isCont() const;
 
 
    bool keepClear() const {
        return myKeepClear;
    }
 
    bool isIndirect() const {
        return myAmIndirect;
    }
 
    bool lastWasContMajor() const;
 
    bool lastWasContState(LinkState linkState) const;
 
    double getInternalLengthsAfter() const;
 
    double getInternalLengthsBefore() const;
 
    double getLengthsBeforeCrossing(const MSLane* foeLane) const;
 
 
    double getLengthBeforeCrossing(const MSLane* foeLane) const;
 
 
    inline MSLane* getViaLane() const {
        return myInternalLane;
    }
 
    const LinkLeaders getLeaderInfo(const MSVehicle* ego, double dist, std::vector<const MSPerson*>* collectBlockers = 0, bool isShadowLink = false) const;
 
    double getZipperSpeed(const MSVehicle* ego, const double dist, double vSafe,
                          SUMOTime arrivalTime,
                          const BlockingFoes* foes) const;
 
    inline MSLane* getViaLaneOrLane() const {
        return  myInternalLane != nullptr ? myInternalLane : myLane;
    }
 
 
    inline const MSLane* getLaneBefore() const {
        assert(myInternalLaneBefore == nullptr || myLaneBefore == myInternalLaneBefore);  // lane before mismatch!
        return myLaneBefore;
    }
 
    inline const MSLane* getInternalLaneBefore() const {
        return myInternalLaneBefore;
    }
 
    SUMOTime getLeaveTime(const SUMOTime arrivalTime, const double arrivalSpeed, const double leaveSpeed, const double vehicleLength) const;
 
    void writeApproaching(OutputDevice& od, const std::string fromLaneID) const;
 
    MSLink* getParallelLink(int direction) const;
 
    MSLink* getOppositeDirectionLink() const;
 
    inline bool fromInternalLane() const {
        return myInternalLaneBefore != nullptr;
    }
 
    bool isEntryLink() const;
 
    bool isConflictEntryLink() const;
 
    bool isExitLink() const;
 
    bool isExitLinkAfterInternalJunction() const;
 
    const MSLink* getCorrespondingExitLink() const;
 
    const MSLink* getCorrespondingEntryLink() const;
 
    bool isInternalJunctionLink() const;
 
    SUMOTime getMesoTLSPenalty() const {
        return myMesoTLSPenalty;
    }
 
    double getGreenFraction() const {
        return myGreenFraction;
    }
 
    void setMesoTLSPenalty(const SUMOTime penalty) {
        myMesoTLSPenalty = penalty;
    }
 
    void setGreenFraction(const double fraction) {
        myGreenFraction = fraction;
    }
 
    const std::vector<const MSLane*>& getFoeLanes() const {
        return myFoeLanes;
    }
 
    const std::vector<ConflictInfo>& getConflicts() const {
        return myConflicts;
    }
 
    const std::vector<MSLink*>& getFoeLinks() const {
        return myFoeLinks;
    }
 
    SVCPermissions getPermissions() const {
        return myPermissions;
    }
 
    void initParallelLinks();
 
    inline double getLateralShift() const {
        return myLateralShift;
    }
 
    std::string  getDescription() const;
 
    std::pair<const SUMOVehicle* const, const ApproachingVehicleInformation> getClosest() const;
 
    inline bool hasFoeCrossing() const {
        return myHavePedestrianCrossingFoe;
    }
 
    bool railSignalWasPassed() const;
 
    static void recheckSetRequestInformation();
 
    static bool ignoreFoe(const SUMOTrafficObject* ego, const SUMOTrafficObject* foe);
 
    static const double NO_INTERSECTION;
 
private:
    static inline bool unsafeMergeSpeeds(double leaderSpeed, double followerSpeed, double leaderDecel, double followerDecel) {
        // XXX mismatch between continuous an discrete deceleration
        return (leaderSpeed * leaderSpeed / leaderDecel) <= (followerSpeed * followerSpeed / followerDecel);
    }
 
    static bool couldBrakeForLeader(double followDist, double leaderDist, const MSVehicle* follow, const MSVehicle* leader);
 
    MSLink* computeParallelLink(int direction);
 
    void checkWalkingAreaFoe(const MSVehicle* ego, const MSLane* foeLane, std::vector<const MSPerson*>* collectBlockers, LinkLeaders& result) const;
 
    bool isInFront(const MSVehicle* ego, const PositionVector& egoPath, const Position& pPos) const;
 
    double isOnComingPed(const MSVehicle* ego, const MSPerson* p) const;
 
    Position getFuturePosition(const MSPerson* p, double timeHorizon = 1) const;
 
    bool blockedByFoe(const SUMOVehicle* veh, const ApproachingVehicleInformation& avi,
                      SUMOTime arrivalTime, SUMOTime leaveTime, double arrivalSpeed, double leaveSpeed,
                      bool sameTargetLane, double impatience, double decel, SUMOTime waitingTime,
                      const SUMOTrafficObject* ego) const;
 
    bool checkContOff() const;
 
    bool contIntersect(const MSLane* lane, const MSLane* foe);
 
    double computeDistToDivergence(const MSLane* lane, const MSLane* sibling, double minDist, bool sameSource, double siblingPredLength = 0) const;
 
    static SUMOTime computeFoeArrivalTimeBraking(SUMOTime arrivalTime, const SUMOVehicle* foe, SUMOTime foeArrivalTime, double impatience, double dist, double& fasb);
 
    static bool lateralOverlap(double posLat, double width, double posLat2, double width2);
 
    const CustomConflict* getCustomConflict(const MSLane* foeLane) const;
 
    void updateDistToFoePedCrossing(double dist);
 
private:
    MSLane* myLane;
 
    MSLane* myLaneBefore;
 
    ApproachInfos myApproachingVehicles;
    PersonApproachInfos* myApproachingPersons;
 
    int myIndex;
 
    const int myTLIndex;
 
    const MSTrafficLightLogic* myLogic;
 
    LinkState myState;
    LinkState myLastGreenState;
    const LinkState myOffState;
 
    SUMOTime myLastStateChange;
 
    LinkDirection myDirection;
 
    double myLength;
 
    double myFoeVisibilityDistance;
 
    double myDistToFoePedCrossing;
 
    bool myHasFoes;
 
    // @brief whether vehicles may continue past this link to wait within the intersection
    bool myAmCont;
    // @brief whether vehicles may continue past this link to wait within the intersection after switching of the traffic light at this intersection
    bool myAmContOff;
 
    // @brief whether vehicles must keep the intersection clear if there is a downstream jam
    bool myKeepClear;
 
    MSLane* const myInternalLane;
 
    /* @brief The preceding junction-internal lane, only used at
     * - exit links (from internal lane to normal lane)
     * - internal junction links (from internal lane to internal lane)
     */
    const MSLane* myInternalLaneBefore;
 
    SUMOTime myMesoTLSPenalty;
    double myGreenFraction;
 
    double myLateralShift;
 
    /* @brief lengths after the crossing point with foeLane
     * (index corresponds to myFoeLanes)
     * empty vector for entry links
     * */
    std::vector<ConflictInfo> myConflicts;
 
    std::vector<CustomConflict> myCustomConflicts;
 
    // TODO: documentation
    std::vector<MSLink*> myFoeLinks;
    std::vector<const MSLane*> myFoeLanes;
 
    /* prioritized links when the traffic light is switched off (only needed for RightOfWay::ALLWAYSTOP)
     * @note stored as a pointer to save space since it won't be used in most cases
     */
    std::vector<MSLink*>* myOffFoeLinks;
 
    const MSLane* myWalkingAreaFoe;
    const MSLane* myWalkingAreaFoeExit;
 
    bool myHavePedestrianCrossingFoe;
 
    /* @brief Links with the same origin lane and the same destination edge that may
       be in conflict for sublane simulation */
    std::vector<MSLink*> mySublaneFoeLinks;
    /* @brief Links with the same origin lane and different destination edge that may
       be in conflict for sublane simulation */
    std::vector<MSLink*> mySublaneFoeLinks2;
 
    /* @brief Internal Lanes with the same origin lane and the same destination edge that may
       be in conflict for sublane simulation */
    std::vector<MSLane*> mySublaneFoeLanes;
 
    static const SUMOTime myLookaheadTime;
    static const SUMOTime myLookaheadTimeZipper;
 
    static std::set<std::pair<MSLink*, MSLink*> > myRecheck;
 
    MSLink* myParallelRight;
    MSLink* myParallelLeft;
 
    const bool myAmIndirect;
 
    double myRadius;
 
    SVCPermissions myPermissions;
 
    MSJunction* myJunction;
 
    MSLink(const MSLink& s);
 
    MSLink& operator=(const MSLink& s);
 
};