pfc::world Namespace Reference

Namespace for decomposition-related classes and functions. More...

Classes
struct	World
	Represents the global simulation domain (the "world"). More...

Typedefs
using	CartesianWorld = World< CartesianTag >
	Type alias for Cartesian 3D World (most common usage)

Functions
template<typename T >
auto	create (const World< T > &world, const heffte::box3d< int > &box)
	Construct a new World object from an existing one and a box.
template<typename T >
auto	to_indices (const World< T > &world)
template<typename T >
auto	split_world (const World< T > &world, const Int3 &grid)
CartesianWorld	create (const Int3 &size)
	Create a World object with the specified size and default offset and spacing.
CartesianWorld	create (const GridSize &size, const PhysicalOrigin &origin, const GridSpacing &spacing)
	Create a World object with strong types for type safety.
CartesianWorld	create (const Int3 &size, const Real3 &offset, const Real3 &spacing)
	Create a World object with raw arrays (DEPRECATED)
CartesianWorld	uniform (int size)
	Create uniform grid with unit spacing at origin.
CartesianWorld	uniform (int size, double spacing)
	Create uniform grid with specified spacing.
CartesianWorld	from_bounds (Int3 size, Real3 lower, Real3 upper, Bool3 periodic={true, true, true})
	Create grid from physical bounds (automatically computes spacing).
CartesianWorld	with_spacing (Int3 size, Real3 spacing)
	Create grid with default origin but custom spacing.
CartesianWorld	with_origin (Int3 size, Real3 origin)
	Create grid with custom origin but unit spacing.
template<typename T >
Int3	get_size (const World< T > &world) noexcept
template<typename T >
int	get_size (const World< T > &world, int index)
template<typename T >
size_t	get_total_size (const World< T > &world) noexcept
const auto &	get_lower (const CartesianWorld &world) noexcept
	Get the lower bounds of the world.
const auto &	get_lower (const CartesianWorld &world, int index)
	Get the lower bounds of the world in a specific dimension.
const auto &	get_upper (const CartesianWorld &world) noexcept
	Get the upper bounds of the world in a specific dimension.
auto	get_upper (const CartesianWorld &world, int index)
	Get the upper bounds of the world in a specific dimension.
template<typename T >
const auto &	get_coordinate_system (const World< T > &world) noexcept
	Get the coordinate system of the world.
const Real3 &	get_spacing (const CartesianWorld &world) noexcept
double	get_spacing (const CartesianWorld &world, int index) noexcept
const Real3 &	get_origin (const CartesianWorld &world) noexcept
double	get_origin (const CartesianWorld &world, int index) noexcept
template<typename T >
auto	to_coords (const World< T > &world, const Int3 &indices) noexcept
template<typename T >
auto	to_indices (const World< T > &world, const Real3 &coords) noexcept
template<typename T >
double	physical_volume (const World< T > &world) noexcept
	Compute physical volume of domain.
template<typename T >
bool	is_1d (const World< T > &world) noexcept
	Check if domain is 1D (only x-direction has > 1 point)
template<typename T >
bool	is_2d (const World< T > &world) noexcept
	Check if domain is 2D (x and y have > 1 point, z has 1)
template<typename T >
bool	is_3d (const World< T > &world) noexcept
	Check if domain is 3D (all dimensions have > 1 point)
template<typename T >
int	dimensionality (const World< T > &world) noexcept
	Get dimensionality as integer.
template<typename T >
Real3	get_lower_bounds (const World< T > &world) noexcept
	Get physical lower bounds (origin corner)
template<typename T >
Real3	get_upper_bounds (const World< T > &world) noexcept
	Get physical upper bounds (far corner)
template<typename T >
std::array< std::vector< double >, 3 >	coordinates (const World< T > &world) noexcept

Detailed Description

Namespace for decomposition-related classes and functions.

Function Documentation

create() [1/3]

CartesianWorld pfc::world::create	(	const GridSize &	size,
		const PhysicalOrigin &	origin,
		const GridSpacing &	spacing
	)

Create a World object with strong types for type safety.

This is the preferred API for creating World objects. Strong types (GridSize, PhysicalOrigin, GridSpacing) make the API self-documenting and prevent parameter confusion at compile time.

Parameters

size	Grid dimensions (number of points per dimension)
origin	Physical origin of the coordinate system
spacing	Physical spacing between grid points

Returns

A World object with the specified geometry

Note

Zero overhead - strong types compile away completely

Type-safe - compiler catches parameter order mistakes

// Clear and type-safe
GridSize size({256, 256, 256});
PhysicalOrigin origin({-128.0, -128.0, -128.0});
GridSpacing spacing({1.0, 1.0, 1.0});
auto world = world::create(size, origin, spacing);
 
// Won't compile if parameters are swapped
// auto bad = world::create(spacing, size, origin);  // Compile error!

See also

GridSize, PhysicalOrigin, GridSpacing in strong_types.hpp

create(Int3, Real3, Real3) for legacy API (deprecated)

create() [2/3]

CartesianWorld pfc::world::create

(

const Int3 &

size

)

Create a World object with the specified size and default offset and spacing.

Parameters

dimensions

Dimensions of the world.

Returns

A World object.

create() [3/3]

CartesianWorld pfc::world::create	(	const Int3 &	size,
		const Real3 &	offset,
		const Real3 &	spacing
	)

Create a World object with raw arrays (DEPRECATED)

Deprecated:

Use create(GridSize, PhysicalOrigin, GridSpacing) for type safety. This overload is ambiguous - it's unclear which Real3 is offset vs spacing. The strong-type API prevents parameter confusion at compile time.

Parameters

size	Grid dimensions
offset	Physical offset (origin) of coordinate system
spacing	Physical spacing between grid points

Returns

A World object

Migration guide:

// Old (ambiguous):
auto world = world::create({256, 256, 256}, {0, 0, 0}, {1, 1, 1});
 
// New (type-safe):
auto world = world::create(
    GridSize({256, 256, 256}),
    PhysicalOrigin({0, 0, 0}),
    GridSpacing({1, 1, 1})
);

See also

create(GridSize, PhysicalOrigin, GridSpacing) for new API

dimensionality()

template<typename T >

int pfc::world::dimensionality ( const World< T > &  world )

inlinenoexcept

Get dimensionality as integer.

Returns 1, 2, or 3 based on how many dimensions have more than one grid point. Returns 0 for degenerate case where all dimensions have size 1.

Parameters

world

World instance

Returns

1, 2, 3, or 0 (degenerate) based on active dimensions

auto world2d = world::create({64, 64, 1});
int dim = world::dimensionality(world2d);  // Returns 2

Time complexity: O(1)

Examples

/home/runner/work/OpenPFC/OpenPFC/include/openpfc/core/world_queries.hpp.

Here is the call graph for this function:

from_bounds()

CartesianWorld pfc::world::from_bounds ( Int3  size, Real3  lower, Real3  upper, Bool3  periodic = {true, true, true}  )

inline

Create grid from physical bounds (automatically computes spacing).

Parameters

size	Grid dimensions
lower	Lower physical bounds
upper	Upper physical bounds
periodic	Periodicity flags (default: all periodic)

Returns

World with computed spacing

Exceptions

std::invalid_argument	if any dimension size <= 0
std::invalid_argument	if any upper bound <= corresponding lower bound

Note

Spacing computed as: dx = (upper - lower) / size for periodic, dx = (upper - lower) / (size - 1) for non-periodic

// 100 cells from 0 to 10 (periodic)
auto w1 = world::from_bounds({100, 100, 100}, {0, 0, 0}, {10, 10, 10});
 
// Non-periodic in x (different spacing formula)
auto w2 = world::from_bounds({100, 100, 100}, {0, 0, 0}, {10, 10, 10},
                              {false, true, true});

get_coordinate_system()

template<typename T >

const auto & pfc::world::get_coordinate_system ( const World< T > &  world )

inlinenoexcept

Get the coordinate system of the world.

Parameters

w	World object.

Returns

The coordinate system of the world.

Examples

/home/runner/work/OpenPFC/OpenPFC/include/openpfc/core/decomposition.hpp, and /home/runner/work/OpenPFC/OpenPFC/include/openpfc/core/world_queries.hpp.

Here is the caller graph for this function:

get_lower() [1/2]

const auto & pfc::world::get_lower ( const CartesianWorld &  world )

inlinenoexcept

Get the lower bounds of the world.

Parameters

w	World object.

Returns

The lower bounds of the world.

Examples

/home/runner/work/OpenPFC/OpenPFC/include/openpfc/core/decomposition.hpp, /home/runner/work/OpenPFC/OpenPFC/include/openpfc/core/halo_pattern.hpp, and /home/runner/work/OpenPFC/OpenPFC/include/openpfc/core/world_queries.hpp.

Here is the caller graph for this function:

get_lower() [2/2]

const auto & pfc::world::get_lower ( const CartesianWorld &  world, int  index  )

inline

Get the lower bounds of the world in a specific dimension.

Parameters

w	World object.
i	Dimension index.

Returns

The lower bound in the specified dimension.

Here is the call graph for this function:

get_lower_bounds()

template<typename T >

Real3 pfc::world::get_lower_bounds ( const World< T > &  world )

inlinenoexcept

Get physical lower bounds (origin corner)

Returns the physical coordinates of the grid point at index (0, 0, 0). This is the lower corner of the domain.

Parameters

world

World instance

Returns

Physical coordinates of (0, 0, 0) grid point

auto world = world::create({100, 100, 100}, {-5, -5, 0}, {0.1, 0.1, 0.1});
Real3 lower = world::get_lower_bounds(world);  // Returns {-5, -5, 0}

Time complexity: O(1)

Examples

/home/runner/work/OpenPFC/OpenPFC/include/openpfc/core/world_queries.hpp.

get_upper() [1/2]

const auto & pfc::world::get_upper ( const CartesianWorld &  world )

inlinenoexcept

Get the upper bounds of the world in a specific dimension.

Parameters

w	World object.

Returns

The upper bounds of the world.

Examples

/home/runner/work/OpenPFC/OpenPFC/include/openpfc/core/decomposition.hpp, /home/runner/work/OpenPFC/OpenPFC/include/openpfc/core/halo_pattern.hpp, and /home/runner/work/OpenPFC/OpenPFC/include/openpfc/core/world_queries.hpp.

Here is the caller graph for this function:

get_upper() [2/2]

auto pfc::world::get_upper ( const CartesianWorld &  world, int  index  )

inline

Get the upper bounds of the world in a specific dimension.

Parameters

w	World object.
i	Dimension index.

Returns

The upper bound in the specified dimension.

Here is the call graph for this function:

get_upper_bounds()

template<typename T >

Real3 pfc::world::get_upper_bounds ( const World< T > &  world )

inlinenoexcept

Get physical upper bounds (far corner)

Returns the physical coordinates of the grid point at the maximum indices (nx-1, ny-1, nz-1). This is the upper corner of the domain.

Parameters

world

World instance

Returns

Physical coordinates of (nx-1, ny-1, nz-1) grid point

auto world = world::create({100, 100, 100}, {0, 0, 0}, {0.1, 0.1, 0.1});
Real3 upper = world::get_upper_bounds(world);  // Returns {9.9, 9.9, 9.9}

Time complexity: O(1)

Examples

/home/runner/work/OpenPFC/OpenPFC/include/openpfc/core/world_queries.hpp.

is_1d()

template<typename T >

bool pfc::world::is_1d ( const World< T > &  world )

inlinenoexcept

Check if domain is 1D (only x-direction has > 1 point)

A domain is considered 1D if only the first dimension has more than one grid point.

Parameters

world

World instance

Returns

true if only x-direction is active (nx > 1, ny = 1, nz = 1)

auto world1d = world::create({100, 1, 1});
bool is_1d = world::is_1d(world1d);  // Returns true

Time complexity: O(1)

Examples

/home/runner/work/OpenPFC/OpenPFC/include/openpfc/core/world_queries.hpp.

Here is the caller graph for this function:

is_2d()

template<typename T >

bool pfc::world::is_2d ( const World< T > &  world )

inlinenoexcept

Check if domain is 2D (x and y have > 1 point, z has 1)

A domain is considered 2D if the first two dimensions have more than one grid point and the third has exactly one.

Parameters

world

World instance

Returns

true if x and y directions are active (nx > 1, ny > 1, nz = 1)

auto world2d = world::create({64, 64, 1});
bool is_2d = world::is_2d(world2d);  // Returns true

Time complexity: O(1)

Examples

/home/runner/work/OpenPFC/OpenPFC/include/openpfc/core/world_queries.hpp.

Here is the caller graph for this function:

is_3d()

template<typename T >

bool pfc::world::is_3d ( const World< T > &  world )

inlinenoexcept

Check if domain is 3D (all dimensions have > 1 point)

A domain is considered 3D if all three dimensions have more than one grid point.

Parameters

world

World instance

Returns

true if all three directions are active (nx > 1, ny > 1, nz > 1)

auto world3d = world::create({32, 32, 32});
bool is_3d = world::is_3d(world3d);  // Returns true

Time complexity: O(1)

Examples

/home/runner/work/OpenPFC/OpenPFC/include/openpfc/core/world_queries.hpp.

Here is the caller graph for this function:

physical_volume()

template<typename T >

double pfc::world::physical_volume ( const World< T > &  world )

inlinenoexcept

Compute physical volume of domain.

Returns the total physical volume (or area in 2D, length in 1D) of the simulation domain.

Parameters

world

World instance

Returns

Physical volume V = Lx * Ly * Lz where L = spacing * size

Note

For Cartesian coordinates, this is the product of all physical dimensions

Works correctly for 1D, 2D, and 3D domains

auto world = world::create({100, 100, 100}, {0, 0, 0}, {0.1, 0.1, 0.1});
double vol = world::physical_volume(world);  // Returns 1000.0

Time complexity: O(1) Space complexity: O(1)

Examples

/home/runner/work/OpenPFC/OpenPFC/include/openpfc/core/world_queries.hpp.

uniform() [1/2]

CartesianWorld pfc::world::uniform ( int  size )

inline

Create uniform grid with unit spacing at origin.

Most common case: N×N×N grid with spacing=1, origin=(0,0,0).

Parameters

size	Grid dimensions (same in all directions)

Returns

World with uniform grid

Exceptions

std::invalid_argument

if size <= 0

auto world = world::uniform(64);  // 64³ grid, dx=1

Here is the call graph for this function:

uniform() [2/2]

CartesianWorld pfc::world::uniform ( int  size, double  spacing  )

inline

Create uniform grid with specified spacing.

Parameters

size	Grid dimensions (same in all directions)
spacing	Grid spacing (same in all directions)

Returns

World with uniform grid and spacing

Exceptions

std::invalid_argument	if size <= 0
std::invalid_argument	if spacing <= 0

auto world = world::uniform(128, 0.5);  // 128³ grid, dx=0.5

Here is the call graph for this function:

with_origin()

CartesianWorld pfc::world::with_origin ( Int3  size, Real3  origin  )

inline

Create grid with custom origin but unit spacing.

Parameters

size	Grid dimensions
origin	Physical origin

Returns

World with specified size and origin, spacing=1

Exceptions

std::invalid_argument

if any size <= 0

auto world = world::with_origin({64, 64, 64}, {-5.0, -5.0, 0.0});

Here is the call graph for this function:

with_spacing()

CartesianWorld pfc::world::with_spacing ( Int3  size, Real3  spacing  )

inline

Create grid with default origin but custom spacing.

Parameters

size	Grid dimensions
spacing	Grid spacing

Returns

World with specified size and spacing, origin at (0,0,0)

Exceptions

std::invalid_argument	if any size <= 0
std::invalid_argument	if any spacing <= 0

auto world = world::with_spacing({64, 64, 128}, {0.1, 0.1, 0.05});

Here is the call graph for this function: