config.h

/*************************************************************************
 * Copyright (C) 2018-2021 Blue Brain Project
 *                         Jonas Karlsson <jonas.karlsson@epfl.ch>
 *                         Juan Hernando <juan.hernando@epfl.ch>
 *
 * This file is part of 'libsonata', distributed under the terms
 * of the GNU Lesser General Public License version 3.
 *
 * See top-level COPYING.LESSER and COPYING files for details.
 *************************************************************************/
 
#pragma once
 
#include <set>
#include <string>
#include <unordered_map>
#include <vector>
 
#include <bbp/sonata/edges.h>
#include <bbp/sonata/nodes.h>
#include <bbp/sonata/optional.hpp>
 
#include "common.h"
#include "optional.hpp"
#include "variant.hpp"
 
 
namespace bbp {
namespace sonata {
 
using variantValueType = nonstd::variant<bool, std::string, int, double>;
 
struct CommonPopulationProperties {
    std::string type;
 
    std::string elementsPath;
 
    std::string typesPath;
 
    std::string biophysicalNeuronModelsDir;
 
    std::string morphologiesDir;
 
    std::unordered_map<std::string, std::string> alternateMorphologyFormats;
};
 
struct SONATA_API NodePopulationProperties: public CommonPopulationProperties {
    std::string spatialSegmentIndexDir;
 
    nonstd::optional<std::string> vasculatureFile{nonstd::nullopt};
 
    nonstd::optional<std::string> vasculatureMesh{nonstd::nullopt};
 
    nonstd::optional<std::string> microdomainsFile{nonstd::nullopt};
 
    nonstd::optional<std::string> spineMorphologiesDir{nonstd::nullopt};
};
 
struct SONATA_API EdgePopulationProperties: public CommonPopulationProperties {
    std::string spatialSynapseIndexDir;
 
    nonstd::optional<std::string> endfeetMeshesFile{nonstd::nullopt};
};
 
class SONATA_API CircuitConfig
{
  public:
    enum class ConfigStatus {
        invalid,
        complete,
        partial
    };
 
    CircuitConfig(const std::string& contents, const std::string& basePath);
 
    static CircuitConfig fromFile(const std::string& path);
 
    ConfigStatus getCircuitConfigStatus() const;
 
    const std::string& getNodeSetsPath() const;
 
    std::set<std::string> listNodePopulations() const;
 
    NodePopulation getNodePopulation(const std::string& name, const Hdf5Reader& hdf5_reader) const;
    NodePopulation getNodePopulation(const std::string& name) const;
    std::set<std::string> listEdgePopulations() const;
 
    EdgePopulation getEdgePopulation(const std::string& name, const Hdf5Reader& hdf5_reader) const;
    EdgePopulation getEdgePopulation(const std::string& name) const;
 
    NodePopulationProperties getNodePopulationProperties(const std::string& name) const;
 
    EdgePopulationProperties getEdgePopulationProperties(const std::string& name) const;
 
    const std::string& getExpandedJSON() const;
 
  private:
    struct Components {
        std::string morphologiesDir;
        std::unordered_map<std::string, std::string> alternateMorphologiesDir;
        std::string biophysicalNeuronModelsDir;
 
        nonstd::optional<std::string> vasculatureFile{nonstd::nullopt};
        nonstd::optional<std::string> vasculatureMesh{nonstd::nullopt};
        nonstd::optional<std::string> endfeetMeshesFile{nonstd::nullopt};
        nonstd::optional<std::string> microdomainsFile{nonstd::nullopt};
        nonstd::optional<std::string> spineMorphologiesDir{nonstd::nullopt};
    };
 
    class Parser;
 
    // Circuit config json string whose paths and variables have been expanded to include
    // manifest variables
    std::string _expandedJSON;
 
    // How strict we are checking the circuit config
    ConfigStatus _status = ConfigStatus::complete;
 
    // Path to the nodesets file
    std::string _nodeSetsFile;
 
    // Node populations that override default components variables
    std::unordered_map<std::string, NodePopulationProperties> _nodePopulationProperties;
 
    // Edge populations that override default components variables
    std::unordered_map<std::string, EdgePopulationProperties> _edgePopulationProperties;
};
 
class SONATA_API SimulationConfig
{
  public:
    struct Run {
        enum class IntegrationMethod { invalid = -1, euler, nicholson, nicholson_ion };
 
        static constexpr double DEFAULT_spikeThreshold = -30.0;
        static constexpr IntegrationMethod DEFAULT_IntegrationMethod = IntegrationMethod::euler;
        static constexpr int DEFAULT_stimulusSeed = 0;
        static constexpr int DEFAULT_ionchannelSeed = 0;
        static constexpr int DEFAULT_minisSeed = 0;
        static constexpr int DEFAULT_synapseSeed = 0;
 
