apocharmm.cuda_langevin_piston_integrator.CudaLangevinPistonIntegrator Class Reference

Provides pressure-controlled Langevin-piston dynamics. More...

Inheritance diagram for apocharmm.cuda_langevin_piston_integrator.CudaLangevinPistonIntegrator:

Public Member Functions
None	__init__ (self, float time_step)
	Constructs a Python-owned Langevin-piston integrator.
None	useNoseHooverThermostat (self, bool flag=True)
	Enables or disables Nose-Hoover temperature coupling.
None	setReferenceTemperature (self, float temperature)
	Sets the piston reference temperature.
None	setNoseHooverPistonMass (self, float mass)
	Sets the scalar Nose-Hoover coupling mass.
None	useOldTemperature (self, bool flag=True)
	Selects the native on-step temperature estimator.
None	setReferencePressure (self, Sequence[Sequence[float]] pressure_tensor)
	Sets the row-major reference pressure tensor.
None	setConstantSurfaceTension (self, bool flag=True)
	Enables or disables the constant-surface-tension branch.
None	setCrystalType (self, CrystalType|int crystal_type)
	Selects crystal symmetry and reallocates piston state.
None	setLangevinPistonMass (self, Sequence[float] masses)
	Sets crystal-sized Langevin-piston masses.
None	setLangevinPistonFrictionSeed (self, int seed)
	Sets the piston RNG seed.
None	setLangevinPistonFriction (self, float friction)
	Sets the Langevin-piston friction coefficient.
None	resetAverages (self)
	Resets temperature and pressure running averages.
float	getReferenceTemperature (self)
	Returns the piston reference temperature.
float	getNoseHooverPistonMass (self)
	Returns the scalar Nose-Hoover coupling mass.
float	getAverageTemperature (self)
	Returns one running-average temperature.
list[list[float]]	getReferencePressureTensor (self)
	Returns the reference pressure tensor.
CrystalType	getCrystalType (self)
	Returns the selected crystal type.
list[float]	getLangevinPistonMass (self)
	Returns the crystal-sized Langevin-piston masses.
list[list[float]]	getInstantaneousPressureTensor (self)
	Returns the instantaneous pressure tensor.
float	getInstantaneousPressureScalar (self)
	Returns the instantaneous scalar pressure.
list[list[float]]	getAveragePressureTensor (self)
	Returns the running-average pressure tensor.
float	getAveragePressureScalar (self)
	Returns the running-average scalar pressure.
int	getLangevinPistonFrictionSeed (self)
	Returns the Langevin-piston RNG seed.
float	getInstantaneousTemperature (self)
	Returns the native selected instantaneous temperature.
Public Member Functions inherited from apocharmm.cuda_integrator.CudaIntegrator
ctypes.c_void_p	integrator_handle (self)
	Returns the borrowed C base-integrator pointer.
None	close (self)
	Closes the concrete handle and invalidates the base view.
None	setTimeStep (self, float time_step)
	Sets the public integrator time step.
None	setCharmmContext (self, CharmmContext context)
	Attaches a context and initializes concrete native state.
None	subscribe (self, Subscriber subscriber)
	Subscribes one output wrapper.
None	unsubscribe (self, Subscriber subscriber)
	Removes one subscriber from native and Python scheduling state.
None	propagate (self, int num_steps)
	Propagates dynamics and scheduled subscribers.
None	initializeFromRestartFile (self, FilePath path)
	Initializes concrete state from a restart file.

Detailed Description

Provides pressure-controlled Langevin-piston dynamics.

Select a supported CrystalType before attaching a context. The wrapper owns the concrete piston C handle and inherits common context, propagation, restart, subscriber, and closure operations.

See also

cuda_integrators

Constructor & Destructor Documentation

__init__()

None apocharmm.cuda_langevin_piston_integrator.CudaLangevinPistonIntegrator.__init__	(		self,
		float	time_step
	)

Constructs a Python-owned Langevin-piston integrator.

Parameters

[in]

time_step

Value converted to C double, interpreted as a finite positive time step in picoseconds.

Exceptions

TypeError	If conversion fails.
ApoCharmmError	With native status APO_STATUS_INVALID_ARGUMENT, APO_STATUS_CUDA_ERROR, or APO_STATUS_RUNTIME_ERROR.
RuntimeError	If a successful native call produces a NULL concrete or base-view handle.

Postcondition

