MSCFModel.h

Go to the documentation of this file.

/****************************************************************************/
// Eclipse SUMO, Simulation of Urban MObility; see https://eclipse.dev/sumo
// Copyright (C) 2001-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
/****************************************************************************/
// The car-following model abstraction
/****************************************************************************/
#pragma once
#include <config.h>
 
#include <cmath>
#include <string>
#include <vector>
#include <utils/common/StdDefs.h>
#include <utils/common/LinearApproxHelpers.h>
#include <utils/common/SUMOTime.h>
 
#define INVALID_SPEED 299792458 + 1 // nothing can go faster than the speed of light!
// Factor that the minimum emergency decel is increased by in corresponding situations
#define EMERGENCY_DECEL_AMPLIFIER 1.2
 
// ===========================================================================
// class declarations
// ===========================================================================
class MSVehicleType;
class MSVehicle;
class MSLane;
class MSPerson;
class MSLink;
class OutputDevice;
class SUMOSAXAttributes;
 
 
// ===========================================================================
// class definitions
// ===========================================================================
class MSCFModel {
 
public:
 
    class VehicleVariables {
    public:
        virtual ~VehicleVariables();
 
        virtual void saveState(OutputDevice& out, const MSCFModel& cfm) const;
 
        virtual void loadState(const SUMOSAXAttributes& attrs);
    };
 
    MSCFModel(const MSVehicleType* vtype);
 
 
    virtual ~MSCFModel();
 
 
    enum CalcReason {
        CURRENT,
        FUTURE,
        CURRENT_WAIT,
        LANE_CHANGE
    };
 
 
 
    virtual double finalizeSpeed(MSVehicle* const veh, double vPos) const;
 
 
    virtual double patchSpeedBeforeLC(const MSVehicle* veh, double vMin, double vMax) const {
        UNUSED_PARAMETER(veh);
        UNUSED_PARAMETER(vMin);
        return vMax;
    }
 
    virtual double applyStartupDelay(const MSVehicle* veh, const double vMin, const double vMax, const SUMOTime addTime = 0) const;
 
    virtual double interpolateProfile(const double speed, const std::vector<std::pair<double, double> > profile) const;
 
 
    virtual double freeSpeed(const MSVehicle* const veh, double speed, double seen,
                             double maxSpeed, const bool onInsertion = false, const CalcReason usage = CalcReason::CURRENT) const;
 
 
    virtual double followSpeed(const MSVehicle* const veh, double speed, double gap2pred, double predSpeed,
                               double predMaxDecel, const MSVehicle* const pred = 0, const CalcReason usage = CalcReason::CURRENT) const = 0;
 
 
    virtual double insertionFollowSpeed(const MSVehicle* const veh, double speed, double gap2pred, double predSpeed, double predMaxDecel, const MSVehicle* const pred = 0) const;
 
 
    inline double stopSpeed(const MSVehicle* const veh, const double speed, double gap, const CalcReason usage = CalcReason::CURRENT) const {
        return stopSpeed(veh, speed, gap, myDecel, usage);
    }
 
    virtual double stopSpeed(const MSVehicle* const veh, const double speed, double gap, double decel, const CalcReason usage = CalcReason::CURRENT) const = 0;
 
 
    virtual double insertionStopSpeed(const MSVehicle* const veh, double speed, double gap) const;
 
    virtual double followSpeedTransient(double duration, const MSVehicle* const veh, double speed, double gap2pred, double predSpeed, double predMaxDecel) const;
 
    virtual double interactionGap(const MSVehicle* const veh, double vL) const;
 
 
    virtual double maximumLaneSpeedCF(const MSVehicle* const veh, double maxSpeed, double maxSpeedLane) const {
        double result = MIN2(maxSpeed, maxSpeedLane);
        applyOwnSpeedPerceptionError(veh, result);
        return result;
    }
 
 
    virtual int getModelID() const = 0;
 
 
    virtual MSCFModel* duplicate(const MSVehicleType* vtype) const = 0;
 
 
    virtual VehicleVariables* createVehicleVariables() const {
        return 0;
    }
 
 
    inline double getMaxAccel() const {
        return myAccel;
    }
 
 
    inline double getMaxDecel() const {
        return myDecel;
    }
 
 
    inline double getEmergencyDecel() const {
        return myEmergencyDecel;
    }
 
 
    inline double getApparentDecel() const {
        return myApparentDecel;
    }
 
 
    inline SUMOTime getStartupDelay() const {
        return myStartupDelay;
    }
 
    virtual double getCurrentAccel(const double speed) const;
 
 
    inline LinearApproxHelpers::LinearApproxMap getMaxAccelProfile() const {
        return myMaxAccelProfile;
    }
 
 
    inline LinearApproxHelpers::LinearApproxMap getDesAccelProfile() const {
        return myDesAccelProfile;
    }
 
 
    inline double getCollisionMinGapFactor() const {
        return myCollisionMinGapFactor;
    }
 
 
    virtual double getImperfection() const {
        return -1;
    }
 
 
    virtual double getHeadwayTime() const {
        return myHeadwayTime;
    }
 
    virtual bool startupDelayStopped() const {
        return false;
    }
 
 
 
 
 
    virtual double maxNextSpeed(double speed, const MSVehicle* const veh) const;
 
 
    inline virtual double maxNextSafeMin(double speed, const MSVehicle* const veh = 0) const {
        return maxNextSpeed(speed, veh);
    }
 
 
    virtual double minNextSpeed(double speed, const MSVehicle* const veh = 0) const;
 
    virtual double minNextSpeedEmergency(double speed, const MSVehicle* const veh = 0) const;
 
 
    double brakeGap(const double speed) const {
        return brakeGap(speed, myDecel, myHeadwayTime);
    }
 
