add a standard biomass hold and a proportional discarding strategy

agents/src/main/java/uk/ac/ox/poseidon/agents/vessels/hold/Hold.java

@@ -40,6 +40,8 @@ public interface Hold<C extends Content<C>> {
      */
     Bucket<C> getContent();
 
+    boolean isFull();
+
     /**
      * Removes all content currently held in the container and returns it.
      *

agents/src/main/java/uk/ac/ox/poseidon/agents/vessels/hold/InfiniteHold.java

@@ -44,6 +44,17 @@ public Bucket<C> getContent() {
         return content;
     }
 
+    /**
+     * An infinite hold is never full (though there might be technical limits depending on content
+     * type, e.g. Double.MAX_VALUE).
+     *
+     * @return false
+     */
+    @Override
+    public boolean isFull() {
+        return false;
+    }
+
     @Override
     public Bucket<C> removeContent() {
         final Bucket<C> result = content;

agents/src/main/java/uk/ac/ox/poseidon/agents/vessels/hold/OvercapacityDiscardingStrategy.java

@@ -0,0 +1,39 @@
+/*
+ * POSEIDON: an agent-based model of fisheries
+ * Copyright (c) 2025 CoHESyS Lab [email protected]
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ *
+ */
+
+package uk.ac.ox.poseidon.agents.vessels.hold;
+
+import lombok.Data;
+import uk.ac.ox.poseidon.biology.Bucket;
+import uk.ac.ox.poseidon.biology.Content;
+
+public interface OvercapacityDiscardingStrategy<C extends Content<C>> {
+    Result<C> discard(
+        Bucket<C> contentToAdd,
+        Bucket<C> currentHoldContent,
+        double capacityInKg,
+        double toleranceInKg
+    );
+
+    @Data
+    class Result<C extends Content<C>> {
+        public final Bucket<C> discarded;
+        public final Bucket<C> updatedHoldContent;
+    }
+}

agents/src/main/java/uk/ac/ox/poseidon/agents/vessels/hold/ProportionalBiomassOvercapacityDiscardingStrategy.java

@@ -0,0 +1,54 @@
+/*
+ * POSEIDON: an agent-based model of fisheries
+ * Copyright (c) 2025 CoHESyS Lab [email protected]
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ *
+ */
+
+package uk.ac.ox.poseidon.agents.vessels.hold;
+
+import uk.ac.ox.poseidon.biology.Bucket;
+import uk.ac.ox.poseidon.biology.biomass.Biomass;
+
+public class ProportionalBiomassOvercapacityDiscardingStrategy
+    implements OvercapacityDiscardingStrategy<Biomass> {
+    @Override
+    public Result<Biomass> discard(
+        final Bucket<Biomass> contentToAdd,
+        final Bucket<Biomass> currentHoldContent,
+        final double capacityInKg,
+        final double toleranceInKg
+    ) {
+        final double contentToAddInKg = contentToAdd.getTotalBiomass().asKg();
+        final double currentContentInKg = currentHoldContent.getTotalBiomass().asKg();
+        final double availableCapacityInKg = capacityInKg - currentContentInKg;
+        if (contentToAddInKg <= availableCapacityInKg) {
+            return new Result<>(
+                Bucket.empty(),
+                currentHoldContent.add(contentToAdd)
+            );
+        } else {
+            final double proportionToKeep = availableCapacityInKg / contentToAddInKg;
+            final Bucket<Biomass> contentToKeep =
+                contentToAdd.mapContent(biomass ->
+                    biomass.multiply(proportionToKeep)
+                );
+            return new Result<>(
+                contentToAdd.subtract(contentToKeep),
+                currentHoldContent.add(contentToKeep)
+            );
+        }
+    }
+}

agents/src/main/java/uk/ac/ox/poseidon/agents/vessels/hold/ProportionalBiomassOvercapacityDiscardingStrategyFactory.java

@@ -0,0 +1,35 @@
+/*
+ * POSEIDON: an agent-based model of fisheries
+ * Copyright (c) 2025 CoHESyS Lab [email protected]
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ *
+ */
+
+package uk.ac.ox.poseidon.agents.vessels.hold;
+
+import uk.ac.ox.poseidon.agents.vessels.Vessel;
+import uk.ac.ox.poseidon.agents.vessels.VesselScopeFactory;
+import uk.ac.ox.poseidon.core.Simulation;
+
+public class ProportionalBiomassOvercapacityDiscardingStrategyFactory
+    extends VesselScopeFactory<ProportionalBiomassOvercapacityDiscardingStrategy> {
+    @Override
+    protected ProportionalBiomassOvercapacityDiscardingStrategy newInstance(
+        final Simulation simulation,
+        final Vessel vessel
+    ) {
+        return new ProportionalBiomassOvercapacityDiscardingStrategy();
+    }
+}

agents/src/main/java/uk/ac/ox/poseidon/agents/vessels/hold/StandardBiomassHold.java

@@ -0,0 +1,67 @@
+/*
+ * POSEIDON: an agent-based model of fisheries
+ * Copyright (c) 2025 CoHESyS Lab [email protected]
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ *
+ */
+
+package uk.ac.ox.poseidon.agents.vessels.hold;
+
+import lombok.Getter;
+import lombok.RequiredArgsConstructor;
+import uk.ac.ox.poseidon.agents.vessels.hold.OvercapacityDiscardingStrategy.Result;
+import uk.ac.ox.poseidon.biology.Bucket;
+import uk.ac.ox.poseidon.biology.biomass.Biomass;
+
+@RequiredArgsConstructor
+public class StandardBiomassHold implements Hold<Biomass> {
+
+    private final double capacityInKg;
+    private final double toleranceInKg;
+    private final OvercapacityDiscardingStrategy<Biomass> overcapacityDiscardingStrategy;
+    @Getter
+    private Bucket<Biomass> content = Bucket.empty();
+
+    @Override
+    public Bucket<Biomass> addContent(final Bucket<Biomass> contentToAdd) {
+        final Bucket<Biomass> newContent = content.add(contentToAdd);
+        if (newContent.getTotalBiomass().asKg() <= capacityInKg + toleranceInKg) {
+            content = newContent;
+            return Bucket.empty();
+        } else {
+            final Result<Biomass> discardingResult =
+                overcapacityDiscardingStrategy.discard(
+                    contentToAdd,
+                    content,
+                    capacityInKg,
+                    toleranceInKg
+                );
+            content = discardingResult.updatedHoldContent;
+            return discardingResult.discarded;
+        }
+    }
+
+    @Override
+    public boolean isFull() {
+        return content.getTotalBiomass().asKg() >= capacityInKg - toleranceInKg;
+    }
+
+    @Override
+    public Bucket<Biomass> removeContent() {
+        final Bucket<Biomass> removedContent = content;
+        content = Bucket.empty();
+        return removedContent;
+    }
+}

agents/src/main/java/uk/ac/ox/poseidon/agents/vessels/hold/StandardBiomassHoldFactory.java

@@ -0,0 +1,60 @@
+/*
+ * POSEIDON: an agent-based model of fisheries
+ * Copyright (c) 2025 CoHESyS Lab [email protected]
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ *
+ */
+
+package uk.ac.ox.poseidon.agents.vessels.hold;
+
+import lombok.AllArgsConstructor;
+import lombok.Getter;
+import lombok.NoArgsConstructor;
+import lombok.Setter;
+import uk.ac.ox.poseidon.agents.vessels.Vessel;
+import uk.ac.ox.poseidon.agents.vessels.VesselScopeFactory;
+import uk.ac.ox.poseidon.biology.biomass.Biomass;
+import uk.ac.ox.poseidon.core.Factory;
+import uk.ac.ox.poseidon.core.Simulation;
+
+import javax.measure.Quantity;
+import javax.measure.quantity.Mass;
+
+import static javax.measure.MetricPrefix.KILO;
+import static tech.units.indriya.unit.Units.GRAM;
+
+@Getter
+@Setter
+@NoArgsConstructor
+@AllArgsConstructor
+public class StandardBiomassHoldFactory extends VesselScopeFactory<StandardBiomassHold> {
+
+    private Factory<? extends Quantity<Mass>> capacity;
+    private Factory<? extends Quantity<Mass>> tolerance;
+    private VesselScopeFactory<? extends OvercapacityDiscardingStrategy<Biomass>>
+        overcapacityDiscardingStrategy;
+
+    @Override
+    protected StandardBiomassHold newInstance(
+        final Simulation simulation,
+        final Vessel vessel
+    ) {
+        return new StandardBiomassHold(
+            capacity.get(simulation).to(KILO(GRAM)).getValue().doubleValue(),
+            tolerance.get(simulation).to(KILO(GRAM)).getValue().doubleValue(),
+            overcapacityDiscardingStrategy.get(simulation, vessel)
+        );
+    }
+}

agents/src/main/java/uk/ac/ox/poseidon/agents/vessels/hold/VoidHold.java

@@ -54,6 +54,16 @@ public Bucket<C> getContent() {
         return Bucket.empty();
     }
 
+    /**
+     * A void hold is never full. There is always more room in the void.
+     *
+     * @return false
+     */
+    @Override
+    public boolean isFull() {
+        return false;
+    }
+
     /**
      * Removes all content from the hold and returns it. In the context of a {@code VoidHold}, no
      * content is actually stored, so this method will always return an empty bucket.