eonc::xtsci_eindir Namespace Reference

Classes
struct	View
	Semantic objective contract shared with eindir_objective_descriptor_t. More...

Functions
View	eon_requirement ()
	What an eOn minimization may consume: eV, angstrom, analytic forces.
View	rgpot_ev_angstrom ()
	rgpot producer advertising the same units and tensor contract.
bool	compatible (const View &actual, const View &required)
	Nonzero when actual satisfies required. Schema id is never a wildcard.
bool	abi_accepts_gradient (std::uint32_t major, std::uint32_t expected_major, std::uint64_t features)
	Major must match and the gradient feature bit must be set.
const std::string &	provenance ()
	Stamp text from the last successful eindir bind. Empty when unused.
State *	bind (ObjectiveFunction *objective, Eigen::VectorXd *cached)
	Borrow an ObjectiveFunction as an eindir objective.
void	release (State *state)
int	eval_grad (State *state, const DLManagedTensorVersioned *x, double *value, DLManagedTensorVersioned *gradient)
	One fused energy and gradient through the borrowed eindir handle.
int	minimize (State *state, double *x, std::size_t n, std::size_t maxiter, double gtol, double istep, std::size_t memory, int method, double *value_out)
	xts_minimize_eindir on a caller-owned buffer. The caller keeps State.

Variables
constexpr const char *	kSchemaId = "eindir.objective-descriptor.v1"
constexpr std::uint64_t	kOpEnergy = 1ull << 0
constexpr std::uint64_t	kOpForces = 1ull << 1
constexpr int	kDeviceCpu = 1
constexpr int	kDtypeFloat = 2
constexpr std::uint32_t	kLayoutContiguous = 1
constexpr std::uint32_t	kLifetimeBorrowed = 1
constexpr std::uint64_t	kFeatureGradient = 1ull << 0

Function Documentation

abi_accepts_gradient()

bool eonc::xtsci_eindir::abi_accepts_gradient	(	std::uint32_t	major,
		std::uint32_t	expected_major,
		std::uint64_t	features )

Major must match and the gradient feature bit must be set.

Definition at line 182 of file XtsciEindir.cpp.

                                                {
  return major == expected_major && (features & kFeatureGradient) != 0;
}

bind()

State * eonc::xtsci_eindir::bind	(	ObjectiveFunction *	objective,
		Eigen::VectorXd *	cached )

Borrow an ObjectiveFunction as an eindir objective.

Null when eindir is not linked. Does not take ownership of the objective or the cache.

Definition at line 189 of file XtsciEindir.cpp.

                                                                 {
#ifndef WITH_EINDIR
  (void)objective;
  (void)cached;
  return nullptr;
#else
  if (objective == nullptr || objective->degreesOfFreedom() <= 0) {
    return nullptr;
  }
  auto state = std::make_unique<State>();
  state->objective = objective;
  state->cached = cached;
  const auto dim = static_cast<std::size_t>(objective->degreesOfFreedom());
  const double inf = std::numeric_limits<double>::infinity();
  state->low.assign(dim, -inf);
  state->high.assign(dim, inf);
  View actual = eon_requirement();
  actual.producer_id = "eon.objective";
  state->schema = actual.schema_id;
  state->producer = actual.producer_id;
  state->length_unit = actual.length_unit;
  state->energy_unit = actual.energy_unit;
  state->desc.schema_id = state->schema.c_str();
  state->desc.producer_id = state->producer.c_str();
  state->desc.length_unit = state->length_unit.c_str();
  state->desc.energy_unit = state->energy_unit.c_str();
  state->desc.energy_sign = actual.energy_sign;
  state->desc.gradient_sign = actual.gradient_sign;
  state->desc.operations = actual.operations;
  state->desc.tensor_device_type = actual.tensor_device_type;
  state->desc.tensor_dtype_code = actual.tensor_dtype_code;
  state->desc.tensor_dtype_bits =
      static_cast<std::uint8_t>(actual.tensor_dtype_bits);
  state->desc.tensor_dtype_lanes =
      static_cast<std::uint8_t>(actual.tensor_dtype_lanes);
  state->desc.tensor_layout = actual.tensor_layout;
  state->desc.callback_lifetime = actual.callback_lifetime;
  state->obj.dim = dim;
  state->obj.low = state->low.data();
  state->obj.high = state->high.data();
  state->obj.eval_fn = eval_cb;
  state->obj.grad_fn = grad_cb;
  state->obj.user_data = state.get();
  state->obj.free_fn = nullptr;
  state->obj.descriptor = &state->desc;
  if (!compatible(actual, eon_requirement())) {
    throw std::runtime_error("eOn eindir objective descriptor was rejected");
  }
  const auto stamp = eindir_core_abi_stamp();
  if (eindir_core_abi_compatible(&stamp) == 0 ||
      !abi_accepts_gradient(stamp.abi_major, 1, stamp.features)) {
    throw std::runtime_error("incompatible eindir ABI stamp");
  }
  if (eindir_objective_has_grad(&state->obj) == 0) {
    throw std::runtime_error("eindir objective has no gradient");
  }
  eindir_objective_descriptor_t required_desc = state->desc;
  required_desc.producer_id = "";
  if (eindir_objective_descriptor_compatible(&state->desc, &required_desc) ==
      0) {
    const char *err = eindir_last_error();
    throw std::runtime_error(err != nullptr ? err
                                            : "eindir descriptor mismatch");
  }
  const auto xts = xts_abi_stamp();
  provenance_slot() =
      std::format("xts-{}.{}.{}+eindir-{}.{}-layout-{}", xts.abi_major,
                  xts.abi_minor, xts.layout_revision, stamp.abi_major,
                  stamp.abi_minor, stamp.objective_layout);
  return state.release();
#endif
}

compatible()

bool eonc::xtsci_eindir::compatible	(	const View &	actual,
		const View &	required )

Nonzero when actual satisfies required. Schema id is never a wildcard.

Definition at line 156 of file XtsciEindir.cpp.

                                                          {
  if (actual.schema_id.empty() || actual.schema_id != required.schema_id) {
    return false;
  }
  if (!text_ok(actual.producer_id, required.producer_id) ||
      !text_ok(actual.length_unit, required.length_unit) ||
      !text_ok(actual.energy_unit, required.energy_unit)) {
    return false;
  }
  if (!scalar_ok(actual.energy_sign, required.energy_sign) ||
      !scalar_ok(actual.gradient_sign, required.gradient_sign)) {
    return false;
  }
  if ((actual.operations & required.operations) != required.operations) {
    return false;
  }
  return scalar_ok(actual.tensor_device_type, required.tensor_device_type) &&
         scalar_ok(actual.tensor_dtype_code, required.tensor_dtype_code) &&
         scalar_ok(actual.tensor_dtype_bits, required.tensor_dtype_bits) &&
         scalar_ok(actual.tensor_dtype_lanes, required.tensor_dtype_lanes) &&
         scalar_ok(static_cast<long>(actual.tensor_layout),
                   static_cast<long>(required.tensor_layout)) &&
         scalar_ok(static_cast<long>(actual.callback_lifetime),
                   static_cast<long>(required.callback_lifetime));
}

eon_requirement()

View eonc::xtsci_eindir::eon_requirement

(

)

What an eOn minimization may consume: eV, angstrom, analytic forces.

Definition at line 133 of file XtsciEindir.cpp.

                       {
  View view;
  view.schema_id = kSchemaId;
  view.length_unit = "angstrom";
  view.energy_unit = "eV";
  view.energy_sign = 1;
  view.gradient_sign = 1;
  view.operations = kOpEnergy | kOpForces;
  view.tensor_device_type = kDeviceCpu;
  view.tensor_dtype_code = kDtypeFloat;
  view.tensor_dtype_bits = 64;
  view.tensor_dtype_lanes = 1;
  view.tensor_layout = kLayoutContiguous;
  view.callback_lifetime = kLifetimeBorrowed;
  return view;
}

eval_grad()

int eonc::xtsci_eindir::eval_grad	(	State *	state,
		const DLManagedTensorVersioned *	x,
		double *	value,
		DLManagedTensorVersioned *	gradient )

