Simulation geometries and related operations. More...

Classes
class	BoundaryCondition
	A structure containing a type of boundary condition in each direction. More...

class	Chameleon
	Geometry class for spheres, cylinders, cuboids, hexagonal prism, truncated octahedron, slits. More...

class	Cuboid
	The cuboid geometry with periodic boundary conditions possibly applied in all three directions. More...

class	Cylinder
	The cylindrical geometry with periodic boundary conditions in z-axis (the height of the cylinder). More...

struct	GeometryBase
	An interface for all geometries.Base class for all geometries. More...

class	GeometryImplementation
	A base class for various geometries implementations. More...

class	HexagonalPrism
	The hexagonal prism geometry with periodic boundary conditions. More...

class	Hypersphere2d

struct	ShapeDescriptors
	Shape descriptors derived from gyration tensor. More...

class	Slit
	A legacy class for the cuboid geometry with periodic boundary conditions only in xy directions. More...

class	Sphere
	The spherical geometry where no periodic boundary condition could be applied. More...

class	TruncatedOctahedron
	The truncated octahedron geoemtry with periodic boundary conditions in all directions. More...

class	TwobodyAngles
	Structure for exploring a discrete, uniform angular space between two rigid bodies. More...

class	TwobodyAnglesState
	Structure for exploring a discrete, uniform angular space between two rigid bodies. More...

Typedefs
using	BoundaryFunction = std::function< void(Point &)>
	Function to apply PBC to a position.

using	DistanceFunction = std::function< Point(const Point &, const Point &)>
	Function to calculate the (minimum) distance between two points.

Enumerations
enum	Variant { CUBOID = 0, SPHERE, CYLINDER, SLIT, HEXAGONAL, OCTAHEDRON, HYPERSPHERE2D }
	Geometry variant used for Chameleon.

enum	VolumeMethod { ISOTROPIC, ISOCHORIC, XY, Z, INVALID }
	Various methods of volume scaling,. More...

enum	Boundary : int { FIXED = 0, PERIODIC = 1 }

enum	weight { MASS, CHARGE, GEOMETRIC }

Functions
void	from_json (const json &j, Chameleon &g)

void	to_json (json &j, const Chameleon &g)

ParticleVector	mapParticlesOnSphere (const ParticleVector &)
	Scale particles to the surface of a sphere. More...

void	to_json (json &j, const ShapeDescriptors &shape)
	Store Shape as json object.

	TEST_CASE ("[Faunus] ShapeDescriptors")

	TEST_CASE ("[Faunus] hexagonalPrismToCuboid")

	TEST_CASE ("[Faunus] spherical coordinates")

	TEST_CASE ("[Faunus] Geometry")

	TEST_CASE ("[Faunus] Chameleon")

	TEST_CASE ("[Faunus] weightedCenter")

	TEST_CASE ("[Faunus] gyration")

	TEST_CASE ("[Faunus] rootMeanSquareDeviation")

	NLOHMANN_JSON_SERIALIZE_ENUM (VolumeMethod, {{VolumeMethod::INVALID, nullptr}, {VolumeMethod::ISOTROPIC, "isotropic"}, {VolumeMethod::ISOCHORIC, "isochoric"}, {VolumeMethod::XY, "xy"}, {VolumeMethod::Z, "z"}}) enum class Coordinates

template<std::ranges::range Positions, std::ranges::range Weights>
Point	weightedCenter (const Positions &positions, const Weights &weights, Geometry::BoundaryFunction boundary=[](auto &) {}, const Point &shift=Point::Zero())
	Calculates the (weighted) center for a set of positions. More...

template<RequireParticleIterator iterator>
Point	weightedCenter (iterator begin, iterator end, BoundaryFunction boundary, std::function< double(const Particle &)> weight_function, const Point &shift=Point::Zero())
	Calculate Center of particle range using arbitrary weight functions applied to each particle. More...

template<RequireParticleIterator iterator>
Point	massCenter (iterator begin, iterator end, BoundaryFunction apply_boundary=[](Point &) {}, const Point &shift={0.0, 0.0, 0.0})
	Calculates mass center of range of particles. More...

