potentialscene2d.h

Go to the documentation of this file.

/**
 * @file potentialscene2d.h
 * @brief Declares the potentialscene2d physics/numerical component used by QPE experiments.
 * @ingroup qpe_quantum
 *
 * Source: @c core/quantum/potentialscene2d.h. This file is part of Quantum Phenomena Explorer (QPE),
 * maintained by Officina Turini. See LICENSE_IT.txt / LICENSE.txt for the
 * QPE freeware source-available terms and THIRD_PARTY_NOTICES.txt for
 * third-party components.
 */
 
#pragma once
 
#include <cstddef>
#include <cstdint>
#include <vector>
 
namespace qpe {
 
class PotentialField2D;
 
/**
 * @brief Enumerates the supported Potential Object Type2D values.
 *
 * The enumeration is part of the typed interface used to keep experiment configuration and analysis routing explicit.
 */
enum class PotentialObjectType2D
{
    Rectangle = 1,
    Circle = 2,
    Barrier = 3,
    SingleSlit = 4,
    DoubleSlit = 5,
    PolygonWedge = 6,
    Gaussian = 7,
    Harmonic = 8,
    Linear = 9,
    SoftenedRadial = 10,
    StadiumExterior = 11
};
 
// One editable term of V(x,y).  The fields deliberately mirror the current
// GUI primitives so the existing parameter pages can act as an inspector.
// Only the subset relevant to type is used during rasterization.
/**
 * @brief Data structure used by the Potential Object2D component.
 *
 * The structure keeps related values explicit and testable across the QPE physics, analysis, or persistence layers.
 */
struct PotentialObject2D
{
    std::uint64_t id = 0;
    PotentialObjectType2D type = PotentialObjectType2D::Rectangle;
    bool enabled = true;
    float value = 0.0f;
 
    float centerX = 0.0f;
    float centerY = 0.0f;
 
    float width = 1.0f;
    float height = 1.0f;
    float radius = 1.0f;
 
    float length = 1.0f;
    float thickness = 1.0f;
 
    float wallWidth = 1.0f;
    float slitHeight = 1.0f;
    float slitSeparation = 2.0f;
 
    // Smooth-potential parameters. value is the Gaussian amplitude, harmonic
    // offset, linear offset, or radial coupling depending on type.
    float sigmaX = 1.0f;
    float sigmaY = 1.0f;
    float curvatureX = 0.25f;
    float curvatureY = 0.25f;
    float slopeX = 0.0f;
    float slopeY = 0.0f;
    float softening = 0.5f;
 
    /**
     * @brief Performs valid.
     */
    bool valid() const noexcept;
};
 
// A small object model for composing an external potential from independent
// terms.  Composition is additive: V_total = sum_i V_i.  This is the natural
// Hamiltonian semantics and also makes overlapping objects explicit instead
// of depending on draw order.
/**
 * @brief Implements the Potential Scene2D component.
 *
 * The class provides one focused service within the QPE architecture and is documented here independently of the experiment-level Help.
 */
class PotentialScene2D
{
public:
    /**
     * @brief Performs add.
     * @param object The object value used by the operation.
     */
    std::uint64_t add(PotentialObject2D object);
    /**
     * @brief Performs update.
     * @param id Stable identifier of the requested object.
     * @param object The object value used by the operation.
     */
    bool update(std::uint64_t id, const PotentialObject2D &object);
    /**
     * @brief Performs remove.
     * @param id Stable identifier of the requested object.
     */
    bool remove(std::uint64_t id);
    /**
     * @brief Performs clear.
     */
    void clear() noexcept;
 
    /**
     * @brief Performs empty.
     */
    bool empty() const noexcept;
    /**
     * @brief Returns size.
     */
    std::size_t size() const noexcept;
 
    /**
     * @brief Performs objects.
     */
    const std::vector<PotentialObject2D> &objects() const noexcept;
    /**
     * @brief Performs find.
     * @param id Stable identifier of the requested object.
     */
    PotentialObject2D *find(std::uint64_t id) noexcept;
    /**
     * @brief Performs find.
     * @param id Stable identifier of the requested object.
     */
    const PotentialObject2D *find(std::uint64_t id) const noexcept;
 
    // Replace the target field with the additive scene potential.  The target
    // field must already have the desired simulation grid.
    /**
     * @brief Performs rasterize.
     * @param target The target value used by the operation.
     */
    void rasterize(PotentialField2D &target) const;
 
private:
    /**
     * @brief Performs allocate id.
     */
    std::uint64_t allocateId() noexcept;
 
    std::vector<PotentialObject2D> objects_;
    std::uint64_t nextId_ = 1;
};
 
} // namespace qpe