The crystal type remains CrystalType.NONE until explicitly set.

Reimplemented from apocharmm.cuda_integrator.CudaIntegrator.

Member Function Documentation

getAveragePressureScalar()

float apocharmm.cuda_langevin_piston_integrator.CudaLangevinPistonIntegrator.getAveragePressureScalar

(

self

)

Returns the running-average scalar pressure.

Returns

A new Python float in atmospheres.

Exceptions

RuntimeError	If the wrapper is closed.
ApoCharmmError	If native validation, shape checking, transfer, or output fails.

getAveragePressureTensor()

list[list[float]] apocharmm.cuda_langevin_piston_integrator.CudaLangevinPistonIntegrator.getAveragePressureTensor

(

self

)

Returns the running-average pressure tensor.

Returns

A newly allocated 3-by-3 row-major nested list in atmospheres.

Exceptions

RuntimeError	If the wrapper is closed.
ApoCharmmError	If native validation, shape checking, transfer, or output fails.

getAverageTemperature()

float apocharmm.cuda_langevin_piston_integrator.CudaLangevinPistonIntegrator.getAverageTemperature

(

self

)

Returns one running-average temperature.

Returns

A new Python float in kelvin.

Exceptions

RuntimeError	If the wrapper is closed.
ApoCharmmError	If native validation, shape checking, or transfer fails.

Warning

Current C ABI behavior returns estimator element 0 when old-temperature mode is enabled and element 1 when it is disabled, opposite the native instantaneous-temperature selector.

getCrystalType()

CrystalType apocharmm.cuda_langevin_piston_integrator.CudaLangevinPistonIntegrator.getCrystalType

(

self

)

Returns the selected crystal type.

Returns

A new CrystalType, including CrystalType.NONE before configuration.

Exceptions

RuntimeError	If the wrapper is closed.
ApoCharmmError	If native validation or enum conversion fails.
ValueError	If the returned C integer is not a Python CrystalType value.

getInstantaneousPressureScalar()

float apocharmm.cuda_langevin_piston_integrator.CudaLangevinPistonIntegrator.getInstantaneousPressureScalar

(

self

)

Returns the instantaneous scalar pressure.

Returns

A new Python float in atmospheres.

Exceptions

RuntimeError	If the wrapper is closed.
ApoCharmmError	If native validation, shape checking, transfer, or output fails.

getInstantaneousPressureTensor()

list[list[float]] apocharmm.cuda_langevin_piston_integrator.CudaLangevinPistonIntegrator.getInstantaneousPressureTensor

(

self

)

Returns the instantaneous pressure tensor.

Returns

A newly allocated 3-by-3 row-major nested list in atmospheres.

Exceptions

RuntimeError	If the wrapper is closed.
ApoCharmmError	If native validation, shape checking, transfer, or output fails.

getInstantaneousTemperature()

float apocharmm.cuda_langevin_piston_integrator.CudaLangevinPistonIntegrator.getInstantaneousTemperature

(

self

)

Returns the native selected instantaneous temperature.

Returns

A new Python float in kelvin. Native selection uses kinetic-energy element 1 when old-temperature mode is enabled and element 0 otherwise.

Exceptions

RuntimeError	If the wrapper is closed.
ApoCharmmError	With native status APO_STATUS_NOT_INITIALIZED before context attachment, APO_STATUS_CUDA_ERROR for transfer failure, or another documented native status.

getLangevinPistonFrictionSeed()

int apocharmm.cuda_langevin_piston_integrator.CudaLangevinPistonIntegrator.getLangevinPistonFrictionSeed

(

self

)

Returns the Langevin-piston RNG seed.

Returns

A new non-negative Python int in the uint64 range.

Exceptions

RuntimeError	If the wrapper is closed.
ApoCharmmError	If native validation or output fails.

getLangevinPistonMass()

list[float] apocharmm.cuda_langevin_piston_integrator.CudaLangevinPistonIntegrator.getLangevinPistonMass

(

self

)

Returns the crystal-sized Langevin-piston masses.

Returns

A newly allocated list containing zero, one, two, or three Python float values in active crystal-degree-of-freedom order.

Exceptions

RuntimeError	If the wrapper is closed.
ApoCharmmError	If native validation, count checking, transfer, or output fails.

getNoseHooverPistonMass()

float apocharmm.cuda_langevin_piston_integrator.CudaLangevinPistonIntegrator.getNoseHooverPistonMass