template<RequireParticleIterator iterator>
void	translate (iterator begin, iterator end, const Point &displacement, BoundaryFunction apply_boundary=[](auto &) {})

template<RequireParticleIterator iterator>
void	translateToOrigin (iterator begin, iterator end, BoundaryFunction apply_boundary=[](auto &) {})
	Move the mass center of the particle range to origin (0,0,0) and wrap to PBC. More...

template<RequireParticleIterator iterator>
void	rotate (iterator begin, iterator end, const Eigen::Quaterniond &quaternion, BoundaryFunction apply_boundary=[](auto &) {}, const Point &shift=Point::Zero())
	Rotate range of particles using a Quaternion. More...

template<class Tspace , class GroupIndex >
Point	trigoCom (const Tspace &spc, const GroupIndex &indices, const std::vector< int > &dir={0, 1, 2})
	Calculate mass center of cluster of particles in unbounded environment. More...

template<RequirePointIterator position_iterator, std::forward_iterator mass_iterator>
Tensor	gyration (position_iterator begin, position_iterator end, mass_iterator mass, const Point &mass_center, const BoundaryFunction boundary=[](auto &) {})
	Calculates a gyration tensor of a range of particles. More...

template<RequireParticleIterator iterator>
Tensor	gyration (iterator begin, iterator end, const Point &mass_center, const BoundaryFunction boundary=[](auto &) {})
	Calculates a gyration tensor of a range of particles. More...

template<RequireParticleIterator iterator>
Tensor	inertia (iterator begin, iterator end, const Point origin=Point::Zero(), const BoundaryFunction boundary=[](auto &) {})
	Calculates an inertia tensor of a molecular group. More...

template<std::forward_iterator InputIt1, std::forward_iterator InputIt2, typename BinaryOperation >
double	rootMeanSquareDeviation (InputIt1 begin, InputIt1 end, InputIt2 d_begin, BinaryOperation diff_squared_func)
	Root-mean-square deviation of two data sets represented by iterators. More...

std::pair< Cuboid, ParticleVector >	hexagonalPrismToCuboid (const HexagonalPrism &hexagon, const RequireParticles auto &particles)
	Convert particles in hexagonal prism to space-filled cuboid. More...

Detailed Description

Simulation geometries and related operations.

Other parts of Faunus use directly only Chameleon geometry which serves as an interface. Based on the provided configuration, Chameleon initializes an appropriate concrete implementation, which it encapsulates.

To add a new geometry implementation, a class derived from GeometryImplementation is created. Geometry::Variant enum type is extended and an initialization within Chameleon::makeGeometry() is provided. In order to make geometry constructable from a json configuration, the map Chameleon::names is extended. When performance is an issue, inlineable implementation of vdist and boundary can be added into respective methods of Chameleon.

All geometry implementation shall be covered by unit tests.

Enumeration Type Documentation

◆ VolumeMethod

enum Faunus::Geometry::VolumeMethod

strong

Various methods of volume scaling,.

See also: GeometryBase::setVolume.

Function Documentation

◆ gyration() [1/2]

template<RequirePointIterator position_iterator, std::forward_iterator mass_iterator>

Tensor Faunus::Geometry::gyration	(	position_iterator	begin,
		position_iterator	end,
		mass_iterator	mass,
		const Point &	mass_center,
		const BoundaryFunction	boundary = `[](auto&) {}`
	)

Calculates a gyration tensor of a range of particles.

The gyration tensor is computed from the atomic position vectors with respect to the reference point which is always a center of mass,

S = (1 / m_i) m_i t_i t_i^T where t_i = r_i - r_cm

Before the calculation, the molecule is made whole to moving it to the center or the simulation box (0,0,0), then apply the given boundary function.

This is the polymer science definition of the gyration tensor which is mass-weighted. In physics, the gyration tensor is normally defined by positions only.

Parameters

begin	Iterator to first position
end	Iterator to past last position
mass	Iterator to first mass
mass_center	The mass center used as reference and to remove PBC
boundary	Function to apply periodic boundary functions (default: none)

Returns: gyration tensor; or zero tensor if empty particle range

Exceptions

If	total mass is non-positive