    virtual double brakeGap(const double speed, const double decel, const double headwayTime) const;
 
    static double brakeGapEuler(const double speed, const double decel, const double headwayTime);
 
    static double freeSpeed(const double currentSpeed, const double decel, const double dist, const double maxSpeed, const bool onInsertion, const double actionStepLength);
 
    virtual double getSecureGap(const MSVehicle* const veh, const MSVehicle* const /*pred*/, const double speed, const double leaderSpeed, const double leaderMaxDecel) const;
 
    virtual 
    inline double getSpeedAfterMaxDecel(double v) const {
        return MAX2(0., v - ACCEL2SPEED(myDecel));
    }
 
    SUMOTime getMinimalArrivalTime(double dist, double currentSpeed, double arrivalSpeed) const;
 
 
    static double estimateArrivalTime(double dist, double speed, double maxSpeed, double accel);
 
    static double estimateArrivalTime(double dist, double initialSpeed, double arrivalSpeed, double maxSpeed, double accel, double decel);
 
    static double avoidArrivalAccel(double dist, double time, double speed, double maxDecel);
 
 
    double getMinimalArrivalSpeed(double dist, double currentSpeed) const;
 
    double getMinimalArrivalSpeedEuler(double dist, double currentSpeed) const;
 
 
    static double gapExtrapolation(const double duration, const double currentGap, double v1,  double v2, double a1 = 0, double a2 = 0, const double maxV1 = std::numeric_limits<double>::max(), const double maxV2 = std::numeric_limits<double>::max());
 
    static double passingTime(const double lastPos, const double passedPos, const double currentPos, const double lastSpeed, const double currentSpeed);
 
 
 
    static double speedAfterTime(const double t, const double oldSpeed, const double dist);
 
 
    virtual double distAfterTime(double t, double speed, double accel) const;
 
 
 
    /* @brief estimate speed while accelerating for the given distance
     * @param[in] dist The distance during which accelerating takes place
     * @param[in] v The initial speed
     * @param[in] accel The acceleration
     * XXX affected by ticket #860 (the formula is invalid for the Euler position update rule)
     * XXX (Leo) Migrated estimateSpeedAfterDistance() to MSCFModel from MSVehicle as Jakob suggested (removed inline property, because myType is fw-declared)
     */
    double estimateSpeedAfterDistance(const double dist, const double v, const double accel) const;
 
 
    virtual void setMaxAccel(double accel) {
        myAccel = accel;
    }
 
 
    virtual void setMaxDecel(double decel) {
        myDecel = decel;
    }
 
 
    virtual void setEmergencyDecel(double decel) {
        myEmergencyDecel = decel;
    }
 
 
    virtual void setApparentDecel(double decel) {
        myApparentDecel = decel;
    }
 
 
    inline void setCollisionMinGapFactor(const double factor) {
        myCollisionMinGapFactor = factor;
    }
 
 
    virtual void setMaxAccelProfile(const LinearApproxHelpers::LinearApproxMap& accelProfile) {
        myMaxAccelProfile = accelProfile;
    }
 
    virtual void setDesAccelProfile(const LinearApproxHelpers::LinearApproxMap&  accelProfile) {
        myDesAccelProfile = accelProfile;
    }
 
 
    virtual void setImperfection(double imperfection) {
        UNUSED_PARAMETER(imperfection);
    }
 
 
    virtual void setHeadwayTime(double headwayTime) {
        myHeadwayTime = headwayTime;
    }
 
    double maximumSafeFollowSpeed(double gap,  double egoSpeed, double predSpeed, double predMaxDecel, bool onInsertion = false) const;
 
 
    double calculateEmergencyDeceleration(double gap, double egoSpeed, double predSpeed, double predMaxDecel) const;
 
 
    double maximumSafeStopSpeed(double gap, double decel, double currentSpeed, bool onInsertion = false, double headway = -1, bool relaxEmergency = true) const;
 
 
    double maximumSafeStopSpeedEuler(double gap, double decel, bool onInsertion, double headway) const;
 
 
    double maximumSafeStopSpeedBallistic(double gap, double decel, double currentSpeed, bool onInsertion = false, double headway = -1) const;
 
    virtual std::string getParameter(const MSVehicle* veh, const std::string& key) const {
        UNUSED_PARAMETER(veh);
        UNUSED_PARAMETER(key);
        return "";
    }
 
    virtual void setParameter(MSVehicle* veh, const std::string& key, const std::string& value) const {
        UNUSED_PARAMETER(veh);
        UNUSED_PARAMETER(key);
        UNUSED_PARAMETER(value);
        throw InvalidArgument("Setting parameter '" + key + "' is not supported by carFollowModel");
    }
 
protected:
 
    void applyOwnSpeedPerceptionError(const MSVehicle* const veh, double& speed) const;
 
    void applyHeadwayAndSpeedDifferencePerceptionErrors(const MSVehicle* const veh, double speed, double& gap, double& predSpeed, double predMaxDecel, const MSVehicle* const pred) const;
 
    void applyHeadwayPerceptionError(const MSVehicle* const veh, double speed, double& gap) const;
 
 
protected:
    const MSVehicleType* myType;
 
    double myAccel;
 
    double myDecel;
    double myEmergencyDecel;
    double myApparentDecel;
    double myCollisionMinGapFactor;
 
    double myHeadwayTime;
 
    SUMOTime myStartupDelay;
 
    LinearApproxHelpers::LinearApproxMap myMaxAccelProfile;
 
    LinearApproxHelpers::LinearApproxMap myDesAccelProfile;
 
 
 
};