        double tstop{};
        double dt{};
        int randomSeed{};
        double spikeThreshold = DEFAULT_spikeThreshold;
        IntegrationMethod integrationMethod = DEFAULT_IntegrationMethod;
        int stimulusSeed = DEFAULT_stimulusSeed;
        int ionchannelSeed = DEFAULT_ionchannelSeed;
        int minisSeed = DEFAULT_minisSeed;
        int synapseSeed = DEFAULT_synapseSeed;
        std::string electrodesFile;
    };
    struct Output {
        enum class SpikesSortOrder { invalid = -1, none, by_id, by_time };
 
        static constexpr char DEFAULT_outputDir[] = "output";
        static constexpr char DEFAULT_logFile[] = "";
        static constexpr char DEFAULT_spikesFile[] = "out.h5";
        static constexpr SpikesSortOrder DEFAULT_sortOrder = SpikesSortOrder::by_time;
 
        std::string outputDir = DEFAULT_outputDir;
        std::string logFile = DEFAULT_logFile;
        std::string spikesFile = DEFAULT_spikesFile;
        SpikesSortOrder sortOrder = DEFAULT_sortOrder;
    };
 
    struct ModificationBase {
        enum class ModificationType { invalid = -1, TTX, ConfigureAllSections };
 
        std::string nodeSet;
        ModificationType type;
    };
 
    struct ModificationTTX: public ModificationBase {};
 
    struct ModificationConfigureAllSections: public ModificationBase {
        std::string sectionConfigure;
    };
 
    using Modification = nonstd::variant<ModificationTTX, ModificationConfigureAllSections>;
 
    using ModificationMap = std::unordered_map<std::string, Modification>;
 
    struct Conditions {
        enum class SpikeLocation { invalid = -1, soma, AIS };
        static constexpr double DEFAULT_celsius = 34.0;
        static constexpr double DEFAULT_vInit = -80.0;
        static constexpr SpikeLocation DEFAULT_spikeLocation = SpikeLocation::soma;
        static constexpr bool DEFAULT_randomizeGabaRiseTime = false;
 
        double celsius = DEFAULT_celsius;
        double vInit = DEFAULT_vInit;
        SpikeLocation spikeLocation = DEFAULT_spikeLocation;
        nonstd::optional<double> extracellularCalcium{nonstd::nullopt};
        bool randomizeGabaRiseTime = DEFAULT_randomizeGabaRiseTime;
        std::unordered_map<std::string, std::unordered_map<std::string, variantValueType>>
            mechanisms;
        ModificationMap modifications;
        std::set<std::string> listModificationNames() const;
        const Modification& getModification(const std::string& name) const;
    };
    struct Report {
        enum class Sections { invalid = -1, soma, axon, dend, apic, all };
        enum class Type { invalid = -1, compartment, lfp, summation, synapse };
        enum class Scaling { invalid = -1, none, area };
        enum class Compartments { invalid = -1, center, all };
 
        std::string cells;
        Sections sections;
        Type type;
        Scaling scaling;
        Compartments compartments;
        std::string variableName;
        std::string unit;
        double dt{};
        double startTime{};
        double endTime{};
        std::string fileName;
        bool enabled = true;
    };
 
    using ReportMap = std::unordered_map<std::string, Report>;
 
    struct InputBase {
        enum class Module {
            invalid = -1,
            linear,
            relative_linear,
            pulse,
            subthreshold,
            hyperpolarizing,
            synapse_replay,
            seclamp,
            noise,
            shot_noise,
            relative_shot_noise,
            absolute_shot_noise,
            ornstein_uhlenbeck,
            relative_ornstein_uhlenbeck
        };
 
        enum class InputType {
            invalid = -1,
            spikes,
            extracellular_stimulation,
            current_clamp,
            voltage_clamp,
            conductance
        };
 
        Module module;
        InputType inputType;
        double delay{};
        double duration{};
        std::string nodeSet;
    };
 
    struct InputLinear: public InputBase {
        double ampStart{};
        double ampEnd{};
        bool representsPhysicalElectrode = false;
    };
 
    struct InputRelativeLinear: public InputBase {
        double percentStart{};
        double percentEnd{};
        bool representsPhysicalElectrode = false;
    };
 
    struct InputPulse: public InputBase {
        double ampStart{};
        double ampEnd{};
        double width{};
        double frequency{};
        bool representsPhysicalElectrode = false;
    };
 
    struct InputSubthreshold: public InputBase {
        double percentLess{};
        bool representsPhysicalElectrode = false;
    };
 
    struct InputHyperpolarizing: public InputBase {
        bool representsPhysicalElectrode = false;
    };
 
    struct InputSynapseReplay: public InputBase {
        std::string spikeFile;
    };
 
    struct InputSeclamp: public InputBase {
        double voltage{};
        double seriesResistance{};
    };
 
    struct InputNoise: public InputBase {
        nonstd::optional<double> mean{nonstd::nullopt};
        nonstd::optional<double> meanPercent{nonstd::nullopt};
        double variance{};
        bool representsPhysicalElectrode = false;
    };
 
    struct InputShotNoise: public InputBase {
        double riseTime{};
        double decayTime{};
        nonstd::optional<int> randomSeed{nonstd::nullopt};
        double reversal{};
        double dt{};
        int rate{};
        double ampMean{};
        double ampVar{};
        bool representsPhysicalElectrode = false;
    };
 
    struct InputRelativeShotNoise: public InputBase {
        double riseTime{};
        double decayTime{};
        nonstd::optional<int> randomSeed{nonstd::nullopt};
        double reversal{};
        double dt{};
        double ampCv{};
        double meanPercent{};
        double sdPercent{};
        bool representsPhysicalElectrode = false;
    };
 
    struct InputAbsoluteShotNoise: public InputBase {
        double riseTime{};
        double decayTime{};
        nonstd::optional<int> randomSeed{nonstd::nullopt};
        double reversal{};
        double dt{};
        double ampCv{};
        double mean{};
        double sigma{};
        bool representsPhysicalElectrode = false;
    };
 
    struct InputOrnsteinUhlenbeck: public InputBase {
        double tau{};
        double reversal{};
        double dt{};
        nonstd::optional<int> randomSeed{nonstd::nullopt};
        double mean{};
        double sigma{};
        bool representsPhysicalElectrode = false;
    };
 
    struct InputRelativeOrnsteinUhlenbeck: public InputBase {
        double tau{};
        double reversal{};
        double dt{};
        nonstd::optional<int> randomSeed{nonstd::nullopt};
        double meanPercent{};
        double sdPercent{};
        bool representsPhysicalElectrode = false;
    };
 
    using Input = nonstd::variant<InputLinear,
                                  InputRelativeLinear,
                                  InputPulse,
                                  InputSubthreshold,
                                  InputHyperpolarizing,
                                  InputSynapseReplay,
                                  InputSeclamp,
                                  InputNoise,
                                  InputShotNoise,
                                  InputRelativeShotNoise,
                                  InputAbsoluteShotNoise,
                                  InputOrnsteinUhlenbeck,
                                  InputRelativeOrnsteinUhlenbeck>;
 
    using InputMap = std::unordered_map<std::string, Input>;
 
    struct ConnectionOverride {
        std::string name;
        std::string source;
        std::string target;
        double weight{1.};
        nonstd::optional<double> spontMinis{nonstd::nullopt};
        nonstd::optional<std::string> synapseConfigure{nonstd::nullopt};
        nonstd::optional<std::string> modoverride{nonstd::nullopt};
        nonstd::optional<double> synapseDelayOverride{nonstd::nullopt};
        double delay{0.};
        nonstd::optional<double> neuromodulationDtc{nonstd::nullopt};
        nonstd::optional<double> neuromodulationStrength{nonstd::nullopt};
    };
 
    enum class SimulatorType { invalid = -1, NEURON, CORENEURON };
 
    SimulationConfig(const std::string& content, const std::string& basePath);
 
    static SimulationConfig fromFile(const std::string& path);
 
    const std::string& getBasePath() const noexcept;
 
    const std::string& getJSON() const noexcept;
 
    const std::string& getNetwork() const noexcept;
 
    const Run& getRun() const noexcept;
 
    const Output& getOutput() const noexcept;
 
    const Conditions& getConditions() const noexcept;
 
    std::set<std::string> listReportNames() const;
 
    const Report& getReport(const std::string& name) const;
 
    std::set<std::string> listInputNames() const;
 
    const Input& getInput(const std::string& name) const;
 
    const std::vector<ConnectionOverride>& getConnectionOverrides() const noexcept;
 
    const SimulationConfig::SimulatorType& getTargetSimulator() const;
 
    const std::string& getNodeSetsFile() const noexcept;
 
    const nonstd::optional<std::string>& getNodeSet() const noexcept;
 
    const std::unordered_map<std::string, variantValueType>& getMetaData() const noexcept;
 
 
    const std::unordered_map<std::string, variantValueType>& getBetaFeatures() const noexcept;
 
    const std::string& getExpandedJSON() const;
 
  private:
    // JSON string
    std::string _expandedJSON;
    // Base path of the simulation config file
    std::string _basePath;
 
    // Run section
    Run _run;
    // Output section
    Output _output;
    // List of reports
    ReportMap _reports;
    // Conditions section
    Conditions _conditions;
    // Path of circuit config file for the simulation
    std::string _network;
    // List of inputs
    InputMap _inputs;
    // List of connections
    std::vector<ConnectionOverride> _connection_overrides;
    // Name of simulator
    SimulatorType _targetSimulator;
    // Path of node sets file
    std::string _nodeSetsFile;
    // Name of node set
    nonstd::optional<std::string> _nodeSet{nonstd::nullopt};
    // Remarks on the simulation
    std::unordered_map<std::string, variantValueType> _metaData;
    // Variables for a new feature in development, to be moved to other sections once in production
    std::unordered_map<std::string, variantValueType> _betaFeatures;
 
    class Parser;
};
 
}  // namespace sonata
}  // namespace bbp