◆ gyration() [2/2]

template<RequireParticleIterator iterator>

Tensor Faunus::Geometry::gyration	(	iterator	begin,
		iterator	end,
		const Point &	mass_center,
		const BoundaryFunction	boundary = `[](auto&) {}`
	)

Calculates a gyration tensor of a range of particles.

The gyration tensor is computed from the atomic position vectors with respect to the reference point which is always a center of mass, \( t_{i} = r_{i} - r_\mathrm{cm} \): \( S = (1 / \sum_{i=1}^{N} m_{i}) \sum_{i=1}^{N} m_{i} t_{i} t_{i}^{T} \)

Before the calculation, the molecule is made whole to moving it to the center or the simulation box (0,0,0), then apply the given boundary function.

Template Parameters

iterator Iterator to Particle range

Parameters

begin	Iterator to first particle
end	Iterator to end
mass_center	The mass center used as reference and to remove PBC
boundary	Function to apply periodic boundary functions (default: none)

Returns: gyration tensor; or zero tensor if empty particle range

Exceptions

If	total mass is non-positive

◆ hexagonalPrismToCuboid()

std::pair<Cuboid, ParticleVector> Faunus::Geometry::hexagonalPrismToCuboid	(	const HexagonalPrism &	hexagon,
		const RequireParticles auto &	particles
	)

Convert particles in hexagonal prism to space-filled cuboid.

Parameters

hexagon	Input hexagonal prism
particles	Particles in hexagonal prism

Returns: Cuboid and particle vector w. positions in cuboidal space

The generated Cuboid has twice the volume of the hexagonal prism with side-lengths [2 * inner_radius, 3 * outer_radius, height] and also twice the number of particles

◆ inertia()

template<RequireParticleIterator iterator>

Tensor Faunus::Geometry::inertia	(	iterator	begin,
		iterator	end,
		const Point	origin = `Point::Zero()`,
		const BoundaryFunction	boundary = `[](auto&) {}`
	)

Calculates an inertia tensor of a molecular group.

The inertia tensor is computed from the atomic position vectors with respect to a reference point, \( t_{i} = r_{i} - r_\mathrm{origin} \): \( S = \sum_{i=1}^{N} m_{i} ( t_{i} \cdot t_{i} I - t_{i} t_{i}^{T} ) \)

Parameters

origin a reference point

Returns: inertia tensor (a zero tensor for an empty group)

◆ mapParticlesOnSphere()

ParticleVector Faunus::Geometry::mapParticlesOnSphere ( const ParticleVector & )

Scale particles to the surface of a sphere.

Parameters

particles Vector of particles

The sphere radius is taken as the average radial distance of all particles with respect to the mass center. The first particle of the given particles is excluded from the COM calculation and re-positioned at the center of the sphere. Therefore, make sure to add a dummy particle to the beginning of the particle vector; its initial positions are ignored and will be overwritten. Similar to routine described in doi:10.1021/jp010360o

◆ massCenter()

template<RequireParticleIterator iterator>

Point Faunus::Geometry::massCenter	(	iterator	begin,
		iterator	end,
		BoundaryFunction	apply_boundary = `[](Point&) {}`,
		const Point &	shift = `{0.0, 0.0, 0.0}`
	)

Calculates mass center of range of particles.

Parameters

begin	Begin particle iterator
end	End particle iterator
apply_boundary	Boundary function to apply PBC (default: no PBC)
shift	Shift by this vector before calculating center, then add again. For PBC removal; default: 0,0,0

Returns: Mass center position

Exceptions

if	the sum of masses is zero, thereby hampering normalization

◆ rootMeanSquareDeviation()

template<std::forward_iterator InputIt1, std::forward_iterator InputIt2, typename BinaryOperation >

double Faunus::Geometry::rootMeanSquareDeviation	(	InputIt1	begin,
		InputIt1	end,
		InputIt2	d_begin,
		BinaryOperation	diff_squared_func
	)

Root-mean-square deviation of two data sets represented by iterators.

A binary function must be given that returns the difference between data points in the two sets, for example [](int a, int b){return a-b;}.

◆ rotate()

