inc

DuneConverter

class DuneConverter

Convert model data into DUNE configuration and arrays.

Public Functions

explicit DuneConverter(const model::Model &model, const std::map<std::string, double, std::less<>> &substitutions = {}, bool forExternalUse = false, const QString &outputIniFile = {}, int doublePrecision = 18)

Build DUNE ini and associated arrays from model.

Parameters:

• model – Source model.

• substitutions – Constant substitutions.

• forExternalUse – Generate output suitable for external execution.

• outputIniFile – Optional output ini filename.

• doublePrecision – Decimal precision for floating values.

QString getIniFile() const

Generated DUNE ini file text.

Returns:

INI file text.

const mesh::Mesh2d *getMesh() const

2D mesh used for conversion (nullable).

Returns:

2D mesh pointer or nullptr.

const mesh::Mesh3d *getMesh3d() const

3D mesh used for conversion (nullable).

Returns:

3D mesh pointer or nullptr.

const std::unordered_map<std::string, std::vector<double>> &getConcentrations() const

Initial concentration arrays keyed by species name.

Returns:

Concentration arrays.

const std::unordered_map<std::string, std::vector<double>> &getDiffusionConstantArrays() const

Diffusion-constant arrays keyed by species name.

Returns:

Diffusion arrays.

const std::unordered_map<std::string, std::vector<std::string>> &getSpeciesNames() const

Species names grouped by compartment id.

Returns:

Species names per compartment.

const std::vector<std::string> &getCompartmentNames() const

Compartment ids in subdomain order.

Returns:

Compartment ids.

common::VoxelF getOrigin() const

Physical origin.

Returns:

Geometry origin.

common::VolumeF getVoxelSize() const

Physical voxel size.

Returns:

Voxel size.

common::Volume getImageSize() const

Geometry image size.

Returns:

Image size.

Pde

class Pde

Symbolic PDE rhs and Jacobian for a compartment/membrane system.

Public Functions

explicit Pde(const model::Model *doc_ptr, const std::vector<std::string> &speciesIDs, const std::vector<std::string> &reactionIDs, const std::vector<std::string> &relabelledSpeciesIDs = {}, const PdeScaleFactors &pdeScaleFactors = {}, const std::vector<std::string> &extraVariables = {}, const std::vector<std::string> &relabelledExtraVariables = {}, const std::map<std::string, double, std::less<>> &substitutions = {})

Construct PDE from model, species set, and reaction set.

const std::vector<std::string> &getRHS() const

Right-hand-side expressions.

const std::vector<std::vector<std::string>> &getJacobian() const

Jacobian expressions.

Simulation

class Simulation

High-level simulation orchestrator over configured solver backend.

Public Functions

explicit Simulation(model::Model &smeModel)

Construct simulation for model.

Parameters:

smeModel – Model to simulate.

~Simulation()

Destructor.

std::size_t doTimesteps(double time, std::size_t nSteps = 1, double timeout_ms = -1.0)

Advance simulation by nSteps of size time.

Parameters:

• time – Timestep size.

• nSteps – Number of timesteps.

• timeout_ms – Timeout in milliseconds, negative for no timeout.

Returns:

Number of completed timesteps.

std::size_t doMultipleTimesteps(const std::vector<std::pair<std::size_t, double>> &timesteps, double timeout_ms = -1.0, const std::function<bool()> &stopRunningCallback = {})

Run multiple simulation segments.

Parameters:

• timesteps – Sequence of (nSteps, dt) segments.

• timeout_ms – Timeout in milliseconds, negative for no timeout.

• stopRunningCallback – Optional callback for external cancellation.

Returns:

Number of completed timesteps.

const std::string &errorMessage() const

Solver error message.

Returns:

Error message string.

const common::ImageStack &errorImages() const

Solver error visualization images.

Returns:

Error image stack.

const std::vector<std::string> &getCompartmentIds() const

Compartment ids in simulation order.

Returns:

Compartment ids.

const std::vector<std::string> &getSpeciesIds(std::size_t compartmentIndex) const

Species ids for a compartment.

Parameters:

compartmentIndex – Compartment index.

Returns:

Species ids for compartment.

const std::vector<QRgb> &getSpeciesColors(std::size_t compartmentIndex) const

Species display colors for a compartment.

Parameters:

compartmentIndex – Compartment index.

Returns:

Species colors for compartment.

std::vector<double> getTimePoints() const

Simulated time points.

Returns:

Time points.

AvgMinMax getAvgMinMax(std::size_t timeIndex, std::size_t compartmentIndex, std::size_t speciesIndex) const

