qemcmc.sampler ============== .. py:module:: qemcmc.sampler Submodules ---------- .. toctree:: :maxdepth: 1 /api/qemcmc/sampler/classical_proposal/index /api/qemcmc/sampler/proposal/index /api/qemcmc/sampler/qe_proposal/index /api/qemcmc/sampler/runners/index Classes ------- .. autoapisummary:: qemcmc.sampler.Proposal qemcmc.sampler.ClassicalProposal qemcmc.sampler.QeProposal Package Contents ---------------- .. py:class:: Proposal(model: qemcmc.model.EnergyModel) Bases: :py:obj:`abc.ABC` Abstract base class for producing proposals for Markov Chain Monte Carlo algorithms. Subclasses implement the proposal mechanism by defining an ``update(state)`` method that generates a candidate state from the current one (e.g. single-spin flips, block updates, or quantum proposals). :param model: Energy model defining the target distribution over spin configurations. :type model: EnergyModel .. py:attribute:: model .. py:attribute:: n_spins .. py:method:: update(state: qemcmc.utils.MCMCState) -> qemcmc.utils.MCMCState :abstractmethod: Generate a candidate state from the current state using the proposal mechanism. This method should be implemented by subclasses to define the specific proposal strategy (e.g., single-spin flips, block updates, or quantum proposals). :param state: The current state of the Markov chain. :type state: MCMCState :returns: A new candidate state. :rtype: MCMCState .. py:class:: ClassicalProposal(model: qemcmc.model.EnergyModel, method: str = 'uniform') Bases: :py:obj:`qemcmc.sampler.Proposal` Classical Markov Chain Monte Carlo proposer. This class implements purely classical proposal mechanisms for MCMC. New candidate states are generated either by sampling a completely random (uniform) configuration, or by performing a local single-spin or two-spin flip. :param model: Energy model defining the target Boltzmann distribution. :type model: EnergyModel :param method: Proposal mechanism used to generate candidate states. - ``"uniform"`` : propose a completely random spin configuration. - ``"local"`` : flip a single randomly chosen spin. - ``"2-local"`` : flip two randomly chosen spins. Default is ``"uniform"``. :type method: str, optional .. py:attribute:: METHODS .. py:attribute:: method :value: 'uniform' .. py:method:: update(current_state_bitstring: str) -> str Generate a candidate state from the current state using the proposal mechanism. This method should be implemented by subclasses to define the specific proposal strategy (e.g., single-spin flips, block updates, or quantum proposals). :param state: The current state of the Markov chain. :type state: MCMCState :returns: A new candidate state. :rtype: MCMCState .. py:method:: update_uniform(current_state_bitstring: str) -> str Proposes a new state by generating a random bitstring. :param current_state_bitstring: The current state represented as a bitstring (not used, but required by the API). :type current_state_bitstring: str :returns: A new random state bitstring of the same length. :rtype: str .. py:method:: update_local(current_state_bitstring: str) -> str Proposes a new state by flipping a single randomly chosen spin. :param current_state_bitstring: The current state represented as a bitstring. :type current_state_bitstring: str :returns: The new state bitstring after flipping one spin. :rtype: str .. py:method:: update_2local(current_state_bitstring: str) -> str Proposes a new state by flipping two randomly chosen spins. :param current_state_bitstring: The current state represented as a bitstring. :type current_state_bitstring: str :returns: The new state bitstring after flipping two spins. :rtype: str .. py:class:: QeProposal(model: qemcmc.model.EnergyModel, gamma: float | tuple[float, float], time: float | tuple[float, float], r: Optional[int] = None, delta_t: Optional[float] = None, coarse_graining: Optional[qemcmc.coarse_grain.CoarseGraining] = None, coupling_weights: Optional[list[float | tuple[float, float]]] = None, m: int = 1) Bases: :py:obj:`qemcmc.sampler.Proposal` Quantum-enhanced Markov Chain Monte Carlo sampler. This class implements the proposal mechanism of the quantum-enhanced MCMC algorithm. Candidate states are generated by simulating the quantum time evolution of a transverse-field Hamiltonian. The quantum proposal circuit is constructed using :class:`CircuitMaker` and can optionally operate on coarse-grained subgroups of spins to improve scalability. :param model: Energy model defining the target Boltzmann distribution. :type model: EnergyModel :param gamma: Transverse field strength (Γ). If a tuple is provided, a value is sampled uniformly from the range [min, max] at each step. :type gamma: float | tuple[float, float] :param time: Total evolution time. If a tuple is provided, a value is sampled uniformly from the range [min, max] at each step. :type time: float | tuple[float, float] :param r: Number of Trotter steps. Mutually exclusive with ``delta_t``. If provided, the Trotter step size is derived as Δt = t / r and ``r`` stays fixed while Δt varies with ``t``. A warning is issued at init if the resulting Δt range falls outside [0.1, 2.0]. By default ``None``. :type r: int | None, optional :param delta_t: Trotter step size. Mutually exclusive with ``r``. If provided, the number of Trotter steps is derived as r = floor(t / Δt) per step, so ``r`` varies with ``t`` while Δt stays fixed. A warning is issued if Δt falls outside [0.1, 2.0]. By default ``None``. :type delta_t: float | None, optional :param coarse_graining: A coarse-graining scheme to define spin subgroups. If None, no coarse-graining is used. By default ``None``. :type coarse_graining: CoarseGraining | None, optional :param coupling_weights: Weights for the coupling tensors. If a tuple is provided, a weight is sampled uniformly from the range. This allows for dynamic adjustment of the influence of different terms in the Hamiltonian during the proposal step. By default ``None``. Note that this is further adjusted by (1 - gamma) to balance the influence of the problem Hamiltonian with the mixer term. Divide by (1 - gamma) if needed. Also, note that the coupling weights should include the mixing term. :type coupling_weights: list[float | tuple[float, float]] | None, optional :param m: Number of subgroups to partition the spins into for sequential updates. By default ``1``. :type m: int, optional .. rubric:: Notes The proposal step simulates the time evolution under a transverse-field Hamiltonian defined by the energy model and measures the resulting state to produce a candidate configuration. This proposal is then accepted or rejected using the Metropolis criterion to ensure convergence to the target Boltzmann distribution. Exactly one of ``r`` or ``delta_t`` should be passed in as an argument. If neither is given, a default Δt of 0.8 is used. .. py:attribute:: gamma .. py:attribute:: time .. py:attribute:: r :value: None .. py:attribute:: delta_t :value: None .. py:attribute:: m :value: 1 .. py:attribute:: method :value: 'quantum' .. py:attribute:: CM .. py:attribute:: cg .. py:method:: update(current_state: str) -> str Perform 'm' sequential quantum updates across non-overlapping subgroups. :param current_state: Current state of the system as a bitstring. :type current_state: str :returns: Updated state of the system as a bitstring. :rtype: str .. py:method:: sample_hyperparams() -> tuple[list[float], float, float, int] Sample hyperparameters (coupling weights, gamma, time, r) for the current proposal step. :returns: (final_coupling_weights, gamma, time, r) for this proposal step. :rtype: tuple[list[float], float, float, int] .. py:method:: _validate_gamma(gamma: float | tuple[float, float]) -> float | tuple[float, float] Validate the weight parameter gamma. .. py:method:: _validate_time(time: float | tuple[float, float]) -> float | tuple[float, float] Validate the total evolution time parameter. .. py:method:: _validate_r(r: Optional[int]) -> Optional[int] Validate the number of Trotter steps 'r'. .. py:method:: _validate_delta_t(delta_t: Optional[float]) -> Optional[float] Validate the Trotter step size 'delta_t'. .. py:method:: _validate_trotter_params() Check mutual exclusivity of r and delta_t, and warn if resulting Trotter step size falls outside [0.1, 2.0].