fix #570, make it easier to zero out migration rates

Author: bhaller

QtSLiM/help/SLiMHelpClasses.html

@@ -1313,7 +1313,8 @@
 <p class="p3">– (void)setCloningRate(numeric rate)</p>
 <p class="p4">Set the cloning rate of this subpopulation.<span class="Apple-converted-space">  </span>The rate is changed to <span class="s1">rate</span>, which should be between 0.0 and 1.0, inclusive (see the SLiM manual for further details).<span class="Apple-converted-space">  </span>Clonal reproduction can be enabled in both non-sexual (i.e. hermaphroditic) and sexual simulations.<span class="Apple-converted-space">  </span>In non-sexual simulations, <span class="s1">rate</span> must be a singleton value representing the overall clonal reproduction rate for the subpopulation.<span class="Apple-converted-space">  </span>In sexual simulations, <span class="s1">rate</span> may be either a singleton (specifying the clonal reproduction rate for both sexes) or a vector containing two numeric values (the female and male cloning rates specified separately, at indices <span class="s1">0</span> and <span class="s1">1</span> respectively).<span class="Apple-converted-space">  </span>During mating and offspring generation, the probability that any given offspring individual will be generated by cloning – by asexual reproduction without gametes or meiosis – will be equal to the cloning rate (for its sex, in sexual simulations) set in the parental (not the offspring!) subpopulation.</p>
 <p class="p3">– (void)setMigrationRates(io&lt;Subpopulation&gt; sourceSubpops, numeric rates)</p>
-<p class="p4">Set the migration rates to this subpopulation from the subpopulations in <span class="s1">sourceSubpops</span> to the corresponding rates specified in <span class="s1">rates</span>; in other words, <span class="s1">rates</span> gives the expected fractions of the children in this subpopulation that will subsequently be generated from parents in the subpopulations <span class="s1">sourceSubpops</span> (see the SLiM manual for further details).<span class="Apple-converted-space">  </span>This method will only set the migration fractions from the subpopulations given; migration rates from other subpopulations will be left unchanged (explicitly set a zero rate to turn off migration from a given subpopulation).<span class="Apple-converted-space">  </span>The type of <span class="s1">sourceSubpops</span> may be either <span class="s1">integer</span>, specifying subpopulations by identifier, or <span class="s1">object</span>, specifying subpopulations directly.</p>
+<p class="p6">Set the migration rates to this subpopulation from the subpopulations in <span class="s1">sourceSubpops</span> to the corresponding rates specified in <span class="s1">rates</span>; in other words, <span class="s1">rates</span> gives the expected fractions of the children in this subpopulation that will subsequently be generated from parents in the subpopulations <span class="s1">sourceSubpops</span> (see section 24.2.1).<span class="Apple-converted-space">  </span>The <span class="s1">rates</span> parameter may be a singleton value, in which case that rate is used for all subpopulations in <span class="s1">sourceSubpops</span>.<span class="Apple-converted-space">  </span>This method will only set the migration fractions from the subpopulations given; migration rates from other subpopulations will be left unchanged (explicitly set a zero rate to turn off migration from a given subpopulation).<span class="Apple-converted-space">  </span>The type of <span class="s1">sourceSubpops</span> may be either <span class="s1">integer</span>, specifying subpopulations by identifier, or <span class="s1">object</span>, specifying subpopulations directly.</p>
+<p class="p6">In general it is illegal to try to set the migration rate into a subpopulation from itself; that rate is, by definition, equal to the remainder after all migration from other subpopulations.<span class="Apple-converted-space">  </span>As a special case for convenience, it is legal to set a rate of <span class="s1">0.0</span> for all subpopulations in the species, including the target subpopulation.<span class="Apple-converted-space">  </span>For example, <span class="s1">subpops.setMigrationRates(allSubpops, 0.0)</span> will turn off all migration into the subpopulations in <span class="s1">subpops</span>.<span class="Apple-converted-space">  </span>The given rate of <span class="s1">0.0</span> from a subpop into itself is simply ignored, for this specific case only.</p>
 <p class="p3">– (void)setSelfingRate(numeric$ rate)</p>
 <p class="p4">Set the selfing rate of this subpopulation.<span class="Apple-converted-space">  </span>The rate is changed to <span class="s1">rate</span>, which should be between 0.0 and 1.0, inclusive (see the SLiM manual for further details).<span class="Apple-converted-space">  </span>Selfing can only be enabled in non-sexual (i.e. hermaphroditic) simulations.<span class="Apple-converted-space">  </span>During mating and offspring generation, the probability that any given offspring individual will be generated by selfing – by self-fertilization via gametes produced by meiosis by a single parent – will be equal to the selfing rate set in the parental (not the offspring!) subpopulation.</p>
 <p class="p3">– (void)setSexRatio(float$ sexRatio)</p>

SLiMgui/SLiMHelpClasses.rtf

@@ -13663,22 +13663,34 @@ This method is similar to getting the
 \f5 \
 \pard\pardeftab720\li547\ri720\sb60\sa60\partightenfactor0
 