(

self

)

Returns the scalar Nose-Hoover coupling mass.

Returns

A new Python float in the native coupling-mass convention.

Exceptions

RuntimeError	If the wrapper is closed.
ApoCharmmError	If native validation, shape checking, transfer, or output fails.

getReferencePressureTensor()

list[list[float]] apocharmm.cuda_langevin_piston_integrator.CudaLangevinPistonIntegrator.getReferencePressureTensor

(

self

)

Returns the reference pressure tensor.

Returns

A newly allocated 3-by-3 nested list of Python float values in row-major order and atmospheres. The result does not alias native storage.

Exceptions

RuntimeError	If the wrapper is closed.
ApoCharmmError	If native validation, shape checking, transfer, or output fails.

getReferenceTemperature()

float apocharmm.cuda_langevin_piston_integrator.CudaLangevinPistonIntegrator.getReferenceTemperature

(

self

)

Returns the piston reference temperature.

Returns

A new Python float in kelvin.

Exceptions

RuntimeError	If the wrapper is closed.
ApoCharmmError	If native validation or output fails.

resetAverages()

None apocharmm.cuda_langevin_piston_integrator.CudaLangevinPistonIntegrator.resetAverages

(

self

)

Resets temperature and pressure running averages.

Returns

None.

Exceptions

RuntimeError	If the wrapper is closed.
ApoCharmmError	If native validation or a device reset fails.

setConstantSurfaceTension()

None apocharmm.cuda_langevin_piston_integrator.CudaLangevinPistonIntegrator.setConstantSurfaceTension	(		self,
		bool	flag = True
	)

Enables or disables the constant-surface-tension branch.

Parameters

[in]

flag

Value converted with ctypes.c_bool.

Returns

None.

Exceptions

TypeError	If C boolean conversion rejects the value.
RuntimeError	If the wrapper is closed.
ApoCharmmError	If the native handle is rejected.

Warning

The current API has no target-surface-tension setter and the native target value is not initialized after allocation. Do not enable this mode until that implementation defect is corrected.

setCrystalType()

None apocharmm.cuda_langevin_piston_integrator.CudaLangevinPistonIntegrator.setCrystalType	(		self,
		CrystalType | int	crystal_type
	)

Selects crystal symmetry and reallocates piston state.

Parameters

[in]

crystal_type

CrystalType.CUBIC, CrystalType.TETRAGONAL, CrystalType.ORTHORHOMBIC, or another object accepted by int() whose resulting value names one of those enums.

Returns

None.

Exceptions

TypeError	If int() or ctypes.c_int rejects the value.
ValueError	If integer conversion fails or the native enum value is unsupported, including CrystalType.NONE.
OverflowError	If the value cannot be represented by ctypes.c_int.
RuntimeError	If the wrapper is closed.
ApoCharmmError	With native status APO_STATUS_INVALID_ARGUMENT, APO_STATUS_CUDA_ERROR, or APO_STATUS_RUNTIME_ERROR.

Warning

Reconfiguration resets crystal-sized state and can invalidate native aliases.

setLangevinPistonFriction()

None apocharmm.cuda_langevin_piston_integrator.CudaLangevinPistonIntegrator.setLangevinPistonFriction	(		self,
		float	friction
	)

Sets the Langevin-piston friction coefficient.

Parameters

[in]

friction

Value converted to C double, in inverse picoseconds. It must be finite and non-negative.

Returns

None.

Exceptions

TypeError	If conversion fails.
RuntimeError	If the wrapper is closed.
ApoCharmmError	With native status APO_STATUS_NOT_INITIALIZED before crystal selection, APO_STATUS_INVALID_ARGUMENT for an invalid value, APO_STATUS_CUDA_ERROR for factor transfer failure, or APO_STATUS_RUNTIME_ERROR for another native failure.

setLangevinPistonFrictionSeed()

None apocharmm.cuda_langevin_piston_integrator.CudaLangevinPistonIntegrator.setLangevinPistonFrictionSeed	(		self,
		int	seed
	)

Sets the piston RNG seed.

Parameters

[in]

seed

Python integer in [0, 2**64 - 1].

Returns

None.

Exceptions

TypeError	If comparison or uint64 conversion rejects the value.
ValueError	If the value is outside the uint64 range.
RuntimeError	If the wrapper is closed.
ApoCharmmError	If selected-crystal RNG allocation or initialization fails.

