#include <WakeRegistry.h>

Inheritance diagram for marenv::wake::WakeRegistry:

Collaboration diagram for marenv::wake::WakeRegistry:

Public Member Functions
void	Add (const std::string &id, std::shared_ptr< WakeField > field)

void	AddJet (const std::string &id, std::shared_ptr< JetField > field)

std::shared_ptr< JetField >	GetJet (const std::string &id) const

void	Remove (const std::string &id)

bool	Has (const std::string &id) const
	Whether a wake field is registered under id.

std::shared_ptr< WakeField >	Get (const std::string &id) const

std::vector< std::string >	Ids () const
	The identifiers in registration order.

std::vector< std::string >	JetIds () const
	The identifiers of the jet fields (AddJet()), in registration order.

WakeSelection	Select (const WakeQueryRegion &region, const WakeQuery &query={}, const WaterVelocityParts &parts={}) const

WakeComposition	Compose (double time, const double pos[3], const WakeQuery &query={}, const WaterVelocityParts &parts={}) const

void	ComposeMany (double time, std::span< const std::array< double, 3 > > positions, const WakeQuery &query, std::span< WakeComposition > out, const WaterVelocityParts &parts={}) const

std::uint64_t	Revision () const

bool	StaticFrom (double t) const

Detailed Description

The wake fields registered in an environment, in registration order, and the rule that composes them.

Registration order is the composition order, so the result is the same on every platform (MENV-0035). Registration (Add, Remove) happens during setup only and is not synchronised; Compose(), ComposeMany() and Select() are const and thread-safe against concurrent updates of the fields themselves (see WakeField::Sample).

Composition. Every field is sampled at the point. A field that returns a status other than Status::OK (Status::ERROR_NOT_SET outside the field) contributes nothing; a returned deficit is clamped to [0, 1], and a zero or NaN deficit contributes nothing (MENV-0020). The registered fields compose by the momentum-flux rule, d_tot (1 - d_tot) = sum d_i (1 - d_i) where that has a root below the branch deficit, else the capped linear sum or 1/2 (owner ruling R95; MomentumFluxSum), with the source velocity u_s the deficit-weighted mean of the u_s,i. A WakeQuery::own field, a net's private per-panel field whose sources are normalised by their local, already shaded inflow (doc/wake.md section 4), is multiplied onto that composition: d_tot = 1 - (1 - D) (1 - d_own) (R88, R95). The deficit acts on the velocity relative to the source, u = u_amb + d_tot (u_s - u_amb) (ADR 0001), whether or not a current is present. The registered jet fields (AddJet()) are summed in registration order and added after the deficits, u = u_amb + d_tot (u_s - u_amb) + sum Δu_j (ADR 0003); they share the identifiers' namespace with the wake fields.

Change signal. Revision() changes whenever a field or jet is registered, removed or published again, and StaticFrom(t) tells whether the composition stays the same from t on until then, so a caller that shows the composition (a visualiser) samples it again only on a change.

Member Function Documentation

◆ Add()

void marenv::wake::WakeRegistry::Add	(	const std::string &	id,
		std::shared_ptr< WakeField >	field
	)

Registers a wake field.

Parameters

[in]	id	Unique identifier.
[in]	field	The field; kept alive by the registry.

Exceptions

std::invalid_argument if id is already registered, as a wake or a jet field.

◆ AddJet()

void marenv::wake::WakeRegistry::AddJet	(	const std::string &	id,
		std::shared_ptr< JetField >	field
	)

Registers a jet field (ADR 0003); jets compose in registration order.

Parameters

[in]	id	Unique identifier, among the wake and the jet fields.
[in]	field	The jet field; kept alive by the registry.

Exceptions

std::invalid_argument if id is already registered, as a wake or a jet field.

◆ Compose()

WakeComposition marenv::wake::WakeRegistry::Compose	(	double	time,
		const double	pos[3],
		const WakeQuery &	query = `{}`,
		const WaterVelocityParts &	parts = `{}`
	)		const

Composes the wake fields and the jets of the query at one point.

Parameters

[in]	time	Simulation time, s.
[in]	pos	Position (x,y,z), m, NED.
[in]	query	Which registered field and jet to skip and which unregistered field to add; the default composes all registered fields and jets.
[in]	parts	The terms to compose: the wake fields (own included) with parts.wakes, else none and deficit 0; the jets with parts.jets, else none. The default composes both.

Returns: The combined deficit, source velocity and number of contributing fields, and the summed jets; deficit 0 when none contributes.

◆ ComposeMany()

void marenv::wake::WakeRegistry::ComposeMany	(	double	time,
		std::span< const std::array< double, 3 > >	positions,
		const WakeQuery &	query,
		std::span< WakeComposition >	out,
		const WaterVelocityParts &	parts = `{}`
	)		const

Composes the wake fields and the jets of the query at many points at one time: Compose() at each, bit for bit.

Parameters

[in]	time	Simulation time, s.
[in]	positions	The points, m, NED.
[in]	query	As Compose().
[out]	out	One composition per point; as many as positions.
[in]	parts	As Compose().

Each field is sampled for all the points at once (WakeField::SampleMany(), one load of its state), and a field or jet that cannot reach the sphere around the points (MayReach() at the exact tier) is not sampled at all. A caller that samples a grid in rows from several threads (a visualiser) composes a row per call. Thread-safe as Compose().

◆ Get()

std::shared_ptr< WakeField > marenv::wake::WakeRegistry::Get ( const std::string & id ) const

Returns the field registered under id.

Exceptions

std::invalid_argument if id is not registered.

◆ GetJet()

std::shared_ptr< JetField > marenv::wake::WakeRegistry::GetJet ( const std::string & id ) const

Returns the jet field registered under id.

Exceptions

std::invalid_argument if no jet field is registered under id.

◆ Remove()

void marenv::wake::WakeRegistry::Remove ( const std::string & id )

Removes a wake field.

Exceptions

std::invalid_argument if id is not registered.

◆ Revision()

std::uint64_t marenv::wake::WakeRegistry::Revision ( ) const

Returns a number that grows whenever a field or jet is registered, removed or published again.

The registrations count in the upper 32 bits and the fields' and jets' WakeField::Revision() below them, so the number grows as long as the registered fields have been published fewer than 2^32 times in all. Fields that cannot tell (Revision() 0) are covered by StaticFrom(). Thread-safe against concurrent publishes, as Compose().

◆ Select()

WakeSelection marenv::wake::WakeRegistry::Select	(	const WakeQueryRegion &	region,
		const WakeQuery &	query = `{}`,
		const WaterVelocityParts &	parts = `{}`
	)		const

Selects the registered wake fields and jets that may reach a region, for a query (owner decision R47).

Parameters

[in]	region	The sphere and time interval of the caller's queries, and the cutoff tier.
[in]	query	The registered field and jet to leave out, and the own field and its tags; the caller keeps query.own and query.ownExcludedTags alive while the selection is used.
[in]	parts	The terms to compose: the wake fields (own included) with parts.wakes, the jets with parts.jets; current and waves are not read.

Returns: The fields other than query.exclude (none without parts.wakes) and the jets other than query.excludeJet (none without parts.jets) for which MayReach(region) is true, in registry order.

A structure selects once per step, after the fields have been published for the step, with a sphere that holds all its query points over the step (EnclosingRegion()). With region.cutoff = 0 (the exact tier) a composition at a point of the sphere and a time of the interval is bit for bit Compose(). With region.cutoff > 0 (the cutoff tier) each left-out field has d < cutoff there, so d_tot changes by less than the cutoff times the number of fields left out, over 1 - 2 min(d_tot, kMomentumFluxBranchDeficit) (the largest slope of the momentum-flux rule there, R95; at most 10 times the cutoff per field); each left-out jet adds less than the cutoff times its velocity scale.

◆ StaticFrom()

bool marenv::wake::WakeRegistry::StaticFrom ( double t ) const

Whether Compose() is the same at every point from t on until Revision() changes.

True when every registered field and jet is static from t (WakeField::StaticFrom(), JetField::StaticFrom()); true with none registered. Thread-safe against concurrent publishes, as Compose().

The documentation for this class was generated from the following file:

webfhsim/reloadrepos/marenv/include/marenv/wake/WakeRegistry.h

Public Member Functions

Detailed Description

Member Function Documentation

◆ Add()

◆ AddJet()

◆ Compose()

◆ ComposeMany()

◆ Get()

◆ GetJet()

◆ Remove()

◆ Revision()

◆ Select()

◆ StaticFrom()