One fused energy and gradient through the borrowed eindir handle.

Definition at line 270 of file XtsciEindir.cpp.

                                                  {
#ifndef WITH_EINDIR
  (void)state;
  (void)x;
  (void)value;
  (void)gradient;
  return 2;
#else
  if (state == nullptr) {
    return 1;
  }
  if (eindir_objective_eval(&state->obj, x, value) != EINDIR_SUCCESS ||
      eindir_objective_grad(&state->obj, x, gradient) != EINDIR_SUCCESS) {
    return 2;
  }
  return 0;
#endif
}

minimize()

int eonc::xtsci_eindir::minimize	(	State *	state,
		double *	x,
		std::size_t	n,
		std::size_t	maxiter,
		double	gtol,
		double	istep,
		std::size_t	memory,
		int	method,
		double *	value_out )

xts_minimize_eindir on a caller-owned buffer. The caller keeps State.

Definition at line 290 of file XtsciEindir.cpp.

                                {
#ifndef WITH_EINDIR
  (void)state;
  (void)x;
  (void)n;
  (void)maxiter;
  (void)gtol;
  (void)istep;
  (void)memory;
  (void)method;
  (void)value_out;
  return 1;
#else
  if (state == nullptr || x == nullptr) {
    return 1;
  }
  auto *tensor = xts_tensor_borrow_cpu_f64(x, n);
  if (tensor == nullptr) {
    return 2;
  }
  const auto stamp = eindir_core_abi_stamp();
  xts_control_t control{maxiter, gtol, istep, memory, 0.0};
  xts_report_t report{};
  const auto status =
      xts_minimize_eindir(&state->obj, &stamp, tensor, &control,
                          static_cast<xts_method_t>(method), &report);
  xts_tensor_free(tensor);
  if (value_out != nullptr) {
    *value_out = report.value;
  }
  return static_cast<int>(status);
#endif
}

provenance()

const std::string & eonc::xtsci_eindir::provenance

(

)

Stamp text from the last successful eindir bind. Empty when unused.

Definition at line 187 of file XtsciEindir.cpp.

{ return provenance_slot(); }

release()

void eonc::xtsci_eindir::release

(

State *

state

)

Definition at line 262 of file XtsciEindir.cpp.

                           {
#ifdef WITH_EINDIR
  delete state;
#else
  (void)state;
#endif
}

rgpot_ev_angstrom()

View eonc::xtsci_eindir::rgpot_ev_angstrom

(

)

rgpot producer advertising the same units and tensor contract.

Definition at line 150 of file XtsciEindir.cpp.

                         {
  View view = eon_requirement();
  view.producer_id = "rgpot";
  return view;
}

Variable Documentation

kDeviceCpu

int eonc::xtsci_eindir::kDeviceCpu = 1

inlineconstexpr

Definition at line 45 of file XtsciEindir.h.

kDtypeFloat

int eonc::xtsci_eindir::kDtypeFloat = 2

inlineconstexpr

Definition at line 46 of file XtsciEindir.h.

kFeatureGradient

std::uint64_t eonc::xtsci_eindir::kFeatureGradient = 1ull << 0

inlineconstexpr

Definition at line 49 of file XtsciEindir.h.

kLayoutContiguous

std::uint32_t eonc::xtsci_eindir::kLayoutContiguous = 1

inlineconstexpr

Definition at line 47 of file XtsciEindir.h.

kLifetimeBorrowed

std::uint32_t eonc::xtsci_eindir::kLifetimeBorrowed = 1

inlineconstexpr

Definition at line 48 of file XtsciEindir.h.

kOpEnergy

std::uint64_t eonc::xtsci_eindir::kOpEnergy = 1ull << 0

inlineconstexpr

Definition at line 43 of file XtsciEindir.h.

kOpForces

std::uint64_t eonc::xtsci_eindir::kOpForces = 1ull << 1

inlineconstexpr

Definition at line 44 of file XtsciEindir.h.

kSchemaId

const char* eonc::xtsci_eindir::kSchemaId = "eindir.objective-descriptor.v1"

inlineconstexpr

Definition at line 42 of file XtsciEindir.h.