-\f4\fs20 \cf0 Set the migration rates to this subpopulation from the subpopulations in 
+\f4\fs20 \cf2 Set the migration rates to this subpopulation from the subpopulations in 
 \f3\fs18 sourceSubpops
 \f4\fs20  to the corresponding rates specified in 
 \f3\fs18 rates
 \f4\fs20 ; in other words, 
 \f3\fs18 rates
 \f4\fs20  gives the expected fractions of the children in this subpopulation that will subsequently be generated from parents in the subpopulations 
 \f3\fs18 sourceSubpops
-\f4\fs20  (see the SLiM manual for further details).  This method will only set the migration fractions from the subpopulations given; migration rates from other subpopulations will be left unchanged (explicitly set a zero rate to turn off migration from a given subpopulation).  The type of 
+\f4\fs20  (see section 24.2.1).  The 
+\f3\fs18 rates
+\f4\fs20  parameter may be a singleton value, in which case that rate is used for all subpopulations in 
+\f3\fs18 sourceSubpops
+\f4\fs20 .  This method will only set the migration fractions from the subpopulations given; migration rates from other subpopulations will be left unchanged (explicitly set a zero rate to turn off migration from a given subpopulation).  The type of 
 \f3\fs18 sourceSubpops
 \f4\fs20  may be either 
 \f3\fs18 integer
 \f4\fs20 , specifying subpopulations by identifier, or 
 \f3\fs18 object
-\f4\fs20 , specifying subpopulations directly.
-\f5 \
+\f4\fs20 , specifying subpopulations directly.\
+In general it is illegal to try to set the migration rate into a subpopulation from itself; that rate is, by definition, equal to the remainder after all migration from other subpopulations.  As a special case for convenience, it is legal to set a rate of 
+\f3\fs18 0.0
+\f4\fs20  for all subpopulations in the species, including the target subpopulation.  For example, 
+\f3\fs18 subpops.setMigrationRates(allSubpops, 0.0)
+\f4\fs20  will turn off all migration into the subpopulations in 
+\f3\fs18 subpops
+\f4\fs20 .  The given rate of 
+\f3\fs18 0.0
+\f4\fs20  from a subpop into itself is simply ignored, for this specific case only.\
 \pard\pardeftab720\li720\fi-446\ri720\sb180\sa60\partightenfactor0
 
 \f3\fs18 \cf0 \'96\'a0(void)setSelfingRate(numeric$\'a0rate)

VERSIONS

@@ -84,6 +84,10 @@ multitrait branch:
 		Substitution: add read-only <trait-name>HemizygousDominance property
 	policy change: the nucleotide and nucleotideValue properties of Substitution are now read-only (I think it was a bug that they were ever read-write...?)
 	fix #564, initializeMutationRateFromFile() needs a `sex` parameter; I'm doing this in multitrait to avoid the annoying doc conflicts
+	fix #570, setMigrationRates() should make it easier to stop all migration (done in multitrait to avoid the annoying doc conflicts)
+		specifically, this entails two changes:
+			allow a singleton migration rate value, applied for all subpops given
+			allow the destination subpop to be given as a source, iff all rates supplied are 0.0, to stop all migration: allSubpops.setMigrationRates(allSubpops, 0.0)
 
 
 version 5.1 (Eidos version 4.1):

core/slim_test_core.cpp

@@ -1337,10 +1337,13 @@ void _RunSubpopulationTests(void)
 	SLiMAssertScriptRaise(gen1_setup_p1p2p3 + "1 early() { p1.setMigrationRates(c(2, 4), c(0.1, 0.1)); } 10 early() { stop(); }", "not defined", __LINE__);
 	SLiMAssertScriptRaise(gen1_setup_p1p2p3 + "1 early() { p1.setMigrationRates(c(2, 2), c(0.1, 0.1)); } 10 early() { stop(); }", "two rates set", __LINE__);
 	SLiMAssertScriptRaise(gen1_setup_p1p2p3 + "1 early() { p1.setMigrationRates(c(p2, p2), c(0.1, 0.1)); } 10 early() { stop(); }", "two rates set", __LINE__);
-	SLiMAssertScriptRaise(gen1_setup_p1p2p3 + "1 early() { p1.setMigrationRates(c(2, 3), 0.1); } 10 early() { stop(); }", "to be equal in size", __LINE__);
+	SLiMAssertScriptStop(gen1_setup_p1p2p3 + "1 early() { p1.setMigrationRates(c(2, 3), 0.1); } 10 early() { stop(); }", __LINE__);
+	SLiMAssertScriptRaise(gen1_setup_p1p2p3 + "1 early() { p1.setMigrationRates(c(2, 3), float(0)); } 10 early() { stop(); }", "to be equal in size", __LINE__);
+	SLiMAssertScriptRaise(gen1_setup_p1p2p3 + "1 early() { p1.setMigrationRates(c(2, 3), c(0.1, 0.1, 0.1)); } 10 early() { stop(); }", "to be equal in size", __LINE__);
 	SLiMAssertScriptRaise(gen1_setup_p1p2p3 + "1 early() { p1.setMigrationRates(2, c(0.1, 0.1)); } 10 early() { stop(); }", "to be equal in size", __LINE__);
 	SLiMAssertScriptRaise(gen1_setup_p1p2p3 + "1 early() { p1.setMigrationRates(2, -0.0001); } 10 early() { stop(); }", "within [0,1]", __LINE__);
 	SLiMAssertScriptRaise(gen1_setup_p1p2p3 + "1 early() { p1.setMigrationRates(2, 1.0001); } 10 early() { stop(); }", "within [0,1]", __LINE__);
