slim.simulation.farm module

Farms are the fundamental agents in SLIM. They cover a number of roles, including

• controlling individual cages

• managing its own finances

• choose whether to cooperate with other farms belonging to the same organisation

This module thus exports Farm but also its ray-friendly version FarmActor . The latter merely serves the purpose of keeping the object alive in an async loop running on a separate process in multithreaded simulations.

Note FarmActor’s documentation cannot generated on sphinx. See https://github.com/ray-project/ray/issues/2658

Please check out its documentation on the corresponding module code.

class slim.simulation.farm.Farm(id_: int, cfg: Config, initial_lice_pop: Optional[Dict[str, int]] = None)

Bases: slim.log.LoggableMixin

Define a salmon farm containing salmon cages. Over time the salmon in the cages grow and are subjected to external infestation pressure from sea lice. A Farm will also provide a constrained Gym space, available with get_gym_space(), with limited information (by design) for policy usage.

It’s usually preferrable to not instantiate this class directy but rather spawn its farm pool or the organisation as farms are required to communicate with each other.

A farm should be used in two ways:

New way

• apply_action() -> apply an action; this will enque the action to be performed during the next update cycle;

• update() -> update the internal state;

• disperse_offspring_v2() -> split the offspring into a list of cage-specific allocations.

Old way (deprecated, only used in single-threaded mode)

• apply_action()

• update()

• disperse_offspring() -> split the offspring into a farm-specific list of allocations

• update_arrivals() -> make the lice (offspring or newborn) enter the farm.

Note: only after dispersing it is safe to check to farm space.

Parameters

• id – the id of the farm.

• cfg – the farm configuration

• initial_lice_pop – if provided, overrides default generated lice population

add_treatment(treatment_type: Treatment, day: datetime.datetime, force=False) → bool

Ask to add a treatment. If a treatment was applied too early or if too many treatments have been applied so far the request is rejected.

Note that if at least one cage is eligible for treatment and the conditions above are still respected this method will still return True.

Eligibility depends on the following conditions:

• the cage should have started by the day treatment is applied

• the cage should not be fallowing

• the cage should not be treated by that day with that same type of treatment

• the lice count should be greater than 1.0 (to prevent spamming)

If force is True, the last three constraints will be ignored.

Parameters

• treatment_type – the treatment type to apply

• day – the day when to start applying the treatment

• force – if True, ignore some eligibility requirement.

Returns

whether the treatment has been added to at least one cage or not.

apply_action(cur_date: datetime.datetime, action: int)

Apply an action

Parameters

• cur_date – the date when the action was issued

• action – the action identifier as defined in slim.types.Treatments

disperse_offspring(eggs_by_hatch_date: Dict[datetime.datetime, GenoDistrib], cur_date: datetime.datetime) → List[Tuple[List[Dict[datetime.datetime, GenoDistrib]], datetime.datetime]]

DEPRECATED: it shouldn’t be within a farm’s responbility to calculate cage arrivals within other farms.

Allocate new offspring between the farms and cages.

Assumes the lice can float freely across a given farm so that they are not bound to a single cage while not attached to a fish.

Parameters

• eggs_by_hatch_date – Dictionary of genotype distributions based on hatch date

• cur_date – Current date of the simulation

disperse_offspring_v2(eggs_by_hatch_date: Dict[datetime.datetime, GenoDistrib], cur_date: datetime.datetime) → Tuple[List[Dict[datetime.datetime, GenoDistrib]], datetime.datetime]

Allocate new offspring within the farm

Assumes the lice can float freely across a given farm so that they are not bound to a single cage while not attached to a fish.

Parameters

• eggs_by_hatch_date – Dictionary of genotype distributions based on hatch date

• cur_date – Current date of the simulation

distribute_cage_offspring(cage_allocations: List[Dict[datetime.datetime, GenoDistrib]], arrival_time: datetime.datetime)

fallow()

Fallow the entire farm. This will in turn fallow all the cages in the farm.

generate_treatment_event(treatment_type: Treatment, cur_date: datetime.datetime) → TreatmentEvent

Generate a new treatment event with the correct efficacy based on the given day and type.

Parameters

• treatment_type – the type of treatment

• cur_date – the current date

Returns

the treatment event

get_cage_allocation(ncages: int, eggs_by_hatch_date: Dict[datetime.datetime, GenoDistrib]) → List[Dict[datetime.datetime, GenoDistrib]]

Return allocation of eggs for given number of cages.

Parameters

• ncages – Number of bins to allocate to

• eggs_by_hatch_date – Dictionary of genotype distributions based on hatch date

Returns

List of dictionaries of genotype distributions based on hatch date per bin

get_cage_arrivals_stats(cage_arrivals: List[Dict[datetime.datetime, GenoDistrib]]) → Tuple[int, List[int], List[GenoDistrib]]

Get stats about the cage arrivals for logging

Parameters

cage_arrivals – List of Dictionaries of genotype distributions based on hatch date.

Returns

Tuple representing total number of arrivals, arrival, distribution and genotype distribution by cage

get_cage_pressures(external_inflow: int) → List[int]

Get external pressure divided into cages

Parameters

external_inflow – the total external pressure

Returns

List of values of external pressure for each cage

get_farm_allocation(target_farm: int, eggs_by_hatch_date: Dict[datetime.datetime, GenoDistrib]) → Dict[datetime.datetime, GenoDistrib]

Return farm allocation of arrivals, that is a dictionary of genotype distributions based on hatch date updated to take into account probability of making it to the target farm.

The probability accounts for interfarm water movement (currents) as well as lice egg survival.

Note: for efficiency reasons this class modifies eggs_by_hatch_date in-place.

Parameters

• target_farm_id – Farm the eggs are travelling to

• eggs_by_hatch_date – Dictionary of genotype distributions based on hatch date

Returns

Updated dictionary of genotype distributions based on hatch date

get_gym_space() → ObservationSpace

Returns

a Gym space for the agent that controls this farm.

get_profit(cur_date: datetime.datetime) → float

Get the current mass of fish that can be resold.

Parameters

cur_date – the current day

Returns

the total profit that can be earned from this farm at the current time

property is_treating

Returns

a list of applied treatments as binary indices

property lice_genomics

Return the overall lice population indexed by geno distribution and stage.

property lice_population

Return the overall lice population in a farm

property num_fish

Return the number of fish across all cages

to_json_dict(**kwargs)

update(cur_date: datetime.datetime, ext_influx: int, ext_pressure_ratios: numpy.ndarray) → Tuple[Dict[datetime.datetime, GenoDistrib], float]

Update the status of the farm given the growth of fish and change in population of parasites. Also distribute the offspring across cages.

Parameters

• cur_date – Current date

• ext_influx – the amount of lice that enter a cage

• ext_pressure_ratios – the ratio to use for the external pressure

Returns

a pair of (dictionary of genotype distributions based on hatch date, cost of the update)

update_arrivals(arrivals: Tuple[List[Dict[datetime.datetime, GenoDistrib]], datetime.datetime])

DEPRECATED: only use in single-threaded scenarios.

Parameters

arrivals – the offspring coming to this lice