Average/min/max concentration summary.

Parameters:

• timeIndex – Time index.

• compartmentIndex – Compartment index.

• speciesIndex – Species index.

Returns:

Average/min/max summary.

std::vector<double> getConc(std::size_t timeIndex, std::size_t compartmentIndex, std::size_t speciesIndex) const

Concentrations in compartment voxel order.

Parameters:

• timeIndex – Time index.

• compartmentIndex – Compartment index.

• speciesIndex – Species index.

Returns:

Concentration values.

std::vector<double> getConcArray(std::size_t timeIndex, std::size_t compartmentIndex, std::size_t speciesIndex) const

Concentrations in full image array order.

Parameters:

• timeIndex – Time index.

• compartmentIndex – Compartment index.

• speciesIndex – Species index.

Returns:

Concentration array in image order.

void applyConcsToModel(model::Model &m, std::size_t timeIndex) const

Write concentrations from one timepoint back into a model.

Parameters:

• m – Target model.

• timeIndex – Time index to apply.

std::vector<double> getDcdt(std::size_t compartmentIndex, std::size_t speciesIndex) const

Time derivatives in compartment voxel order.

Parameters:

• compartmentIndex – Compartment index.

• speciesIndex – Species index.

Returns:

Time derivative values.

std::vector<double> getDcdtArray(std::size_t compartmentIndex, std::size_t speciesIndex) const

Time derivatives in full image array order.

Parameters:

• compartmentIndex – Compartment index.

• speciesIndex – Species index.

Returns:

Time derivative array in image order.

double getLowerOrderConc(std::size_t compartmentIndex, std::size_t speciesIndex, std::size_t pixelIndex) const

Lower-order concentration value for adaptive RK.

Parameters:

• compartmentIndex – Compartment index.

• speciesIndex – Species index.

• pixelIndex – Pixel index.

Returns:

Lower-order concentration value.

common::ImageStack getConcImage(std::size_t timeIndex, const std::vector<std::vector<std::size_t>> &speciesToDraw = {}, bool normaliseOverAllTimepoints = false, bool normaliseOverAllSpecies = false) const

Render concentration image stack.

Parameters:

• timeIndex – Time index.

• speciesToDraw – Per-compartment species indices to draw.

• normaliseOverAllTimepoints – Normalize using all timepoints.

• normaliseOverAllSpecies – Normalize using all species.

Returns:

Concentration image stack.

const std::vector<std::string> &getPyNames(std::size_t compartmentIndex) const

Species names for Python API.

Parameters:

compartmentIndex – Compartment index.

Returns:

Species names.

std::vector<std::vector<double>> getPyConcs(std::size_t timeIndex, std::size_t compartmentIndex) const

Concentrations formatted for Python API.

Parameters:

• timeIndex – Time index.

• compartmentIndex – Compartment index.

Returns:

Concentrations grouped by species.

std::vector<std::vector<double>> getPyDcdts(std::size_t compartmentIndex) const

Time derivatives formatted for Python API.

Parameters:

compartmentIndex – Compartment index.

Returns:

Time derivatives grouped by species.

std::size_t getNCompletedTimesteps() const

Number of completed timesteps.

Returns:

Completed timestep count.

const SimulationData &getSimulationData() const

Immutable simulation data storage.

Returns:

Simulation data.

bool getIsRunning() const

Returns true if solver is currently running.

Returns:

Running flag.

bool getIsStopping() const

Returns true if stop has been requested.

Returns:

Stop-request flag.

void requestStop()

Request graceful stop of running simulation.

SimulationData

class SimulationData

Stored simulation outputs across timepoints.

Public Functions

void clear()

Clear all stored data.

std::size_t size() const

Number of stored timepoints.

std::size_t getEstimatedMemoryBytes() const

Estimated memory usage of currently stored data.

std::size_t getEstimatedAdditionalMemoryBytes(std::size_t nAdditionalTimepoints) const

Estimated additional memory for extra timepoints.

void reserve(std::size_t n)

Reserve storage for n timepoints.

void pop_back()

Remove last stored timepoint.

template<class Archive>
inline void serialize(Archive &ar, std::uint32_t const version)

Public Members

std::vector<double> timePoints

Simulated time values.

std::vector<std::vector<std::vector<double>>> concentration

Concentrations: time -> compartment -> flattened(voxel,species).

std::vector<std::vector<std::vector<AvgMinMax>>> avgMinMax

Average/min/max by time -> compartment -> species.

std::vector<std::vector<std::vector<double>>> concentrationMax

Concentration maxima by time -> compartment -> species.

std::vector<std::size_t> concPadding

Padding values for flattened concentration arrays per timepoint.

std::string xmlModel

Serialized XML of model this data belongs to.

std::vector<simulate::FeatureResult> featureResults

Feature extraction results: one FeatureResult per feature.

struct AvgMinMax

Aggregate concentration statistics.

Public Functions

template<class Archive>
inline void serialize(Archive &ar, std::uint32_t const version)

Public Members

double avg = 0

Average concentration.

double min = std::numeric_limits<double>::max()

Minimum concentration.

double max = 0

Maximum concentration.

Friends

friend bool operator==(const AvgMinMax &lhs, const AvgMinMax &rhs)

Equality comparison.

SimulationOptions

struct Options

Global simulation options for all solver backends.

Public Functions

template<class Archive>
inline void serialize(Archive &ar, std::uint32_t const version)

Public Members

DuneOptions dune

DUNE backend options.

PixelOptions pixel

Pixel backend options.

enum class sme::simulate::SimulatorType

Solver backend selection.

Values:

enumerator DUNE

enumerator Pixel

struct PixelOptions

Pixel solver options.

Public Functions

template<class Archive>
inline void serialize(Archive &ar, std::uint32_t const version)

Public Members

PixelBackendType backend = {PixelBackendType::CPU}

Execution backend for the pixel solver.

GpuFloatPrecision gpuFloatPrecision = {GpuFloatPrecision::Double}

Floating-point precision for the GPU backend.

PixelIntegratorType integrator = {PixelIntegratorType::RK212}

RK integrator scheme.

PixelIntegratorError maxErr

Adaptive error tolerances.

double maxTimestep = {std::numeric_limits<double>::max()}

Maximum timestep.

bool enableMultiThreading = {false}

Enable multithreading for pixel solver.

std::size_t maxThreads = {0}

Max thread count (0 means automatic/default).

bool doCSE = {true}

Enable common subexpression elimination in symbolic expressions.

unsigned optLevel = {3}

LLVM optimization level.

struct PixelIntegratorError

Error tolerances for pixel adaptive integration.

Public Functions

template<class Archive>
inline void serialize(Archive &ar, std::uint32_t const version)

Public Members

double abs = {std::numeric_limits<double>::max()}

Absolute tolerance.

double rel = {0.005}

Relative tolerance.

enum class sme::simulate::PixelIntegratorType

Pixel integrator scheme selection.

Values:

enumerator RK101

enumerator RK212

enumerator RK323

enumerator RK435

struct DuneOptions

DUNE solver options.

Public Functions

template<class Archive>
inline void serialize(Archive &ar, std::uint32_t const version)

Public Members

DuneDiscretizationType discretization = {DuneDiscretizationType::FEM1}

Spatial discretization scheme.

std::string integrator = {"Alexander2"}

Time integrator name.

double dt = {1e-1}

Initial timestep.

double minDt = {1e-10}

Minimum adaptive timestep.

double maxDt = {1e4}

Maximum adaptive timestep.

double increase = {1.5}

Adaptive timestep increase factor.

double decrease = {0.5}

Adaptive timestep decrease factor.

bool writeVTKfiles = {false}

Enable VTK output files.

double newtonRelErr = {1e-8}

Newton relative tolerance.

double newtonAbsErr = {0.0}

Newton absolute tolerance.

std::string linearSolver = {"RestartedGMRes"}

Linear solver name.

std::size_t maxThreads = {0}

Max thread count (0 means automatic/default).

enum class sme::simulate::DuneDiscretizationType

DUNE spatial discretization type.

Values:

enumerator FEM1

Optimization

class Optimization

Optimize model parameters.

Optimizes the supplied model parameters to minimize the supplied cost functions.

Public Functions

explicit Optimization(sme::model::Model &model)

Constructs an Optimization object from the supplied model.

Parameters:

model – [in] the model to optimize

std::size_t evolve(std::size_t n = 1, const std::function<void(double, const std::vector<double>&)> &callback = {})

Do n iterations of parameter optimization.

bool applyParametersToModel(sme::model::Model *model) const

Apply the current best parameter values to the supplied model.

std::vector<std::vector<double>> getParams() const

The best set of parameters from each iteration.

std::vector<std::string> getParamNames() const

The names of the parameters being optimized.

std::vector<double> getFitness() const

The best fitness from each iteration.

bool setBestResults(double fitness, std::vector<std::vector<double>> &&results)

Try to set a new set of best results for each target.

The best results are only updated if fitness is lower than the current bestResultsFitness