template<RequireParticleIterator iterator>

void Faunus::Geometry::rotate	(	iterator	begin,
		iterator	end,
		const Eigen::Quaterniond &	quaternion,
		BoundaryFunction	apply_boundary = `[](auto&) {}`,
		const Point &	shift = `Point::Zero()`
	)

Rotate range of particles using a Quaternion.

Parameters

begin	Begin particle iterator
end	End particle iterator
quaternion	Quaternion used for rotation
apply_boundary	Boundary function to apply PBC (default: none)
shift	This value is added before rotation to aid PBC remove (default: 0,0,0)

Todo:: Currently both quaternion and rotation matrix are passed, but one of them should be enough

This will rotate both positions and internal coordinates in the particle (dipole moments, tensors etc.)Rotate particle pos and internal coordinates

◆ TEST_CASE()

Faunus::Geometry::TEST_CASE ( " Chameleon" [Faunus] )

function compares if Chamelon's and Geometry's boundary methods produce the same result using n random points

function compares if Chamelon's and Geometry's vdist methods produce the same result using n random points

◆ translate()

template<RequireParticleIterator iterator>

void Faunus::Geometry::translate	(	iterator	begin,
		iterator	end,
		const Point &	displacement,
		BoundaryFunction	apply_boundary = `[](auto&) {}`
	)

Parameters

begin	Begin iterator
end	End iterator
displacement	Displacement vector
apply_boundary	Boundary function to apply PBC (default: no PBC)

◆ translateToOrigin()

template<RequireParticleIterator iterator>

void Faunus::Geometry::translateToOrigin	(	iterator	begin,
		iterator	end,
		BoundaryFunction	apply_boundary = `[](auto&) {}`
	)

Move the mass center of the particle range to origin (0,0,0) and wrap to PBC.

Parameters

begin	Begin iterator
end	End iterator
apply_boundary	Boundary function to apply PBC (default: none)

◆ trigoCom()

template<class Tspace , class GroupIndex >

Point Faunus::Geometry::trigoCom	(	const Tspace &	spc,
		const GroupIndex &	indices,
		const std::vector< int > &	dir = `{0, 1, 2}`
	)

Calculate mass center of cluster of particles in unbounded environment.

More info

◆ weightedCenter() [1/2]

template<std::ranges::range Positions, std::ranges::range Weights>

Point Faunus::Geometry::weightedCenter	(	const Positions &	positions,
		const Weights &	weights,
		Geometry::BoundaryFunction	boundary = `[](auto&) {}`,
		const Point &	shift = `Point::Zero()`
	)

Calculates the (weighted) center for a set of positions.

Parameters

positions	Positions
weights	Weights (ones, masses, charges etc.)
boundary	Used to remove periodic boundaries
shift	Shift with this value before and after center calculation. To e.g. remove PBC

◆ weightedCenter() [2/2]

template<RequireParticleIterator iterator>

Point Faunus::Geometry::weightedCenter	(	iterator	begin,
		iterator	end,
		BoundaryFunction	boundary,
		std::function< double(const Particle &)>	weight_function,
		const Point &	shift = `Point::Zero()`
	)

Calculate Center of particle range using arbitrary weight functions applied to each particle.

Parameters

begin	Begin particle iterator
end	End parti cle iterator
boundary	Boundary function to apply PBC (default: no PBC)
weight_function	Functor return weight for a given particle
shift	Shift by this vector before calculating center, then add again. For PBC removal; default: 0,0,0

Returns: Center position; (0,0,0) if the sum of weights is zero

Exceptions

warning if the sum of weights is zero, thereby hampering normalizationMass, charge, or geometric center of a collection of particles

Classes

Typedefs

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ VolumeMethod

Function Documentation

◆ gyration() [1/2]

◆ gyration() [2/2]

◆ hexagonalPrismToCuboid()

◆ inertia()

◆ mapParticlesOnSphere()

◆ massCenter()

◆ rootMeanSquareDeviation()

◆ rotate()

◆ TEST_CASE()

◆ translate()

◆ translateToOrigin()

◆ trigoCom()

◆ weightedCenter() [1/2]

◆ weightedCenter() [2/2]