+	SLiMAssertScriptRaise(gen1_setup_p1p2p3 + "1 early() { p1.setMigrationRates(c(2, 3), 0.6); } 10 early() { stop(); }", "must sum to <= 1.0", __LINE__, false);	// raise is from EvolveSubpopulation(); we don't force constraints prematurely
 	SLiMAssertScriptRaise(gen1_setup_p1p2p3 + "1 early() { p1.setMigrationRates(c(2, 3), c(0.6, 0.6)); } 10 early() { stop(); }", "must sum to <= 1.0", __LINE__, false);	// raise is from EvolveSubpopulation(); we don't force constraints prematurely
 
 	// Test Subpopulation - (void)setSelfingRate(numeric$ rate)

core/subpopulation.cpp

@@ -8975,22 +8975,34 @@ EidosValue_SP Subpopulation::ExecuteMethod_setMigrationRates(EidosGlobalStringID
 	int source_subpops_count = sourceSubpops_value->Count();
 	int rates_count = rates_value->Count();
 	std::vector<slim_objectid_t> subpops_seen;
+	bool saw_nonzero_rate = false, saw_self_reference = false;
 
-	if (source_subpops_count != rates_count)
-		EIDOS_TERMINATION << "ERROR (Subpopulation::ExecuteMethod_setMigrationRates): setMigrationRates() requires sourceSubpops and rates to be equal in size." << EidosTerminate();
+	if ((source_subpops_count != rates_count) && (rates_count != 1))
+		EIDOS_TERMINATION << "ERROR (Subpopulation::ExecuteMethod_setMigrationRates): setMigrationRates() requires sourceSubpops and rates to be equal in size, or rates to be singleton." << EidosTerminate();
 
 	for (int value_index = 0; value_index < source_subpops_count; ++value_index)
 	{
 		EidosObject *source_subpop = SLiM_ExtractSubpopulationFromEidosValue_io(sourceSubpops_value, value_index, &species_.community_, &species_, "setMigrationRates()");		// SPECIES CONSISTENCY CHECK
 		slim_objectid_t source_subpop_id = ((Subpopulation *)(source_subpop))->subpopulation_id_;
-		
+		double migrant_fraction = ((rates_count == 1) ? rates_value->NumericAtIndex_NOCAST(0, nullptr) : rates_value->NumericAtIndex_NOCAST(value_index, nullptr));
+		
+		// BCH 11/16/2025: We used to require that the target subpop was not a member of sourceSubpops; we would
+		// raise an error in all cases if that occurred.  Now we relax those rules slightly, to make it easier
+		// to zero out all immigration into a subpop or subpops; we allow self-reference, but *only* if *all*
+		// rates specified in the call are 0.0.  So you can do, e.g., allSubpops.setMigrationRates(allSubpops, 0).
+		// See https://github.com/MesserLab/SLiM/issues/570.  As part of that fix, we also now allow rates to
+		// provide a singleton value, used for all sourceSubpops.
+		if (migrant_fraction != 0.0)
+			saw_nonzero_rate = true;
 		if (source_subpop_id == subpopulation_id_)
-			EIDOS_TERMINATION << "ERROR (Subpopulation::ExecuteMethod_setMigrationRates): setMigrationRates() does not allow migration to be self-referential (originating within the destination subpopulation)." << EidosTerminate();
+			saw_self_reference = true;
+		if (saw_self_reference && saw_nonzero_rate)
+			EIDOS_TERMINATION << "ERROR (Subpopulation::ExecuteMethod_setMigrationRates): setMigrationRates() does not allow migration to be self-referential (originating within the destination subpopulation), except when all rates are zero (for convenience)." << EidosTerminate();
+		
+		// can't specify the same source subpopulation twice
 		if (std::find(subpops_seen.begin(), subpops_seen.end(), source_subpop_id) != subpops_seen.end())
 			EIDOS_TERMINATION << "ERROR (Subpopulation::ExecuteMethod_setMigrationRates): setMigrationRates() two rates set for subpopulation p" << source_subpop_id << "." << EidosTerminate();
 
-		double migrant_fraction = rates_value->NumericAtIndex_NOCAST(value_index, nullptr);
-		
 		population_.SetMigration(*this, source_subpop_id, migrant_fraction);
 		subpops_seen.emplace_back(source_subpop_id);
 	}