std::vector<double> getBestResultValues(std::size_t index) const

Get the values for a target obtained with the best currently available parameters.

common::ImageStack getTargetImage(std::size_t index) const

Get an image of the a target.

const std::vector<double> &getTargetValues(std::size_t index) const

Get the raw values of the optimization target.

std::optional<common::ImageStack> getUpdatedBestResultImage(std::size_t index)

Get an image of the current best result for a target.

common::ImageStack getCurrentBestResultImage() const

Get the current best result for a target.

sme::common::Volume getImageSize()

Get the size of the domain of the image representing the optimization target in number of pixels in each dimension.

double getMaxValue(std::size_t index)

get the maximum value of the target values

common::ImageStack getDifferenceImage(std::size_t index)

Get the difference between the optimization target and the current best result.

std::size_t getIterations() const

The number of completed evolve iterations.

bool getIsRunning() const

True if the optimization is currently running.

bool getIsStopping() const

True if requestStop() has been called.

void requestStop()

Stop the evolution as soon as possible.

const std::string &getErrorMessage() const

Returns a message if an error occurred - empty if no errors occurred.

OptimizationOptions

struct OptimizeOptions

Optimization options.

Public Functions

template<class Archive>
inline void serialize(Archive &ar, std::uint32_t const version)

Public Members

OptAlgorithm optAlgorithm

The algorithm to use.

std::vector<OptParam> optParams

The parameters to optimize.

std::vector<OptCost> optCosts

The costs to minimize.

struct OptParam

Defines a parameter to be used in optimization.

Public Functions

template<class Archive>
inline void serialize(Archive &ar, std::uint32_t const version)

Public Members

OptParamType optParamType

The type of parameter.

std::string name

The name of this OptParam as displayed to the user.

std::string id

The id of the parameter in the model.

std::string parentId

The id of the parent of the parameter in the model (optional)

double lowerBound

The lower bound on the allowed values of the parameter.

double upperBound

The upper bound on the allowed values of the parameter.

enum class sme::simulate::OptParamType

Types of model parameters that can be used in optimization.

Values:

enumerator ModelParameter

enumerator ReactionParameter

enumerator DiffusionConstant

struct OptCost

Defines a cost function to be minimized.

Public Functions

template<class Archive>
inline void serialize(Archive &ar, std::uint32_t const version)

Public Members

OptCostType optCostType

The type of cost function.

OptCostDiffType optCostDiffType

The type of difference (e.g. absolute, relative) used in the cost function.

std::string name

The name of this OptCost as displayed to the user.

std::string id

The id of the species in the model.

double simulationTime = {1.0}

The simulation time at which the cost function should be calculated.

double weight = {1.0}

The scale factor to multiply the cost by.

This assigns a relative weight to this cost when the optimization involves the sum of multiple cost functions.

std::size_t compartmentIndex

The index of the compartment containing the species.

std::size_t speciesIndex

The index of the species.

std::vector<double> targetValues

The target image values for this observable.

For concentration and feature observables this stores a concentration image. For dcdt observables this stores a dcdt image. It should contain a value for each pixel in the image, including those outside of the compartment the species is located in. If empty, the target values are assumed to be zero everywhere.

double epsilon = {1e-15}

A small number to avoid dividing by zero in relative differences.

A small value to be added to the denominator of relative differences to avoid numerical issues caused by dividing by zero.

std::string featureId

Stable internal feature id for feature observables.

Empty for concentration and dcdt observables.

enum class sme::simulate::OptCostType

Types of costs that can be used in optimization.

Values:

enumerator Concentration

enumerator ConcentrationDcdt

enumerator Feature

enum class sme::simulate::OptCostDiffType

Types of differences that can be used in costs.

Values:

enumerator Absolute

enumerator Relative

struct OptAlgorithm

Optimization algorithm options.

Public Functions

template<class Archive>
inline void serialize(Archive &ar, std::uint32_t const version)

Public Members

OptAlgorithmType optAlgorithmType = {OptAlgorithmType::PSO}

The algorithm to use.

std::size_t islands = {1}

The number of islands.

std::size_t population = {2}

The population size in each island.

enum class sme::simulate::OptAlgorithmType

Types of algorithms that can be used in optimization.

Values:

enumerator PSO

enumerator GPSO

enumerator DE

enumerator iDE

enumerator jDE

enumerator pDE

enumerator ABC

enumerator gaco

enumerator COBYLA

enumerator BOBYQA

enumerator NMS

enumerator sbplx

enumerator AL

enumerator PRAXIS