Skip to main content

Objective

molpack::objective

Trait Objective 

Source 
pub trait Objective {
    // Required methods
    fn evaluate(
        &mut self,
        x: &[F],
        mode: EvalMode,
        gradient: Option<&mut [F]>,
    ) -> EvalOutput;
    fn fdist(&self) -> F;
    fn frest(&self) -> F;
    fn ncf(&self) -> usize;
    fn ncg(&self) -> usize;
    fn reset_eval_counters(&mut self);

    // Provided method
    fn bounds(&self, l: &mut [F], u: &mut [F]) { ... }
}
Expand description

Abstracts the packer’s objective function so the optimizer can talk to any (f, g) oracle, not just PackContext.

Implementors are responsible for:

  • Returning f, worst-atom distance violation (fdist), worst-molecule restraint violation (frest) in one pass, via evaluate.
  • Exposing the cumulative function / gradient counters that the caller resets between phases and reads for logging.

The trait does not own bounds (l, u): those are problem-specific and the caller (e.g. pgencan::build_bounds) builds them from the concrete context it has in hand.

See spec .claude/specs/molrs-pack-plugin-arch.md §9 Phase A step 5 for the rationale; Phase B will expose this trait publicly as the extension hook for custom objectives.

Required Methods§

Source

fn evaluate( &mut self, x: &[F], mode: EvalMode, gradient: Option<&mut [F]>, ) -> EvalOutput

Unified evaluation entry point. mode selects between f only, gradient only, and both. When a gradient is requested, gradient must be Some(buf) with buf.len() == x.len(); when it is not, gradient is ignored.

On return, the implementor’s internal fdist / frest state reflects this call (so a subsequent self.fdist() / self.frest() returns the same values as the EvalOutput’s fdist_max / frest_max).

Source

fn fdist(&self) -> F

Worst-atom distance violation from the most recent evaluate call.

Source

fn frest(&self) -> F

Worst-molecule restraint violation from the most recent evaluate call.

Source

fn ncf(&self) -> usize

Cumulative count of function-value evaluations since the last reset_eval_counters call.

Source

fn ncg(&self) -> usize

Cumulative count of gradient evaluations since the last reset_eval_counters call.

Source

fn reset_eval_counters(&mut self)

Zero the function / gradient counters. GENCAN calls this at the start of each outer iteration.

Provided Methods§

Source

fn bounds(&self, l: &mut [F], u: &mut [F])

Fill l and u (each of length x.len() at the pgencan entry) with per-variable bounds. The default implementation sets every variable to [-1e20, +1e20] (effectively unbounded); PackContext overrides it to add the Euler-angle bounds implied by constrain_rotation.

Landed in A.6 so pgencan no longer needs &mut PackContext for anything beyond evaluation — bounds construction is now behind the trait too.

Dyn Compatibility§

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors§