Definition of environmental objects. More...

Data Types
type	spatial
	Definition of a spatial object. Spatial object determines the position of the agent, food items and other things in the simulated space. Here we use continuous 3D environment (real type coordinates) More...

type	spatial_moving
	Definition of a movable spatial object. It extends the the_environment::spatial object, but also adds its previous position history in stack-like arrays. The history is maintained with the commondata::add_to_history() subroutine, adding a single element on the top (end) of the history stack. More...

type	environment
	Definition of the overall environment. Environment is a general container for all habitats, patches and other similar objects where the whole life of the agents takes place. Environment just provides the limits for all these objects. More...

type	food_item
	Definition of a single food item. Food item is a spatial object that has specific location in space. It can be "created" and eaten ("disappear"). Food item is an immobile SPATIAL object that has a position in 3D space. More...

type	food_resource
	Definition of the super-type FOOD resource type. This is a superclass, several sub-classes can be defined for different kinds of food and prey objects. More...

type	predator
	Definition of the `PREDATOR` objects. Predator is a moving agent that hunts on the evolving AHA agents but its internal structure is very simplistic (although we can in principle doit as a full AHA complexity with genome, GOS etc...). More...

type	habitat
	Definition of the environment habitat `HABITAT` object. There can potentially be of several types of habitats (patches etc.), so the superclass HABITAT defines the most general properties and procedures. More specific procedures are defined in sub-objects. Such procedures can be overriden from super-object to sub-objects providing for procedure polymorphism. More...

interface	light_surface
	Calculate surface light intensity (that is subject to diel variation) for specific time step of the model. Irradiance can be stochastic if an optionallogical `stochastic` flag is set to `TRUE`. More...

interface	light_depth
	Calculate underwater background irradiance at specific depth. More...

interface	visual_range
	Calculate visual range of predator using Dag Aksnes's procedures `srgetr()`, `easyr()` and `deriv()`. More...

interface	visual_range_new
	Calculate visual range of predator using Dag Aksnes's procedures `srgetr()`, `easyr()` and `deriv()`. More...

interface	dist
	Internal distance calculation backend engine. More...

interface	join
	An alias for the the_environment::food_resources_collapse_global_object() method for joining food resources into a single global food resource out of the global array the_environment::global_habitats_available. See the_environment::unjoin() for how to unjoin an array of food resources back into an array. More...

interface	unjoin
	An alias to the_environment::food_resources_update_back_global_object() method to transfer (having been modified) food resource objects out from the single united object back to the global array the_environment::global_habitats_available. See the_environment::join() for how to join an array of food resources into a single global object. More...

interface	assemble
	Interface to the procedure to assemble the global array of habitat objects the_environment::global_habitats_available from a list of separate habitat object components. This call. More...

interface	disassemble
	Interface to the procedure to disassemble the global habitats objects array the_environment::global_habitats_available back into separate habitat object components. See the_environment::global_habitats_disassemble() for the backend implementation. More...

interface	operator(.cat.)
	Interface operator to concatenate two arrays of the spatial the_environment::spatial or spatial moving the_environment::spatial_moving objects. More...

interface	operator(.catloc.)
	Interface operator to concatenate the location components of two arrays ofthe_environment::spatial class objects. More...

interface	operator(.within.)
	Interface operators `.within.` for testing whether a spatial object (first argument lies within an environment (second argument). Usage: More...

interface	operator(.contains.)
	Interface operators `.contains.` for testing whether an environment object (first argument) contains a `SPATIAL` object (second argument). Usage: More...

interface	operator(.above.)
	Interface operators .above. for spatial objects. Usage: More...

interface	operator(.below.)
	Interface operators .below. for spatial objects. Usage: More...

interface	operator(-)
	Interface operator "-" for the the_environment::environment spatial container objects. Return an environment object that is shrunk by a fixed value in the 2D XxY plane. See `the_environment::environment_shrink_xy_fixed()`. The operator can be used as follows: More...

Functions/Subroutines
elemental subroutine	spatial_create_empty (this)
	These are public access functions, but probably we don't need to allow public access to functions inside generic interfaces. More...

subroutine	environment_whole_build_vector (this, min_coord, max_coord)
	Create the highest level container environment. Set the size of the 3D environment container as two coordinate vectors setting the minimum and maximum coordinate limits: `min_coord(1)` for x, `min_coord(2)` for y, `min_coord(3)` for z The size of the environment should be set from parameter vectors in `COMMONDATA`. More...

subroutine	environment_whole_build_object (this, min_coord, max_coord)
	Create the highest level container environment. Set the size of the 3D environment container as two coordinate vectors setting the minimum and maximum coordinate limits. The parameters `min_coord` and `max_coord` are SPATIAL objects. More...

subroutine	environment_build_unlimited (this)
	Build an unlimited environment, with the spatial coordinates limited by the maximum machine supported values based on the intrinsic `huge` function. More...

type(environment) function	environment_shrink_xy_fixed (this, shrink_value)
	Return an environment object that is shrunk by a fixed value in the 2D XxY plane. More...

type(spatial) function	environment_get_minimum_obj (this)
	Function to get the minimum spatial limits (coordinates) of the environment. More...

type(spatial) function	environment_get_maximum_obj (this)
	Function to get the maximum spatial limits (coordinates) of the environment. More...

elemental real(srp) function	environment_get_minimum_depth (this)
	Get the minimum depth in this environment. More...

elemental real(srp) function	environment_get_maximum_depth (this)
	Get the maximum depth in this environment. More...

pure type(spatial) function, dimension(dim_environ_corners)	environment_get_corners_2dxy (this, ref_depth, offset)
	Get the corners of the environment in the 2D X Y plane. This is a very simplistic procedure that works only with the box environmental objects. More...

elemental logical function	environment_check_located_within_3d (this, check_object)
	Check if a spatial object is actually within this environment. More...

type(spatial) function	environment_random_uniform_spatial_3d (this)
	Generate a random spatial object with the uniform distribution within (i.e. bound to) this environment. More...

type(spatial) function	environment_random_uniform_spatial_2d (this, fixdepth)
	Generate a random spatial object with the uniform distribution within (i.e. bound to) this environment, the third depth coordinate is fixed. More...

type(spatial) function, dimension(num)	environment_random_uniform_spatial_vec_3d (this, num)
	Generate a vector of random spatial objects with the uniform distribution within (i.e. bound to) this environment. More...

type(spatial) function, dimension(size(fixdep_array))	environment_random_uniform_spatial_vec_2d (this, fixdep_array)
	Generate a vector of random spatial objects with the uniform distribution within (i.e. bound to) this environment. The third, depth coordinate is non-stochastic, and provided as an array parameter. More...

type(spatial) function, dimension(num)	environment_random_gaussian_spatial_3d (this, num, centroid, variance)
	Generates a vector of random spatial object with Gaussian coordinates within (i.e. bound to) this environment. More...

type(spatial) function, dimension(num)	environment_random_gaussian_spatial_2d (this, num, centroid, fixdepth, variance, variance_depth)
	Generates a vector of random spatial object with Gaussian coordinates within (i.e. bound to) this environment. The depth coordinate is set separately and can be non-random (fixed for the whole output array) or Gaussian with separate variance. More...

subroutine	environment_get_nearest_point_in_outside_obj (this, outside_object, offset_into, point_spatial, point_dist)
	Get the spatial point position within this environment that is nearest to an arbitrary spatial object located outside of the this environment. If the spatial object is actually located in this environment, return its own position. More...

subroutine	spatial_fix_position_3d_s (this, x, y, depth)
	Place spatial object into a 3D space, define the object's current coordinates. More...

elemental subroutine	spatial_fix_position_3d_o (this, location)
	Place spatial object into a 3D space, define the object's current coordinates. More...

elemental subroutine	spatial_make_missing (this)
	Assign all commondata::missing` coordinates to the_environment::spatial object. More...

elemental type(spatial) function	spatial_get_current_pos_3d_o (this)
	Get the current spatial position of a `SPATIAL` object. More...

pure real(srp) function, dimension(dimensionality_default)	spatial_get_current_pos_3d_v (this, vector)
	Get the current spatial position of a `SPATIAL` object. More...

elemental real(srp) function	spatial_get_current_pos_x_3d (this)
	Get the current `X` position of a `SPATIAL` object. More...

elemental real(srp) function	spatial_get_current_pos_y_3d (this)
	Get the current `Y` position of a `SPATIAL` object. More...

elemental real(srp) function	spatial_get_current_pos_d_3d (this)
	Get the current `DEPTH` position of a `SPATIAL` object. More...

real(srp) function	spatial_calc_irradiance_at_depth (this, time_step_model)
	Calculate the illumination (background irradiance) at the depth of the spatial object at an arbitrary time step of the model. More...

real(srp) function	spatial_visibility_visual_range_cm (this, object_area, contrast, time_step_model)
	Calculate the visibility range of a spatial object. Wrapper to the the_environment::visual_range() function. This function calculates the distance from which this object can be seen by a visual object (e.g. predator or prey). More...

pure integer function	spatial_get_environment_in_pos (this, environments_array)
	Identify in which environment from the input list this spatial agent is currently in. Example call: More...

subroutine	spatial_moving_fix_position_3d_v (this, x, y, depth)
	Place spatial movable object into a 3D space, define the object's current coordinates, but first save previous coordinates. More...

elemental subroutine	spatial_moving_fix_position_3d_o (this, location)
	Place spatial movable object into a 3D space, define the object's current coordinates, but first save previous coordinates. More...

elemental subroutine	spatial_moving_repeat_position_history_3d (this)
	Repeat (re-save) the current position into the positional history stack. More...

elemental real(srp) function	spatial_distance_3d (this, other)
	Calculate the Euclidean distance between two spatial objects. This is a type-bound function. More...

pure type(spatial) function, dimension(:), allocatable	spatial_stack2arrays (a, b)
	Concatenate two arrays of the_environment::spatial objects `a` and `b`. This procedure uses array slices which would be faster in most cases than the intrinsic `[a,b]` method. More...

pure type(spatial_moving) function, dimension(:), allocatable	spatial_moving_stack2arrays (a, b)
	Concatenate two arrays of the_environment::spatial_moving objects `a` and `b`. This procedure uses array slices which would be faster in most cases than the intrinsic `[a,b]` method. More...

pure type(spatial) function, dimension(:), allocatable	spatial_class_stack2arrays_locs (a, b)
	Concatenate the location components of two arrays of the_environment::spatial class objects a and b. This procedure uses array slices which would be faster in most cases than the intrinsic `[a,b]` method. More...

elemental real(srp) function	dist3d (this, other)
	This is a non-type-bound version of the distance calculation function. More...

elemental real(srp) function	spatial_self_distance_3d (this, from_history)
	Calculate the Euclidean distance between the current and previous position of a single spatial object. More...

elemental real(srp) function	spatial_moving_self_distance_3d (this, from_history)
	Calculate the Euclidean distance between the current and previous position of a single spatial movable object. Optionally, it also calculates the total distance traversed during the `from_history` points from the history stack along with the distance from the current position and the last historical value. For example, to calculate the average distance throughout the whole history (`HISTORY_SIZE_SPATIAL` points) do this: More...

elemental subroutine	spatial_moving_create_3d (this)
	Create a new spatial moving object. Initially it has no position, all coordinate values are `MISSING` or `INVALID` for real type coordinates. More...

elemental subroutine	spatial_moving_clean_hstory_3d (this)
	Create a new empty history of positions for spatial moving object. Assign all values to the MISSING value code. More...

elemental subroutine	spatial_moving_go_up (this, step)
	The spatial moving object ascends, goes up the depth with specific fixed step size. More...

elemental subroutine	spatial_moving_go_down (this, step)
	The spatial moving object decends, goes down the depth with specific fixed step size. More...

subroutine	spatial_moving_randomwalk_gaussian_step_3d (this, meanshift, cv_shift, environment_limits)
	Implements an optionally environment-restricted Gaussian random walk in 3D. More...

subroutine	spatial_moving_randomwalk_gaussian_step_25d (this, meanshift_xy, cv_shift_xy, meanshift_depth, cv_shift_depth, environment_limits)
	Implements an optionally environment-restricted Gaussian random walk in a "2.5 dimensions", i.e. 2D x y with separate walk parameters for the third depth dimension. More...

subroutine	spatial_moving_corwalk_gaussian_step_3d (this, target, meanshift, cv_shift, is_away, ci_lim, environment_limits, is_converged, debug_reps)
	Implements an optionally environment-restricted correlated directional Gaussian random walk in 3D towards (or away of) an the_environment::spatial class `target` object. More...

subroutine	spatial_moving_corwalk_gaussian_step_25d (this, target, meanshift_xy, cv_shift_xy, meanshift_depth, cv_shift_depth, is_away, ci_lim, environment_limits, is_converged, debug_reps)
	Implements an optionally environment-restricted correlated directional Gaussian random walk in 3D towards (or away of) an the_environment::spatial class `target` object. More...

subroutine	spatial_moving_dirwalk_gaussian_step_3d (this, target, meanshift, cv_shift, environment_limits)
	Implements an optionally environment-restricted directional Gaussian random walk in 3D towards a `target` the_environment::spatial class object. More...

subroutine	spatial_moving_dirwalk_gaussian_step_25d (this, target, meanshift_xy, cv_shift_xy, meanshift_depth, cv_shift_depth, environment_limits)
	Implements an optionally environment-restricted directional Gaussian random walk in "2.5"-D towards a `target` the_environment::spatial class object. i.e. 2D x y with separate walk parameters for the third depth dimension. More...

subroutine	rwalk3d_array (this, dist_array, cv_array, dist_all, cv_all, environment_limits, n_walks)
	Perform one or several steps of random walk by an array of the_environment::spatial_moving class objects. This is a 3D version with the same walk parameters for the horizontal XxY plane and depth. More...

subroutine	rwalk25d_array (this, dist_array_xy, cv_array_xy, dist_array_depth, cv_array_depth, dist_all_xy, cv_all_xy, dist_all_depth, cv_all_depth, environment_limits, n_walks)
	Perform one or several steps of random walk by an array of the_environment::spatial_moving class objects. This is a 2.5D version with separate walk parameters for the horizontal XxY plane and depth. More...

elemental logical function	spatial_check_located_within_3d (this, environment_limits)
	Function to check if this spatial object is located within an area set by an environmental object (parameter). This should be similar to an analogous function defined for the environment object. More...

elemental logical function	spatial_check_located_below (this, check_object)
	Logical function to check if the argument spatial object(s) (`check_object`) is (are) located below the this reference spatial object. Elemental function that also works with arrays. Use as: More...

elemental logical function	spatial_check_located_above (this, check_object)
	Logical function to check if the argument spatial object(s) (`check_object`) is (are) located above the this reference spatial object. Elemental function that also works with arrays. Use as: More...

type(spatial) function	spatial_get_nearest_object (this, neighbours, number)
	Determine the nearest spatial object to this spatial object among an array of other spatial objects. More...

integer function	spatial_get_nearest_id (this, neighbours, object)
	Determine the nearest spatial object to this spatial object among an array of other spatial objects. More...

subroutine	habitat_make_init (this, coord_min, coord_max, label, otherrisks, eggmortality, predators_number, loc_predators, food_abundance, loc_food, sizes_food)
	Make an instance of the habitat object (an environment superset). More...

character(len=label_length) function	habitat_name_get (this)
	Return the name of the habitat. More...

real(srp) function	habitat_get_risk_mortality (this)
	Get the mortality risk associated with this habitat. More...

real(srp) function	habitat_get_risk_mortality_egg (this)
	Get the egg mortality risk associated with this habitat. More...

subroutine	habitat_save_predators_csv (this, csv_file_name, is_success)
	Save the predators with their characteristics into a CSV file. More...

subroutine	save_dynamics (maxdepth, csv_file_name, is_success)
	Save diagnostics data that shows the dynamics of the light and the average depth of the food items, light at the average depth of the food items etc at each time step of the model. More...

type(spatial) function	environment_centre_coordinates_3d (this, nodepth)
	Determine the centroid of the environment. More...

real(srp) function, private	visual_range_scalar (irradiance, prey_area, prey_contrast)
	Wrapper for calculating visual range of a fish predator using the Dag Aksnes's procedures `srgetr()`, `easyr()` and `deriv()`. See `srgetr()` for computational details. More...

real(srp) function, dimension(size(prey_area)), private	visual_range_vector (irradiance, prey_area, prey_contrast_vect, prey_contrast)
	Wrapper for calculating visual range of a fish predator using the Dag Aksnes's procedures `srgetr()`, `easyr()` and `deriv()`. See `srgetr()` for computational details. More...

elemental real(srp) function	visual_range_fast (irradiance, prey_area, prey_contrast)
	Wrapper for calculating visual range of a fish predator using the Dag Aksnes's procedures `srgetr()`, `easyr()` and `deriv()`. This is a new elemental and parallel-ready visual range function wrapper making use the elemental-procedures based computational backend. See notes on `visual_range_scalar()` and `srgetr()` for computational details. More...

elemental real(srp) function, private	light_surface_deterministic (tstep)
	Calculate deterministic surface light at specific time step of the model. Light (`surlig`) is calculated from a sine function. Light intensity just beneath the surface is modelled by assuming a 50 % loss by scattering at the surface: More...

real(srp) function, private	light_surface_stochastic_scalar (tstep, is_stochastic)
	Calculate stochastic surface light at specific time step of the model. Light (`surlig`) is calculated from a sine function. Light intensity just beneath the surface is modelled by assuming a 50 % loss by scattering at the surface: More...

real(srp) function, dimension(size(tstep)), private	light_surface_stochastic_vector (tstep, is_stochastic)
	Calculate stochastic surface light at specific time step of the model. More...

real(srp) function, private	light_depth_integer (depth, surface_light, is_stochastic)
	Calculate underwater light at specific depth given specific surface light. More...

real(srp) function, private	light_depth_real (depth, surface_light, is_stochastic)
	Calculate underwater light at specific depth given specific surface light. More...

elemental real(srp) function	dist_scalar (x1, x2, y1, y2, z1, z2)
	Calculate distance between 3D or 2D points. This is a function engine for use within type bound procedures. Example (dist_scalar): More...

pure real(srp) function	dist_vector_nd (cvector1, cvector2)
	Calculate distance between N-dimensional points. This is a function engine for use within other type bound procedures. More...

pure real(srp) function	dist2_vector (cvector1, cvector2)
	Calculate the squared distance between two N-dimensional points. More...

pure real(srp) function	vect_magnitude (vector)
	Calculate the magnitude of an arbitrary N-dimensional vector. This is a raw vector backend. More...

elemental real(srp) function	dist2step (average_distance, dimensionality)
	Calculate the unit step along a single coordinate axis given the average distance between any two points in a N-dimensional Gaussian random walk. More...

elemental subroutine	food_item_create (this)
	Create a single food item at an undefined position with default size. More...

elemental subroutine	food_item_make (this, location, size, iid)
	Make a single food item, i.e. place it into a specific position in the model environment space and set the size. More...

logical function	food_item_capture_success_stochast (this, prob)
	Stochastic outcome of this food item capture by an agent. Returns TRUE if the food item is captured. More...

real(srp) function	food_item_capture_probability_calc (this, distance, time_step_model)
	Calculate the probability of capture of this food item by a predator agent depending on the distance between the agent and this food item. More...

real(srp) function	food_item_visibility_visual_range (this, object_area, contrast, time_step_model)
	Calculate the visibility range of this food item. Wrapper to the the_environment::visual_range() function. This function calculates the distance from which this food item can be seen by a predator (i.e. the default predator's visual range). More...

real(srp) function	minimum_depth_visibility (target_range, depth_range_min, depth_range_max, object_area, object_contrast, time_step_model)
	Find the depth at which the visibility of a spatial object becomes smaller than a specific distance value `target_range`. More...

elemental subroutine	food_item_disappear (this)
	Make the food item "disappear" and take the "eaten" state, i.e. impossible for consumption by the agents. More...

elemental logical function	food_item_is_eaten_unavailable (this)
	Logical check-indicator function for the food item being eaten and not available. More...

elemental logical function	food_item_is_available (this)
	Logical check-indicator function for the food item being available. More...

elemental real(srp) function	food_item_get_size (this)
	Get the size component of the food item object. More...

elemental real(srp) function	size2mass_food (radius)
	Calculate the mass of a food item, the non-OO backend. More...

elemental real(srp) function	mass2size_food (mass)
	Calculate the size (radius) of a food item, a reverse function of the_environment::size2mass_food(): More...

elemental real(srp) function	food_item_get_mass (this)
	Calculate and get the mass of the food item. More...

elemental subroutine	food_item_set_iid (this, iid)
	Set unique id for the food item object. More...

elemental subroutine	food_item_clone_assign (this, the_other)
	Clone the properties of this food item to another food item. More...

elemental integer function	food_item_get_iid (this)
	Get the unique id of the food item object. More...

pure subroutine	food_resource_make (this, label, abundance, locations, sizes)
	Make food resource object. This class standard constructor. More...

elemental integer function	food_resource_get_abundance (this)
	Get the number of food items in the food resource. More...

elemental character(len=label_length) function	food_resource_get_label (this)
	Get the label of the this food resource. More...

pure subroutine	food_resource_destroy_deallocate (this)
	Delete and deallocate food resource object. This class standard destructor. More...

pure type(spatial) function, dimension(size(this%food))	food_resource_locate_3d (this)
	Get the location object array (array of `SPATIAL` objects) of a food resource object. More...

real(srp) function	food_resource_calc_average_distance_items (this, n_sample)
	Calculate the average distance between food items within a resource. e.g. to compare it with the agent's random walk step size. More...

subroutine	food_resource_replenish_food_items_all (this, replace)
	Replenish and restore food resource. The food resource is replenished by substituting randomly selected `replace` food items or all items if `replace` is omitted or exceeds the actual number of food items. Unlike the the_environment::food_resource::make() method, the sizes and the positions of the food items within the resource are reused from the previous positions (previously explicitly set set by the the_environment::food_resource::make() method). More...

subroutine	food_resource_migrate_move_items (this, max_depth, time_step_model)
	This subroutine implements the migration of all the food items in the resource according to the plankton migration pattern from the G1 model (HED18). Briefly, the movement of each of the food items has two components: More...

subroutine	food_resource_rwalk_items_default (this)
	Perform a random walk step for all food items within the food resource. The walk is performed with the default parameters: More...

subroutine	migrate_food_vertical (habitats, time_step_model)
	Migrate food items in a whole array of food resources. The array is normally the the_environment::global_habitats_available. More...

subroutine	rwalk_food_step (habitats)
	Perform a random walk of food items in a whole array of food resources. The array is normally the the_environment::global_habitats_available. This procedure is a wrapper for the_environment::food_resource::rwalk() to do a walk on a whole array of habitats and linked food resources. More...

real(srp) function	center_depth_sinusoidal (tstep, depth)
	This function calculates the target depth for the sinusoidal vertical migration pattern of the food items at each time step of the model. See the_environment::food_resource_migrate_move_items() for the calling procedure. More...

subroutine	food_resource_save_foods_csv (this, csv_file_name, is_success)
	Save characteristics of food items in the resource into a CSV file. More...

elemental subroutine	food_resource_sort_by_size (this, reindex)
	Sort the food resource objects within the array by their sizes. The two subroutines below are a variant of the recursive quick-sort algorithm adapted for sorting real components of the the `FOOD_RESOURCE` object. More...

pure subroutine	food_resource_reset_iid_all (this, start_iid)
	Reset individual iid for the food resource. Individual iids must normally coincide with the array order index. If it is changed after sorting, iids no longer reflect the correct index. So this subroutine resets iids to be coinciding with each food item index. More...

subroutine	reindex_food_resources (resource_1, resource_2, resource_3, resource_4, resource_5, resource_6, resource_7, resource_8, resource_9, resource_10, resource_11, resource_12, resource_13, resource_14, resource_15, resource_16, resource_17, resource_18, resource_19, resource_20)
	Reset and reindex iids for an input list of several food resources. As the result of this subroutine all food items across all the resources within the whole list will have unique iids. More...

subroutine	food_resources_collapse (food_resource_collapsed, resource_1, resource_2, resource_3, resource_4, resource_5, resource_6, resource_7, resource_8, resource_9, resource_10, resource_11, resource_12, resource_13, resource_14, resource_15, resource_16, resource_17, resource_18, resource_19, resource_20, reindex, label)
	Collapse several food resources into one. The collapsed resource can then go into the perception system. The properties of the component resources are retained in the collapsed resource. More...

type(food_resource) function	food_resources_collapse_global_object (reindex, label)
	Join food resources into a single global food resource out of the global array the_environment::global_habitats_available. See the_environment::unjoin() for how to unjoin an array of food resources back into an array. The joined resource can then go into the perception system. The properties of the component resources are retained in the collapsed resource. More...

subroutine	food_resources_update_back (food_resource_collapsed, resource_1, resource_2, resource_3, resource_4, resource_5, resource_6, resource_7, resource_8, resource_9, resource_10, resource_11, resource_12, resource_13, resource_14, resource_15, resource_16, resource_17, resource_18, resource_19, resource_20, reindex)
	Transfer back the resulting food resources into their original objects out from a collapsed object from `food_resources_collapse`. More...

subroutine	food_resources_update_back_global_object (food_resource_collapsed, reindex)
	Transfer the (having been modified) food resource objects from the single united object `food_resource_collapsed` back to the global array the_environment::global_habitats_available array. See the_environment::join() for how to join an array of food resources into a single global object. More...

subroutine	global_habitats_assemble (habitat_1, habitat_2, habitat_3, habitat_4, habitat_5, habitat_6, habitat_7, habitat_8, habitat_9, habitat_10, habitat_11, habitat_12, habitat_13, habitat_14, habitat_15, habitat_16, habitat_17, habitat_18, habitat_19, habitat_20, reindex)
	Assemble the global habitats objects array the_environment::global_habitats_available from a list of separate habitat objects. This call. More...

subroutine	global_habitats_disassemble (habitat_1, habitat_2, habitat_3, habitat_4, habitat_5, habitat_6, habitat_7, habitat_8, habitat_9, habitat_10, habitat_11, habitat_12, habitat_13, habitat_14, habitat_15, habitat_16, habitat_17, habitat_18, habitat_19, habitat_20, reindex)
	Disassemble the global habitats objects array the_environment::global_habitats_available into separate habitat object. More...

subroutine	spatial_neighbours_distances (this, neighbours, dist, index_vector, ranks, rank_max, error_flag)
	Calculate the distances between this spatial object and an array of its neighbours. Optionally output the distances, sorting index vector and rankings vector for each of these neighbours. Optionally do only partial indexing, up to the order `rank_max` for computational speed. Procedure `ARRAY_INDEX()` from HEDTOOLS is used as the computational backend for partial segmented indexing. More...

elemental subroutine	predator_make_init (this, body_size, attack_rate, position, label)
	Initialise a predator object. More...

subroutine	predator_label_set (this, label)
	Set label for the predator, if not provided, set it random. More...

elemental real(srp) function	predator_get_body_size (this)
	Accessor function for the predator body size (length). More...

elemental real(srp) function	predator_get_attack_rate (this)
	Accessor function for the predator attack rate. More...

real(srp) function	predator_capture_risk_calculate_fish (this, prey_spatial, prey_length, prey_distance, is_freezing, time_step_model, debug_plot_file)
	Calculates the risk of capture of the fish with the spatial location defined by `prey_spatial` and the body length equal to `prey_length`. This is a backend function bound to the predator rather than prey object. More...

subroutine	predator_capture_risk_calculate_fish_group (this, prey_spatial, prey_length, is_freezing, time_step_model, risk, risk_indexed, index_dist)
	Calculates the risk of capture by a specific predator of an array of the fish agents with the spatial locations array defined by `prey_spatial` and the body length array `prey_length`. This subroutine takes account of both the predator dilution and confusion effects and risk adjusted by the distance towards the predator. More...

real(srp) function	predator_visibility_visual_range (this, object_area, contrast, time_step_model)
	Calculate the visibility range of this predator. Wrapper to the the_environment::visual_range() function. This function calculates the distance from which this predator can be seen by a visual object (e.g. the agent). More...

real(srp) function	distance_average (spatial_objects, sample_size)
	Calculates the average nearest neighbour distance amongst an array of spatial objects (class) by sampling `sample_size` of them. The sample size `sample_size` is optional, if not provided set to `SAMPLE_SIZE_DEFAULT=25`. More...

Visual range calculation backend.
The subroutines the_environment::srgetr(), the_environment::easyr() and the_environment::deriv() should be better isolated into a separate module or form a submodule, but it is not used here as submodules are a F2008 feature not supported by all compiler systems. Anyway, submodule is not essential here. Note Note that all these backend procedures are now pure and therefore parallel-safe.
elemental subroutine, private	srgetr (r, c, C0, Ap, Vc, Ke, Eb, IER)
	Obtain visual range by solving the non-linear equation by means of Newton-Raphson iteration and derivation in subroutine the_environment::deriv(). Initial value is calculated in the_environment::easyr(). The calculation is based on the model described in Aksnes & Utne (1997) Sarsia 83:137-147. More...

elemental subroutine, private	easyr (r, C0, Ap, Vc, Ke, Eb)
	Obtain a first estimate of visual range by using a simplified expression of visual range. See `srgetr()` for more details. More...

elemental subroutine, private	deriv (r, F1, FDER, c, C0, Ap, Vc, Ke, Eb)
	Derivation of equation for visual range of a predator. See the_environment::srgetr() for more details. More...

Computational geometry backend: <strong>polygon2D</strong>
Rudimentary computational geometry (geo_) procedures, based on 2D polygons (poly2d) with fixed depth or depth ignored. Note Manually constructed using 2D X x Y vectors ignoring the depth dimension.
subroutine	geo_poly2d_dist_point_to_section (point, sectp1, sectp2, min_dist, point_segment)
	Calculates the minimum distance from a the_environment::spatial class object to a line segment delimited by two the_environment::spatial class endpoints in the 2D XY plane (the depth coordinate is ignored). (The algorithm is partially based on this.) More...

subroutine	geo_poly3d_dist_point_to_section (point, sectp1, sectp2, min_dist, point_segment)
	Calculates the minimum distance from a the_environment::spatial class object to a line segment delimited by two the_environment::spatial class endpoints in the 3D XY space. (The algorithm is partially based on this.) More...

type(spatial) function	offset_dist (obj_a, obj_b, offset)
	Calculate a the_environment::spatial target with an offset. More...

Variables
character(len= *), parameter, private	modname = "(THE_ENVIRONMENT)"

integer, parameter, private	dimensionality_default = 3
	Default dimensionality of the environment universe. More...

integer, parameter	dim_environ_corners = 4
	The number of corners for an environment object in the 2D XxY plane. More...

type(habitat), dimension(:), allocatable, public	global_habitats_available
	A list (array) of all the the_environment::habitat objects available to the agents. This single array should encompass all the locations that the agent can potentially be in (e.g. migrate from one to another). More...

Detailed Description

Definition of environmental objects.

THE_ENVIRONMENT module

This module defines various environment objects and primitives, starting from the basic primitive a spatial object the_environment::spatial. This object represents a point in a three-dimensional space. The agent class hierarchy starts from this spatial primitive as the agent is a spatial object.

Function/Subroutine Documentation

◆ spatial_create_empty()

elemental subroutine the_environment::spatial_create_empty ( class(spatial), intent(inout) this )

These are public access functions, but probably we don't need to allow public access to functions inside generic interfaces.

We do not need specific functions outside of this module, always use generic functions. Create an empty spatial object. The object's starting coordinates get all MISSING values.

Definition at line 939 of file m_env.f90.

◆ environment_whole_build_vector()

subroutine the_environment::environment_whole_build_vector	(	class(environment), intent(inout)	this,
		real(srp), dimension(3), intent(in)	min_coord,
		real(srp), dimension(3), intent(in)	max_coord
	)

Create the highest level container environment. Set the size of the 3D environment container as two coordinate vectors setting the minimum and maximum coordinate limits: min_coord(1) for x, min_coord(2) for y, min_coord(3) for z The size of the environment should be set from parameter vectors in COMMONDATA.

Parameters

min_coord	Minimum coordinate bound for the environment.
max_coord	Maximum coordinate bound for the environment.

Note: This version accepts simple arrays as the environment coordinates.

Warning: Not-extensible version. TODO: Do we need it? Deprecate? There is a generic function build that should normally be used.

Definition at line 958 of file m_env.f90.

◆ environment_whole_build_object()

subroutine the_environment::environment_whole_build_object	(	class(environment), intent(inout)	this,
		type(spatial), intent(in)	min_coord,
		type(spatial), intent(in)	max_coord
	)

Create the highest level container environment. Set the size of the 3D environment container as two coordinate vectors setting the minimum and maximum coordinate limits. The parameters min_coord and max_coord are SPATIAL objects.

Parameters

min_coord	Minimum coordinate bound for the environment, `SPATIAL` object.
max_coord	Maximum coordinate bound for the environment, `SPATIAL` object.

Note: This version accepts SPATIAL objects as the environment coordinates.

Definition at line 988 of file m_env.f90.

◆ environment_build_unlimited()

subroutine the_environment::environment_build_unlimited ( class(environment), intent(inout) this )

Build an unlimited environment, with the spatial coordinates limited by the maximum machine supported values based on the intrinsic huge function.

Definition at line 1005 of file m_env.f90.

◆ environment_shrink_xy_fixed()

type(environment) function the_environment::environment_shrink_xy_fixed	(	class(environment), intent(in)	this,
		real(srp), intent(in)	shrink_value
	)

Return an environment object that is shrunk by a fixed value in the 2D XxY plane.

Here is an illustration of the function. The outer box is the input environment, the inner box is the shrunken environment that is returned. The shrinkage value is fixed, defined by the second function parameter. The depth is ignored in this function working with the simplistic box-like environment objects.

 min_coord is obtained   +---------------------+
 by coordinate addition; | +                   |
                         |   +-------------+   |
                         |   |             |   |
                         |-->|             |<--|
                         |   |             |   |
                         |   |             |   |
                         |   +-------------+   |
                         |                   - |  max_coord is obtained by
                         +---------------------+  coordinate subtraction.

There is a user defined operator - (minus), that can be used as follows:

temp_hab = habitat_safe - 0.5_srp

Warning: Valid only for the simplistic box-like environments; should be reimplemented if the environment is implemented as an arbitrary polyhedron.

Definition at line 1047 of file m_env.f90.

◆ environment_get_minimum_obj()

type(spatial) function the_environment::environment_get_minimum_obj ( class(environment), intent(in) this )

Function to get the minimum spatial limits (coordinates) of the environment.

Returns: The minimum spatial bound of the environment, as a SPATIAL object.

Definition at line 1066 of file m_env.f90.

◆ environment_get_maximum_obj()

type(spatial) function the_environment::environment_get_maximum_obj ( class(environment), intent(in) this )

Function to get the maximum spatial limits (coordinates) of the environment.

Returns: The maximum spatial bound of the environment, as a SPATIAL object.

Definition at line 1082 of file m_env.f90.

◆ environment_get_minimum_depth()

elemental real(srp) function the_environment::environment_get_minimum_depth ( class(environment), intent(in) this )

Get the minimum depth in this environment.

Returns: The maximum depth of this environment

Definition at line 1095 of file m_env.f90.

◆ environment_get_maximum_depth()

elemental real(srp) function the_environment::environment_get_maximum_depth ( class(environment), intent(in) this )

Get the maximum depth in this environment.

Returns: The maximum depth of this environment

Definition at line 1106 of file m_env.f90.

◆ environment_get_corners_2dxy()

pure type(spatial) function, dimension(dim_environ_corners) the_environment::environment_get_corners_2dxy	(	class(environment), intent(in)	this,
		real(srp), intent(in), optional	ref_depth,
		real(srp), intent(in), optional	offset
	)

Get the corners of the environment in the 2D X Y plane. This is a very simplistic procedure that works only with the box environmental objects.

Warning: Should be reimplemented if the environment is implemented as an arbitrary polyhedron.

Parameters

[in]	ref_depth	ref_depth optional parameter setting the fixed depth for the returned corner objects. If not provided, a fixed default value equal to the local parameter `REF_DEPTH_DEF=0.0` is used.
[in]	offset	offset The offset that can be set to make the borders and corners of the environment inside at a fixed value. If offset is absent, the actual corners of the environment are returned. The offset parameter works as the `shrink2d` function (the_environment::environment::shrink2d()`. .---------------------. \| + \| \| ------------- \| \| \| \| \| \| \| \|<--\| offset shrinks corners \| \| \| \| \| \| \| \| \| ------------- \| \| - \| .---------------------.

Returns: Returns an array of the environment corners in the 2D X x Y plane. The number of corners for the environment object in the 2D X x Y plane is defined by the parameter constant the_environment::dim_environ_corners.

Implementation details

The corners 1,2,3,4 of the simplistic box-like environmental object are defined as follows:

   (1:minX,minY) ----- (2:maxX,minY)
    |                         |
   (4:minX,maxY) ----- (3:maxX,maxY)

These four points are returned as the the_environment::spatial class objects.

Warning: The order of the points is important because it is also used in the nearest_target procedure the_environment::environment_get_nearest_point_in_outside_obj().

Definition at line 1120 of file m_env.f90.

◆ environment_check_located_within_3d()

elemental logical function the_environment::environment_check_located_within_3d	(	class(environment), intent(in)	this,
		class(spatial), intent(in)	check_object
	)

Check if a spatial object is actually within this environment.

Returns: TRUE if the spatial object is located within the environment.

Parameters

check_object

A spatial object (SPATIAL or any extension) to check. There is a user-defined operator:

if ( environment .contains. object ) then

Definition at line 1207 of file m_env.f90.

◆ environment_random_uniform_spatial_3d()

type(spatial) function the_environment::environment_random_uniform_spatial_3d ( class(environment), intent(in) this )

Generate a random spatial object with the uniform distribution within (i.e. bound to) this environment.

Returns: uniformly distributed random SPATIAL object bound to this environment.

Definition at line 1239 of file m_env.f90.

◆ environment_random_uniform_spatial_2d()

type(spatial) function the_environment::environment_random_uniform_spatial_2d	(	class(environment), intent(in)	this,
		real(srp), intent(in)	fixdepth
	)

Generate a random spatial object with the uniform distribution within (i.e. bound to) this environment, the third depth coordinate is fixed.

Returns: uniformly distributed random SPATIAL object bound to this environment.

Definition at line 1261 of file m_env.f90.

◆ environment_random_uniform_spatial_vec_3d()

type(spatial) function, dimension(num) the_environment::environment_random_uniform_spatial_vec_3d	(	class(environment), intent(in)	this,
		integer, intent(in)	num
	)

Generate a vector of random spatial objects with the uniform distribution within (i.e. bound to) this environment.

Parameters

the	dimension(size) of the vector to generate

Returns: uniformly distributed random SPATIAL object bound to this environment.

Warning: Intel Fortran porting note. This whole array function does not work under Intel Fortran 13, issues stack overflow runtime error, although compiles without issues: loc_food_here = thisuniform(thisfoodnumber_food_items).

Definition at line 1290 of file m_env.f90.

◆ environment_random_uniform_spatial_vec_2d()

type(spatial) function, dimension(size(fixdep_array)) the_environment::environment_random_uniform_spatial_vec_2d	(	class(environment), intent(in)	this,
		real(srp), dimension(:), intent(in)	fixdep_array
	)

Generate a vector of random spatial objects with the uniform distribution within (i.e. bound to) this environment. The third, depth coordinate is non-stochastic, and provided as an array parameter.

Parameters

the	dimension(size) of the vector to generate

Returns: uniformly distributed random SPATIAL object bound to this environment.

Implementation details

We call the type bound uniform_s=>environment_random_uniform_spatial_3d to get a vector of uniformly-distributed spatial objects.

Definition at line 1331 of file m_env.f90.

◆ environment_random_gaussian_spatial_3d()

type(spatial) function, dimension(num) the_environment::environment_random_gaussian_spatial_3d	(	class(environment), intent(in)	this,
		integer, intent(in)	num,
		class(spatial), intent(in), optional	centroid,
		real(srp), intent(in), optional	variance
	)

Generates a vector of random spatial object with Gaussian coordinates within (i.e. bound to) this environment.

Parameters

num	the dimension(size) of the vector to generate
centroid	Optional centroid of the Gaussian scatter. If not provided, will select random uniformly distributed point.
variance	Gaussian variance parameter.

Returns: Gaussian ranrom SPATIAL object bound to this environment.

Implementation details

First, check optional centroid and set local centroid.

The centroid that is provided is accepted only if it is within this environment.

If a centroid is provided but is outside of the environment, reset it to random uniform.

Now, generate Gaussian spatial objects and fill the output array.

First, generate random Gaussian coordinanes for a temporary spatial object.

Make sure this spatial object is within the bounding environment.

Finally, set assign the output array component to this object.

Definition at line 1370 of file m_env.f90.

◆ environment_random_gaussian_spatial_2d()

type(spatial) function, dimension(num) the_environment::environment_random_gaussian_spatial_2d	(	class(environment), intent(in)	this,
		integer, intent(in)	num,
		class(spatial), intent(in), optional	centroid,
		real(srp), intent(in), optional	fixdepth,
		real(srp), intent(in), optional	variance,
		real(srp), intent(in), optional	variance_depth
	)

Generates a vector of random spatial object with Gaussian coordinates within (i.e. bound to) this environment. The depth coordinate is set separately and can be non-random (fixed for the whole output array) or Gaussian with separate variance.

Parameters

num	the dimension(size) of the vector to generate
centroid	Optional centroid of the Gaussian scatter. If not provided, will select random uniformly distributed point.
fixdepth	Optional fixed depth for the generated Gaussian objects.
variance	Gaussian variance parameter.
variance_depth	Gaussian variance parameter for the fixed depth.

Returns: Gaussian random SPATIAL object bound to this environment.

Implementation details

First, check optional centroid parameter and set local centroid.

Make sure fixdepth is within the allowed environmental range.

If fixed depth is provided, we use the centroid but take the depth from the fixdepth parameter.

And check if the resulting centroid is within this environment. If not, make it random uniform making use of the fixed depth.

If the fixdepth is not conformant with this environment, use centroid provided and discard the fixdepth parameter

And check if the resulting centroid is within this environment, if not, discard both the centroid and the fixed depth parameters and use random uniform centroid as the last resort.

If fixed depth is not provided, however, we use the fixed depth from the centroid

The centroid that is provided is accepted only if it is within this environment.

If a centroid is provided but is outside of the environment, reset it to random uniform.

Check if it's conformant with the environment. Use if if okay.

If the depth provided is not conformant, discard and use random.

Finally, if neither centroid nor depth is provided, use random uniform.

Check if separate variance parameter for the depth is provided. This sets if stochastic depth is to be generated.

If separate depth variance parameter is provided, depth is stochastic Gaussian. Generate Gaussian spatial objects and fill the output array.

First, generate random Gaussian coordinanes for a temporary spatial object.

Finally, set assign the output array component to this object.

If there is no separate variance parameter for the depth, depth fixed deterministic, identical in for the whole array. Set the fixed depth.

Now, generate Gaussian spatial objects and fill the output array.

First, generate random Gaussian coordinanes for a temporary spatial object.

Finally, set assign the output array component to this object.

Definition at line 1450 of file m_env.f90.

Here is the call graph for this function:

◆ environment_get_nearest_point_in_outside_obj()

subroutine the_environment::environment_get_nearest_point_in_outside_obj	(	class(environment), intent(in)	this,
		class(spatial), intent(in)	outside_object,
		real(srp), intent(in), optional	offset_into,
		type(spatial), intent(out), optional	point_spatial,
		real(srp), intent(out), optional	point_dist
	)

Get the spatial point position within this environment that is nearest to an arbitrary spatial object located outside of the this environment. If the spatial object is actually located in this environment, return its own position.

Note: This function is necessary for the implementation of migration behaviour across two or several environments or habitats: it allows to set the (nearest) target point in the desired target environment.

Warning: Valid only for the simplistic box-like environments; should be reimplemented if the environment is implemented as an arbitrary polyhedron.

Parameters

[in]	outside_object	outside_object is the outside object, the minimum distances to the environment and the closest point are evaluated for this object.
[in]	offset_into	offset_into optional offset guaranteeing that the nearest point is located more or less deeply within the this target environment rather than just at the border of the environment. This parameter is useful if the nearest point in the environment actually sets the target point, to which the agent represented by the `outside_object` spatial is relocating. In such a case, the agent is therefore moving into the environment, at a distance `offset_into` rather than just to the edge of this target environment. This is illustrated by the below: .----------------------. this environment \| + \| \| -------------- \| \| \| target point \| \| outside_object \| \| is inside ()<------------<=>< \| \| \| \| \| \| >\|---\|<-------- offset_into \| -------------- \| \| - \| .------------------ ---.
[out]	point_spatial

Returns: The point within the this environment that is the nearest to the outside_object the_environment::spatial class target object.

Implementation notes

First, check if the outside object is actually located within the target environment.

If so, the distance between the object and the environment is zero. This is a degenerate case that is treated separately: the nearest point within the environment coincides with the location of the outside object itself.

If the object is indeed outside, determine the four corners of the this environment. These corners are delimiting the outside of the this environment. The reference depth is set to the depth of the outside object.

@nolte Note that if the offset_into offset parameter is set, the corners are adjusted to this offset value, so that they are actually inside the this environment object.

Calculate the distances and the nearest points between the outside object and the four outer segments (1,2), (2,3), (3,4), (4,1).

Warning

This fast but unsafe implementation requires the same order of points to be set also in the the_environment::environment_get_corners_2dxy(). For arbitrary order of points, a full cross loop is needed, with the sizes of the segment_nearest_obj segment_distance arrays set to the square DIM_ENVIRON_CORNERS * DIM_ENVIRON_CORNERS.

   1, 2               1------------2
   2, 3               |            |
   3, 4               |            |
   4, 1               4------------3

Finally, the returned nearest point is the point where the distance between the outside point and any of the outer segments of the environment reaches the minimum value.

Definition at line 1632 of file m_env.f90.

◆ spatial_fix_position_3d_s()

subroutine the_environment::spatial_fix_position_3d_s	(	class(spatial), intent(inout)	this,
		real(srp), intent(in)	x,
		real(srp), intent(in)	y,
		real(srp), intent(in)	depth
	)

Place spatial object into a 3D space, define the object's current coordinates.

Parameters

coordinates The spatial objects will now get these coordinates.

Note: This is actually the constructor for the SPATIAL object giving it its value and existence.; This version takes scalar coordinates as the argument.

Warning: This implementation is not extensible.

Definition at line 1756 of file m_env.f90.

◆ spatial_fix_position_3d_o()

elemental subroutine the_environment::spatial_fix_position_3d_o	(	class(spatial), intent(inout)	this,
		type(spatial), intent(in)	location
	)

Place spatial object into a 3D space, define the object's current coordinates.

Parameters

location SPATIAL location that will be assigned to the current spatial object.

Note: This is actually the constructor for the SPATIAL object giving it its value and existence.; This version takes a SPATIAL object as argument.

Definition at line 1776 of file m_env.f90.

◆ spatial_make_missing()

elemental subroutine the_environment::spatial_make_missing ( class(spatial), intent(inout) this )

Assign all commondata::missing` coordinates to the_environment::spatial object.

Definition at line 1792 of file m_env.f90.

◆ spatial_get_current_pos_3d_o()

elemental type(spatial) function the_environment::spatial_get_current_pos_3d_o ( class(spatial), intent(in) this )

Get the current spatial position of a SPATIAL object.

Returns: Current spatial coordinates as a SPATIAL object.

Note: This function returns SPATIAL type object (3D coordinates).; This is a standard extensible version.

Definition at line 1806 of file m_env.f90.

◆ spatial_get_current_pos_3d_v()

pure real(srp) function, dimension(dimensionality_default) the_environment::spatial_get_current_pos_3d_v	(	class(spatial), intent(in)	this,
		logical, intent(in)	vector
	)

Get the current spatial position of a SPATIAL object.

Parameters

vector flag indicating if we return a 3D vector rather than SPATIAL type object. Note: We need this logical parameter to avoid ambiguity in calling the generic function: ‘Error: 'spatial_get_current_pos_3d’ and 'spatial_get_current_pos_3d_v' for GENERIC 'now' at (1) are ambiguous`. The parameter itself is not used. So, for vector-output must always be TRUE.

Returns: Current spatial coordinates as a 3-dimensional array.

Note: This function returns array of 3D coordinates.

Warning: This function is non extensible.

Note: The vector form of the location function is particularly convenient for data output into the LOGGER module that does not accept object data, but does accept simple array data, e.g.:
call LOG_DBG ("location=" // &

tostr(proto_parents%individual(ind)%location(.true.)))

Definition at line 1836 of file m_env.f90.

◆ spatial_get_current_pos_x_3d()

elemental real(srp) function the_environment::spatial_get_current_pos_x_3d ( class(spatial), intent(in) this )

Get the current X position of a SPATIAL object.

Returns: x_pos current X coordinate of the SPATIAL object.

Note: Not sure if really much needed.

Definition at line 1859 of file m_env.f90.

◆ spatial_get_current_pos_y_3d()

elemental real(srp) function the_environment::spatial_get_current_pos_y_3d ( class(spatial), intent(in) this )

Get the current Y position of a SPATIAL object.

Returns: x_pos current X coordinate of the SPATIAL object.

Note: Not sure if really much needed.

Definition at line 1872 of file m_env.f90.

◆ spatial_get_current_pos_d_3d()

elemental real(srp) function the_environment::spatial_get_current_pos_d_3d ( class(spatial), intent(in) this )

Get the current DEPTH position of a SPATIAL object.

Returns: x_pos current X coordinate of the SPATIAL object.

Note: Not sure if really much needed.

Definition at line 1885 of file m_env.f90.

◆ spatial_calc_irradiance_at_depth()

real(srp) function the_environment::spatial_calc_irradiance_at_depth	(	class(spatial), intent(in)	this,
		integer, intent(in), optional	time_step_model
	)

Calculate the illumination (background irradiance) at the depth of the spatial object at an arbitrary time step of the model.

Warning: Cannot implement a generic function accepting also vectors of this objects as only elemental object-bound array functions are allowed by the standard. This function cannot be elemental, so passed-object dummy argument must always be scalar.

Implementation details

Check optional time step parameter. If unset, use global commondata::global_time_step_model_current.

Calculate ambient illumination / irradiance at the depth of this food item at the given time step.

Definition at line 1901 of file m_env.f90.

◆ spatial_visibility_visual_range_cm()

real(srp) function the_environment::spatial_visibility_visual_range_cm	(	class(spatial), intent(in)	this,
		real(srp), intent(in), optional	object_area,
		real(srp), intent(in), optional	contrast,
		integer, intent(in), optional	time_step_model
	)

Calculate the visibility range of a spatial object. Wrapper to the the_environment::visual_range() function. This function calculates the distance from which this object can be seen by a visual object (e.g. predator or prey).

Warning: Cannot implement a generic function accepting also vectors of this objects as only elemental object-bound array functions are allowed by the standard. This function cannot be elemental, so passed-object dummy argument must always be scalar.

Parameters

[in] object_area object_area is the mandatory area of the spatial object (m).

Note: object_area has optional attribute here with the base the_environemnt::spatial class object can be only optional because it is optional in all extension classes (the_environment::food_item, the_environment::predator, the_body::condition,the_neurobio::spatialobj_percept_comp). However, it is actually mandatory here and not providing object size results in wrong calculations. Such a case is logged with the commondata::ltag_error logger tag.

Parameters

[in]	contrast	contrast is optional inherent contrast of this spatial object. the default contrast of all objects is defined by the commondata::preycontrast_default parameter.
[in]	time_step_model	optional time step of the model, if absent gets the current time step as defined by the value of `commondata::global_time_step_model_current`.

Returns: The maximum distance (m) from which this object can be seen.

PROCNAME is the procedure name for logging and debugging

Implementation details

Check if optional object area parameter is present. For a base the_environment::spatial object, providing explicit value is mandatory. If object area is absent, commondata::missing value is used as a default, which results in wrong calculations.

Such a case is logged with the commondata::ltag_error logger tag. (check logger errors with grep ERROR: *log).

Check optional contrast parameter. If unset, use global commondata::preycontrast_default.

Check optional time step parameter. If unset, use global commondata::global_time_step_model_current.

Calculate ambient illumination / irradiance at the depth of this object at the given time step.

Return visual range to see this spatial object: its visibility range.

Definition at line 1938 of file m_env.f90.

◆ spatial_get_environment_in_pos()

pure integer function the_environment::spatial_get_environment_in_pos	(	class(spatial), intent(in)	this,
		class(environment), dimension(:), intent(in), optional	environments_array
	)

Identify in which environment from the input list this spatial agent is currently in. Example call:

ienv = object%find_environment( [habitat_safe, habitat_dangerous] )

Note: Because the habitat object is an extension of the environment, this method also works with the habitats.

Determining the environment object the agent is currently in can be done by the_environment::spatial::find_environment() method in this way:

   ...
   environment_limits = Global_Habitats_Available(                        &
                  this_agent%find_environment(Global_Habitats_Available) )
   ...

This uses the the_environment::global_habitats_available global array containing all available environments, initialised in the_evolution::init_environment_objects().

Parameters

[in] environments_array environments_array An array of environment objects, where the this object can be. If this parameter is omitted, the environment objects are obtained from the default global array the_environment::global_habitats_available.

Warning: The environment objects within the array must be non-overlapping, otherwise, the results are undefined due to parallel algorithm.

Returns: Returns the number of the environment from the input array, where this spatial object is currently in.

Implementation details

First, determine the size of the input array of the environments among which the check is done.

Also, initialise the return value to zero.

Then cycle over all the input environments whether the this spatial object is within it.

The .within. operator is used for checking (defined by the_environment::environment_check_located_within_3d()). Then, return the number of the environment within the input array and exit.

If the environments_array array is not provided, default habitats are obtained from the the_environment::global_habitats_available global array .

Definition at line 2039 of file m_env.f90.

◆ spatial_moving_fix_position_3d_v()

subroutine the_environment::spatial_moving_fix_position_3d_v	(	class(spatial_moving), intent(inout)	this,
		real(srp), intent(in)	x,
		real(srp), intent(in)	y,
		real(srp), intent(in)	depth
	)

Place spatial movable object into a 3D space, define the object's current coordinates, but first save previous coordinates.

Parameters

x	The spatial objects will now get these coordinates.
y	The spatial objects will now get these coordinates.
depth	The spatial objects will now get these coordinates.

Implementation details

Save previous coordinates into the history stacks.

Finally, position the object now with the coordinates provided.

Definition at line 2121 of file m_env.f90.

◆ spatial_moving_fix_position_3d_o()

elemental subroutine the_environment::spatial_moving_fix_position_3d_o	(	class(spatial_moving), intent(inout)	this,
		type(spatial), intent(in)	location
	)

Place spatial movable object into a 3D space, define the object's current coordinates, but first save previous coordinates.

Parameters

location The spatial objects will now get these coordinates.

Implementation details

Save previous coordinates into the history stacks.

Finally, position the object now with the coordinates provided.

Definition at line 2144 of file m_env.f90.

◆ spatial_moving_repeat_position_history_3d()

elemental subroutine the_environment::spatial_moving_repeat_position_history_3d ( class(spatial_moving), intent(inout) this )

Repeat (re-save) the current position into the positional history stack.

Note: Re-saving the current position is necessary to keep the full positional history even for the the_behavior::behaviour's that do not involve spatial displacement (movement).

Definition at line 2168 of file m_env.f90.

◆ spatial_distance_3d()

elemental real(srp) function the_environment::spatial_distance_3d	(	class(spatial), intent(in)	this,
		class(spatial), intent(in)	other
	)

Calculate the Euclidean distance between two spatial objects. This is a type-bound function.

Returns: distance Euclidean distance between two spatial objects.

Parameters

other another spatial object that we measure distance between.

Note: Note that this version uses the vector-based backend for calculation. The vector-based backend is equivalent to the scalar-based, but might be more general as it easily works with other dimensionality (e.g. 2D or 4D). The negative side is that the vector-based backend cannot be used to make an elemental function. Example: x_dist = objectdistance(other_object)

Implementation details

Calculate the distance between these two spatial objects.

Note: Note that this version uses the vector-based backend for calculation. The vector-based backend is equivalent to the scalar-based, but might be more general as it easily works with other dimensionality (e.g. 2D or 4D). The negative side is that the vector-based backend cannot be used to make an elemental function.

Definition at line 2190 of file m_env.f90.

◆ spatial_stack2arrays()

pure type(spatial) function, dimension(:), allocatable the_environment::spatial_stack2arrays	(	type(spatial), dimension(:), intent(in)	a,
		type(spatial), dimension(:), intent(in)	b
	)

Concatenate two arrays of the_environment::spatial objects a and b. This procedure uses array slices which would be faster in most cases than the intrinsic [a,b] method.

Note: There is a user defined operator .cat. making use of this procedure that can be used like this:
object1%location() .cat. object2%location()

Warning: This is the the_environment::spatial type version. All input and output parameters are defined as type, so this is not class-safe.

Parameters

[in]	a	a first array
[in]	b	b second array

Returns: an array [a, b]

Definition at line 2223 of file m_env.f90.

◆ spatial_moving_stack2arrays()

pure type(spatial_moving) function, dimension(:), allocatable the_environment::spatial_moving_stack2arrays	(	type(spatial_moving), dimension(:), intent(in)	a,
		type(spatial_moving), dimension(:), intent(in)	b
	)

Concatenate two arrays of the_environment::spatial_moving objects a and b. This procedure uses array slices which would be faster in most cases than the intrinsic [a,b] method.

Note: There is a user defined operator .cat. making use of this procedure that can be used like this:
object1%location() .cat. object2%location()

Warning: This is the the_environment::spatial_moving type version. All input and output parameters are defined as type, so this is not class-safe.

Parameters

[in]	a	a first array
[in]	b	b second array

Returns: an array [a, b]

Definition at line 2250 of file m_env.f90.

◆ spatial_class_stack2arrays_locs()

pure type(spatial) function, dimension(:), allocatable the_environment::spatial_class_stack2arrays_locs	(	class(spatial), dimension(:), intent(in)	a,
		class(spatial), dimension(:), intent(in)	b
	)

Concatenate the location components of two arrays of the_environment::spatial class objects a and b. This procedure uses array slices which would be faster in most cases than the intrinsic [a,b] method.

Note: There is a user defined operator .cat. making use of this procedure that can be used like this:
all_objects%position%( object1 .catloc. object2 )

Warning: Unlike the the_environment::spatial_stack2arrays() and the_environment::spatial_moving_stack2arrays() methods, this procedure is class-safe and can be used with any class upwards, but it concatenates only the location data (returns type the_environment::spatial).

Parameters

[in]	a	a first array
[in]	b	b second array

Returns: an array [a, b]

Definition at line 2280 of file m_env.f90.

◆ dist3d()

elemental real(srp) function the_environment::dist3d	(	class(spatial), intent(in)	this,
		class(spatial), intent(in)	other
	)

This is a non-type-bound version of the distance calculation function.

Note: Note that this is an elemental function that can also accept arrays (but these must be conforming). Example:
x_dist = dist3d(object, other_object) # scalar variant

d=dist3d( habitat_safe%food%food(1:3), &

habitat_safe%food%food(4:6) ) # vector variant

Returns: distance Euclidean distance between two spatial objects.

Parameters

[in] other other another spatial object that we measure distance between.

Implementation details

Calculate the distance between these two spatial objects.

Note: Note that this version uses the scalar-based backend for calculation. The scalar-based backend is equivalent to the vector-based one, but is linked with the 3D space only (has to be re-implemented in case of 2D or 4D space). But its positive side is that it is an elemental function that can be used to make further elemental functions.

Definition at line 2306 of file m_env.f90.

◆ spatial_self_distance_3d()

elemental real(srp) function the_environment::spatial_self_distance_3d	(	class(spatial), intent(in)	this,
		integer, intent(in), optional	from_history
	)

Calculate the Euclidean distance between the current and previous position of a single spatial object.

Parameters

from_history We have to calculate total distance from this point in the spatial stack history (< HISTORY_SIZE_SPATIAL). Not used here, always 0.0.

Returns: distance Euclidean distance between two spatial objects.

Implementation details

The distance between two positions of an immobile object is zero in all cases. It is a fixed value in this procedure.

Definition at line 2334 of file m_env.f90.

◆ spatial_moving_self_distance_3d()

elemental real(srp) function the_environment::spatial_moving_self_distance_3d	(	class(spatial_moving), intent(in)	this,
		integer, intent(in), optional	from_history
	)

Calculate the Euclidean distance between the current and previous position of a single spatial movable object. Optionally, it also calculates the total distance traversed during the from_history points from the history stack along with the distance from the current position and the last historical value. For example, to calculate the average distance throughout the whole history (HISTORY_SIZE_SPATIAL points) do this:

object_name%way(history_size_spatial - 1) / history_size_spatial

This is because for N points in history we can calculate N-1 distances, but the sample size is N, that is N-1 plus an additional distance between the latest historical point and the current position.

Parameters

from_history We have to calculate total distance from this point in the spatial stack history (< HISTORY_SIZE_SPATIAL)

Returns: distance Euclidean distance between two spatial objects.

Implementation details

We get the history size from the history stack size (history), alternatively, can get from the HISTORY_SIZE_SPATIAL parameter directly.

Check if we are asked to calculate distance traversed using the history stack. If the number provided exceed the limit, set maximum. If no history requested (parameter not present or 0) calculate the distance between the current point and the latest historical point.

Note: If we have history stack of size N, we can calculate maximum N-1 historical distances between N successive points.

Calculate the distance between the current position and the last historical stack record.

Now cycle backwards through the from_history steps of the history stack and calculate the sum = total distance traversed.

Definition at line 2367 of file m_env.f90.

◆ spatial_moving_create_3d()

elemental subroutine the_environment::spatial_moving_create_3d ( class(spatial_moving), intent(inout) this )

Create a new spatial moving object. Initially it has no position, all coordinate values are MISSING or INVALID for real type coordinates.

Note: This is the constructor for SPATIAL_MOVING object type that makes it into existence and gives it its value.

Implementation details

Assign MISSING values to the new object, use interface function and type constructor.

This also cleanups the history stack, i.e. fills it with MISSING values.

Definition at line 2435 of file m_env.f90.

◆ spatial_moving_clean_hstory_3d()

elemental subroutine the_environment::spatial_moving_clean_hstory_3d ( class(spatial_moving), intent(inout) this )

Create a new empty history of positions for spatial moving object. Assign all values to the MISSING value code.

Implementation details

Set all historical stack arrays to MISSING.

Definition at line 2453 of file m_env.f90.

◆ spatial_moving_go_up()

elemental subroutine the_environment::spatial_moving_go_up	(	class(spatial_moving), intent(inout)	this,
		real(srp), intent(in), optional	step
	)

The spatial moving object ascends, goes up the depth with specific fixed step size.

Parameters

[in] step step is the step size for the upwards walk. If it is too large (the object would extend beyond its current environment), it is adjusted autiomatically.

Implementation details

Calculate the minimum depth in the environment currently occupied by the spatial object.

Use a combination of the_environment::spatial::find_environment() and the_environment::environment::depth_min().

Check if the target depth is likely to go beyond the environment depth limits and reduce the upwnward walk step size accordingly. Namely, if the depth coordinate of the object minus the depth step exceeds the minimum depth, the step is reduced to be within the available environment: $d_{o} - D_{min} - \varepsilon$ , where $D_{min}$ is the maximum depth, $d_{o}$ is the current depth of the object and $\varepsilon$ is a very small constant defined by the parameter commondata::zero to guarantee the object remains within the current environment.

Relocate the object so that its X and Y coordinates remain intact but the depth reduces by the step size.

Here, if the object is a the_environment::food_item class object, also check if it is the_environment::food_item::is_available() and move the object only if yes.

Definition at line 2467 of file m_env.f90.

◆ spatial_moving_go_down()

elemental subroutine the_environment::spatial_moving_go_down	(	class(spatial_moving), intent(inout)	this,
		real(srp), intent(in), optional	step
	)

The spatial moving object decends, goes down the depth with specific fixed step size.

Parameters

[in] step step is the step size for the upwards walk. If it is too large (the object would extend beyond its current environment), it is adjusted autiomatically.

Implementation details

Calculate the maximum depth in the environment currently occupied by the spatial object.

Use a combination of the_environment::spatial::find_environment() and the_environment::environment::depth_max().

Check if the target depth is likely to go beyond the environment depth limits and reduce the downward walk step size accordingly. Namely, if the depth coordinate of the object plus the depth step exceeds the maximum depth, the step is reduced to be within the available environment: $D_{max} - d_{o} - \varepsilon$ , where $D_{max}$ is the maximum depth, $d_{o}$ is the current depth of the object and $\varepsilon$ is a very small constant defined by the parameter commondata::zero to guarantee the object remains within the current environment.

Relocate the object so that its X and Y coordinates remain intact but the depth reduces by the step size.

Here, if the object is a the_environment::food_item class object, also check if it is the_environment::food_item::is_available() and move the object only if yes.

Definition at line 2530 of file m_env.f90.

◆ spatial_moving_randomwalk_gaussian_step_3d()

subroutine the_environment::spatial_moving_randomwalk_gaussian_step_3d	(	class(spatial_moving), intent(inout)	this,
		real(srp), intent(in)	meanshift,
		real(srp), intent(in)	cv_shift,
		class(environment), intent(in), optional	environment_limits
	)

Implements an optionally environment-restricted Gaussian random walk in 3D.

Parameters

meanshift	the mean shift along any of the three dimensions.
cv_shift	the coefficient of variation for a single elementary shift in any of the three dimensions.
environment_limits	Limits of the environment area available for the random walk. The moving object cannot get beyond this limit.

The moving object walks in three dimensions. The process is simple, first shift along the x axis for some random Gaussian length (with the mean meanshift and the variance/CV cv_shift) then walk another Gaussian length the y axis. The, walk in the same manner along the z axis. The optional restriction is that the whole walk must not exceed specific spatial location set by the environment parameter.

Implementation details

First, we get the current coordinates of the spatial object.

And set a temporary spatial test object with the new coordinates, advancing/adding our random walk step. This is done via the .radd. operator and calling RNORM (see HEDTOOLS).

Environment restriction part of the random walk, if environment_limits parameter object is provided. Here the object is not allowed to go beyond its bounding environment: get new position while outside of the target environment.

Loop while this new test spatial object is outside of our target environment. It must be strictly within.

Finally, change the current position of the this object to the position defined by the test_object. The standard function position for the SPATIAL_MOVINGis used, that keeps the movement history.

Definition at line 2604 of file m_env.f90.

Here is the call graph for this function:

◆ spatial_moving_randomwalk_gaussian_step_25d()

subroutine the_environment::spatial_moving_randomwalk_gaussian_step_25d	(	class(spatial_moving), intent(inout)	this,
		real(srp), intent(in)	meanshift_xy,
		real(srp), intent(in)	cv_shift_xy,
		real(srp), intent(in)	meanshift_depth,
		real(srp), intent(in)	cv_shift_depth,
		class(environment), intent(in), optional	environment_limits
	)

Implements an optionally environment-restricted Gaussian random walk in a "2.5 dimensions", i.e. 2D x y with separate walk parameters for the third depth dimension.

Parameters

meanshift	the mean shift along any of the three dimensions.
cv_shift	the coefficient of variation for a single elementary shift in any of the three dimensions.
environment_limits	Limits of the environment area available for the random walk. The moving object cannot get beyond this limit.

The moving object walks in three dimensions. The process is simple, first shift along the x axis for some random Gaussian length (with the mean meanshift and the variance/CV cv_shift) then walk another Gaussian length the y axis. The, walk in the same manner along the z axis. But here z axis has separate walk parameters (meanshift and cv_shift) that are much smaller than the x and y parameters. The optional restriction is that the whole walk must not exceed specific spatial location set by the environment parameter.

Note: The mean and CV is different for the 2D x y movement and the third dimension depth movement.

Implementation details

First, we get the current coordinates of the spatial object.

And set a temporary spatial test object with the new coordinates, advancing/adding our random walk step. This is done via the .radd. operator and calling the RNORM function (see HEDTOOLS).

Environment restriction part of the random walk, if environment_limits parameter object is provided. Here the object is not allowed to go beyond its bounding environment: get new position while outside of the target environment.

Loop while this new test spatial object is outside of our target environment. It must be strictly within.

Finally, change the current position of the this object to the position defined by the test_object. The standard function position for the SPATIAL_MOVINGis used, that keeps the movement history.

Definition at line 2686 of file m_env.f90.

Here is the call graph for this function:

◆ spatial_moving_corwalk_gaussian_step_3d()

subroutine the_environment::spatial_moving_corwalk_gaussian_step_3d	(	class(spatial_moving), intent(inout)	this,
		class(spatial), intent(in)	target,
		real(srp), intent(in)	meanshift,
		real(srp), intent(in)	cv_shift,
		logical, intent(in), optional	is_away,
		real(srp), intent(in), optional	ci_lim,
		class(environment), intent(in), optional	environment_limits,
		logical, intent(out), optional	is_converged,
		integer, intent(out), optional	debug_reps
	)

Implements an optionally environment-restricted correlated directional Gaussian random walk in 3D towards (or away of) an the_environment::spatial class target object.

The moving object walks in three dimensions towards (or away of) a the_environment::spatial class target. Here is an example of walks:

Correlated Gaussian random walk in 3D

Parameters

[in]	target	target The target of the random walk.
[in]	meanshift	meanshift the mean shift along any of the three dimensions.
[in]	cv_shift	cv_shift the coefficient of variation for a single elementary shift in any of the three dimensions.
[in]	is_away	is_away optional logical flag, if set to TRUE, the walk is actually directed out of the target, so that the object is going to maximise rather than minimise the distance to the target.
[in]	ci_lim	ci_lim This parameter sets the convergence criterion; it is the confidence interval limit for the distance between the object and the target. The walk is considered "converged" if the distance between the object and the target is smaller than `ci_lim` std. deviations of the average step distance (set by `meanshift`). The default value is the 95% confidence interval (1.95996).
[in]	environment_limits	environment_limits optional limits of the environment area available for the random walk. The moving object cannot get beyond this limit.
[out]	is_converged	is_converged optional logical flag for the "converged" state, i.e. the distance between the object and the target is smaller than `ci_lim` standard deviations of the average step distance.
[out]	debug_reps	debug_reps optional internal counter for repeated samplings of random positions for prospective spatial advancement of the object. If the counter reaches a too high value, a "no convergence" state is reached. In case of the avoiding environmentally limited walk, when the object maximises its distance from the target, such a condition may indicate that there is no further space to avoid the target in the available environment.

Implementation details

First, check if the convergence criterion is reached. The walk is considered "converged" if the distance between the object and the target is smaller than ci_lim std. deviations of the average step distance (which is set by meanshift).

If the convergence condition is met, the object does not change its position any more, no further walks are performed.

If the convergence condition is not yet met, the current coordinates of the spatial object are recorded.

Then a temporary spatial test object (test_object) is set the new coordinates for the spatial moving object, advancing to a random walk step. This is done by randomly adding or subtracting a Gaussian step size with the mean meanshift and variance defined by cv_shift along all three spatial coordinates.

A series of conditions is then checked, the main is that the new position defined by the temporary spatial object should be such that the distance from the target must be smaller (if the object is intended to moved towards the target) or larger (if the object is intended to move away of the target).

Environment restriction is also applied if environment_limits parameter is provided: the object is not allowed to go beyond its bounding environment in such a case.

There is also a safeguard against poor convergence: If the number of iterations exceeds a fixed value (CONVERG local parameter), force to exit from the condition loops without changing the object position (i.e. no walk is done).

Finally, change the current position of the this object to the position defined by the test_object. Such a change is done only if the non-convergence condition is not detected.

At the end, check and return the optional intent[out] parameters is_converged and debug_reps.

Definition at line 2765 of file m_env.f90.

Here is the call graph for this function:

◆ spatial_moving_corwalk_gaussian_step_25d()

subroutine the_environment::spatial_moving_corwalk_gaussian_step_25d	(	class(spatial_moving), intent(inout)	this,
		class(spatial), intent(in)	target,
		real(srp), intent(in)	meanshift_xy,
		real(srp), intent(in)	cv_shift_xy,
		real(srp), intent(in)	meanshift_depth,
		real(srp), intent(in)	cv_shift_depth,
		logical, intent(in), optional	is_away,
		real(srp), intent(in), optional	ci_lim,
		class(environment), intent(in), optional	environment_limits,
		logical, intent(out), optional	is_converged,
		integer, intent(out), optional	debug_reps
	)

Implements an optionally environment-restricted correlated directional Gaussian random walk in 3D towards (or away of) an the_environment::spatial class target object.

The moving object walks in three dimensions towards (or away of) a the_environment::spatial class target.

Correlated Gaussian random walk in 3D

Parameters

[in]	target	target The target of the random walk.
[in]	meanshift_xy	meanshift_xy the mean shift along any of the three dimensions.
[in]	cv_shift_xy	cv_shift_xy the coefficient of variation for a single elementary shift in any of the three dimensions.
[in]	meanshift_depth	meanshift_depth the mean shift along any of the three dimensions.
[in]	cv_shift_depth	cv_shift_depth the coefficient of variation for a single elementary shift in any of the three dimensions.
[in]	is_away	is_away optional logical flag, if set to TRUE, the walk is actually directed out of the target, so that the object is going to maximise rather than minimise the distance to the target.
[in]	ci_lim	ci_lim This parameter sets the convergence criterion; it is the confidence interval limit for the distance between the object and the target. The walk is considered "converged" if the distance between the object and the target is smaller than `ci_lim` std. deviations of the average step distance (set by `meanshift`). The default value is the 95% confidence interval (1.95996).
[in]	environment_limits	environment_limits optional limits of the environment area available for the random walk. The moving object cannot get beyond this limit.
[out]	is_converged	is_converged optional logical flag for the "converged" state, i.e. the distance between the object and the target is smaller than `ci_lim` standard deviations of the average step distance.
[out]	debug_reps	debug_reps optional internal counter for repeated samplings of random positions for prospective spatial advancement of the object. If the counter reaches a too high value, a "no convergence" state is reached. In case of the avoiding environmentally limited walk, when the object maximises its distance from the target, such a condition may indicate that there is no further space to avoid the target in the available environment.