Postcondition

The recorded native sequence position is preserved.

setLangevinPistonMass()

None apocharmm.cuda_langevin_piston_integrator.CudaLangevinPistonIntegrator.setLangevinPistonMass	(		self,
		Sequence[float]	masses
	)

Sets crystal-sized Langevin-piston masses.

The sequence is eagerly converted with float() and copied into a temporary contiguous C buffer.

Parameters

[in]

masses

One, two, or three finite non-negative values whose length exactly matches the selected crystal degree-of-freedom count. The exact dimensional convention is not established by the repository.

Returns

None.

Exceptions

TypeError	If masses is not iterable or a value cannot be converted to float.
ValueError	If float() rejects a value.
RuntimeError	If the wrapper is closed.
ApoCharmmError	With native status APO_STATUS_NOT_INITIALIZED before crystal selection, APO_STATUS_INVALID_ARGUMENT for length or value validation, APO_STATUS_CUDA_ERROR for device update failure, or APO_STATUS_RUNTIME_ERROR for another native failure.

setNoseHooverPistonMass()

None apocharmm.cuda_langevin_piston_integrator.CudaLangevinPistonIntegrator.setNoseHooverPistonMass	(		self,
		float	mass
	)

Sets the scalar Nose-Hoover coupling mass.

Parameters

[in]

mass

Value converted to C double. It must be finite and non-negative. Its exact dimensional convention is not established.

Returns

None.

Exceptions

TypeError	If conversion fails.
RuntimeError	If the wrapper is closed.
ApoCharmmError	If native validation or device update fails.

Warning

Zero is accepted, but enabled Nose-Hoover propagation divides by this value.

setReferencePressure()

None apocharmm.cuda_langevin_piston_integrator.CudaLangevinPistonIntegrator.setReferencePressure	(		self,
		Sequence[Sequence[float]]	pressure_tensor
	)

Sets the row-major reference pressure tensor.

The wrapper iterates the outer object, iterates each inner object, converts every value with float(), and flattens all values into a temporary contiguous C buffer. Native validation requires exactly nine total values but the wrapper does not independently require a 3-by-3 nested shape.

Parameters

[in]

pressure_tensor

Iterable of iterables whose flattened values are ordered xx, xy, xz, yx, yy, yz, zx, zy, zz and interpreted in atmospheres.

Returns

None.

Exceptions

TypeError	If an input is not iterable or a value cannot be converted to float.
ValueError	If float() rejects a value.
RuntimeError	If the wrapper is closed.
ApoCharmmError	With native status APO_STATUS_INVALID_ARGUMENT for a non-nine-element or non-finite tensor, APO_STATUS_CUDA_ERROR for transfer failure, or APO_STATUS_RUNTIME_ERROR for another native failure.

setReferenceTemperature()

None apocharmm.cuda_langevin_piston_integrator.CudaLangevinPistonIntegrator.setReferenceTemperature	(		self,
		float	temperature
	)

Sets the piston reference temperature.

Parameters

[in]

temperature

Value converted to C double, in kelvin. It must be finite and non-negative.

Returns

None.

Exceptions

TypeError	If conversion fails.
RuntimeError	If the wrapper is closed.
ApoCharmmError	If native validation, factor recomputation, or device transfer fails.

useNoseHooverThermostat()

None apocharmm.cuda_langevin_piston_integrator.CudaLangevinPistonIntegrator.useNoseHooverThermostat	(		self,
		bool	flag = True
	)

Enables or disables Nose-Hoover temperature coupling.

Parameters

[in]

flag

Value converted with ctypes.c_bool. A truthy value enables the coupling.

Returns

None.

Exceptions

TypeError	If C boolean conversion rejects the value.
RuntimeError	If the wrapper is closed.
ApoCharmmError	If the native handle is rejected.

useOldTemperature()

None apocharmm.cuda_langevin_piston_integrator.CudaLangevinPistonIntegrator.useOldTemperature	(		self,
		bool	flag = True
	)

Selects the native on-step temperature estimator.

Parameters

[in]

flag

Value converted with ctypes.c_bool. A truthy value selects kinetic-energy element 1 for native feedback and instantaneous temperature.

Returns

None.

Exceptions

TypeError	If C boolean conversion rejects the value.
RuntimeError	If the wrapper is closed.
ApoCharmmError	If the native handle is rejected.