Program Listing for File ParallelVehicles.h#
↰ Return to documentation for file (include/Karana/GeneralKModels/ParallelVehicles.h)
/*
* Copyright (c) 2024-2026 Karana Dynamics Pty Ltd. All rights reserved.
*
* NOTICE TO USER:
*
* This source code and/or documentation (the "Licensed Materials") is
* the confidential and proprietary information of Karana Dynamics Inc.
* Use of these Licensed Materials is governed by the terms and conditions
* of a separate software license agreement between Karana Dynamics and the
* Licensee ("License Agreement"). Unless expressly permitted under that
* agreement, any reproduction, modification, distribution, or disclosure
* of the Licensed Materials, in whole or in part, to any third party
* without the prior written consent of Karana Dynamics is strictly prohibited.
*
* THE LICENSED MATERIALS ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND.
* KARANA DYNAMICS DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
* BUT NOT LIMITED TO WARRANTIES OF MERCHANTABILITY, NON-INFRINGEMENT, AND
* FITNESS FOR A PARTICULAR PURPOSE.
*
* IN NO EVENT SHALL KARANA DYNAMICS BE LIABLE FOR ANY DAMAGES WHATSOEVER,
* INCLUDING BUT NOT LIMITED TO LOSS OF PROFITS, DATA, OR USE, EVEN IF
* ADVISED OF THE POSSIBILITY OF SUCH DAMAGES, WHETHER IN CONTRACT, TORT,
* OR OTHERWISE ARISING OUT OF OR IN CONNECTION WITH THE LICENSED MATERIALS.
*
* U.S. Government End Users: The Licensed Materials are a "commercial item"
* as defined at 48 C.F.R. 2.101, and are provided to the U.S. Government
* only as a commercial end item under the terms of this license.
*
* Any use of the Licensed Materials in individual or commercial software must
* include, in the user documentation and internal source code comments,
* this Notice, Disclaimer, and U.S. Government Use Provision.
*/
/**
* @file
* @brief Contains the declarations for the ParallelVehicles KModel.
*/
#pragma once
#include "Karana/Math/Defs.h"
#include "Karana/SOADyn/KModel.h"
namespace Karana::Models {
namespace km = Karana::Math;
namespace kd = Karana::Dynamics;
/**
* @class ParallelVehicles
* @brief Run vehicles associated with the provided StatePropagators in parallel.
*
* This KModel runs vehicles in parallel. Each vehicle should be associated with one of the
* provided StatePropagators. For clarity, these StatePropagators will be referred to as vehicle
* StatePropagators. This KModel should be registered on a different
* ModelManager/StatePropagator, which will be referred to as the global StatePropagators. To
* use this KModel, do the following:
* 1. Ensure the Karana::KCore::ThreadPool has a size of at least the number of vehicles + 1.
* The get/setThreadPoolSize methods can be used to do this.
* 2. This model should be registered with the global StatePropagator before any other KModel
* that has a postHop. This ensures that the dynamics of the vehicles run after any `KModel`
* `preHops`s on the global StatePropagator, and before all other `KModel` `postHop`s.
*
* This model should not be used in the following scenarios:
* - Spice frames are present. This will data race issues when the separate vehicles each try to
* update the ephemeris time.
* - Collision/contact. If two vehicles may collide, then they cannot be run in parallel, as
* their dynamics are coupled.
*/
class ParallelVehicles : public KModel<ParallelVehicles> {
public:
/**
* @brief ParallelVehicles constructor. The constructor is not meant to be called directly.
* Please use the create(...) method instead to create an instance.
*
* @param name The name of the model.
* @param mm The ModelManager to register this model with.
*/
ParallelVehicles(std::string_view name, const kc::ks_ptr<kd::ModelManager> &mm);
/**
* @brief Destructor for ParallelVehicles.
*/
~ParallelVehicles();
/**
* @brief Constructor.
*
* @param name The name of the model.
* @param mm The ModelManager to register this model with.
* @param sps The StatePropagators associated with the vehicles that should be run in
* parallel.
* @return A ks_ptr to the newly created instance of the ParallelVehicles model.
*/
static kc::ks_ptr<ParallelVehicles>
create(std::string_view name,
const kc::ks_ptr<kd::ModelManager> &mm,
const std::vector<kc::ks_ptr<kd::StatePropagator>> &sps);
/**
* @brief Temporarily release the GIL so other threads can do work.
*
* @param t Current time.
* @param x Current state. Not used.
*/
void postHop(const km::Ktime &t, const km::Vec &x);
/**
* @brief Get the StatePropagators for the vehicles.
*
* @returns The vehicle StatePropagators.
*/
const std::vector<kc::ks_ptr<kd::StatePropagator>> &getVehicleStatePropagators() const;
/**
* @brief Set the StatePropagators for the vehicles.
* @param sps The StatePropagators to use for the vehicles.
*/
void setVehicleStatePropagators(const std::vector<kc::ks_ptr<kd::StatePropagator>> &sps);
/**
* @brief Get whether this model will run the vehicles in serial or not.
*
* @return True if running in serial, false otherwise.
*/
bool getRunInSerial() const;
/**
* @brief Set whether this model will run the vehicles in serial or not.
*
* Serial mode can be used for debugging, but should remain false (the default)
* when running production code.
*
* @param run_in_serial True to run in serial, false to run in parallel.
*/
void setRunInSerial(bool run_in_serial);
protected:
/**
* @brief Register the model.
*/
void _registerModel() override;
/**
* @brief Unregister the model.
*/
void _unregisterModel() override;
private:
/// The StatePropagators for the vehicles to run in parallel
std::vector<kc::ks_ptr<kd::StatePropagator>> _sps;
/// Whether to run in serial or not
bool _run_in_serial = false;
};
} // namespace Karana::Models