Merge pull request #294 from Libensemble/docs/updates_for_053_format

Docs/updates for 053 format

libensemble/alloc_funcs/fast_alloc.py

@@ -9,8 +9,8 @@ def give_sim_work_first(W, H, sim_specs, gen_specs, alloc_specs, persis_info):
     is told to call the generator function, provided this wouldn't result in
     more than ``gen_specs['user']['num_active_gen']`` active generators.
 
-    :See:
-        ``/libensemble/tests/regression_tests/test_fast_alloc.py``
+    .. seealso::
+        `test_fast_alloc.py <https://github.com/Libensemble/libensemble/blob/develop/libensemble/tests/regression_tests/test_fast_alloc.py>`_
     """
 
     Work = {}

libensemble/alloc_funcs/fast_alloc_and_pausing.py

@@ -21,8 +21,8 @@ def give_sim_work_first(W, H, sim_specs, gen_specs, alloc_specs, persis_info):
     alloc_specs['user']['stop_partial_fvec_eval']: True --- after the value returned from
         combine_component_func is larger than a known upper bound on the objective.
 
-    :See:
-        ``/libensemble/tests/regression_tests/test_chwirut_uniform_sampling_one_residual_at_a_time.py``
+    .. seealso::
+        `test_chwirut_uniform_sampling_one_residual_at_a_time.py <https://github.com/Libensemble/libensemble/blob/develop/libensemble/tests/regression_tests/test_chwirut_uniform_sampling_one_residual_at_a_time.py>`_
     """
 
     Work = {}

libensemble/alloc_funcs/fast_alloc_to_aposmm.py

@@ -12,8 +12,8 @@ def give_sim_work_first(W, H, sim_specs, gen_specs, alloc_specs, persis_info):
     more than ``gen_specs['user']['num_active_gen']`` active generators. Also allows
     for a 'batch_mode'.
 
-    :See:
-        ``/libensemble/tests/regression_tests/test_6-hump_camel_aposmm_LD_MMA.py``
+    .. seealso::
+        `test_6-hump_camel_aposmm_LD_MMA.py <https://github.com/Libensemble/libensemble/blob/develop/libensemble/tests/regression_tests/test_6-hump_camel_aposmm_LD_MMA.py>`_
     """
 
     Work = {}

libensemble/alloc_funcs/give_pregenerated_work.py

@@ -6,8 +6,8 @@ def give_pregenerated_sim_work(W, H, sim_specs, gen_specs, alloc_specs, persis_i
     This allocation function gives (in order) entries in alloc_spec['x'] to
     idle workers. It is an example use case where no gen_func is used.
 
-    :See:
-        ``/libensemble/tests/regression_tests/test_fast_alloc.py``
+    .. seealso::
+        `test_fast_alloc.py <https://github.com/Libensemble/libensemble/blob/develop/libensemble/tests/regression_tests/test_fast_alloc.py>`_
     """
 
     Work = {}

libensemble/alloc_funcs/give_sim_work_first.py

@@ -20,8 +20,8 @@ def give_sim_work_first(W, H, sim_specs, gen_specs, alloc_specs, persis_info):
 
     This is the default allocation function if one is not defined.
 
-    :See:
-        ``/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling.py``
+    .. seealso::
+        `test_6-hump_camel_uniform_sampling.py <https://github.com/Libensemble/libensemble/blob/develop/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling.py>`_
     """
 
     Work = {}

libensemble/alloc_funcs/persistent_aposmm_alloc.py

@@ -13,8 +13,8 @@ def persistent_aposmm_alloc(W, H, sim_specs, gen_specs, alloc_specs, persis_info
     This function assumes that one persistent APOSMM will be started and never
     stopped (until some exit_criterion is satisfied).
 
-    :See:
-        ``/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py``
+    .. seealso::
+        `test_6-hump_camel_persistent_aposmm.py <https://github.com/Libensemble/libensemble/blob/develop/libensemble/tests/regression_tests/test_6-hump_camel_persistent_aposmm.py>`_
     """
 
     Work = {}

libensemble/alloc_funcs/start_only_persistent.py

@@ -10,8 +10,8 @@ def only_persistent_gens(W, H, sim_specs, gen_specs, alloc_specs, persis_info):
     the persistent generator have been returned from the simulation evaluation,
     then this information is given back to the persistent generator.
 
-    :See:
-        ``/libensemble/tests/regression_tests/test_6-hump_camel_persistent_uniform_sampling.py``
+    .. seealso::
+        `test_6-hump_camel_persistent_uniform_sampling.py <https://github.com/Libensemble/libensemble/blob/develop/libensemble/tests/regression_tests/test_6-hump_camel_persistent_uniform_sampling.py>`_
     """
 
     Work = {}

libensemble/alloc_funcs/start_persistent_local_opt_gens.py

@@ -20,8 +20,8 @@ def start_persistent_local_opt_gens(W, H, sim_specs, gen_specs, alloc_specs, per
       evaluated (oldest first).
     - If no points are left, call the generation function.
 
-    :See:
-        ``/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling_with_persistent_localopt_gens.py``
+    .. seealso::
+        `test_6-hump_camel_uniform_sampling_with_persistent_localopt_gens.py <https://github.com/Libensemble/libensemble/blob/develop/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling_with_persistent_localopt_gens.py>`_
     """
 
     Work = {}

libensemble/gen_funcs/aposmm.py

@@ -133,11 +133,12 @@ def aposmm_logic(H, persis_info, gen_specs, _):
         active runs, order of points in each run, etc. The allocation function
         must ensure it's always given.
 
-    :See:
-        ``libensemble/tests/regression_tests/test_branin_aposmm.py``
+    .. seealso::
+        `test_branin_aposmm_nlopt_and_then_scipy.py <https://github.com/Libensemble/libensemble/blob/develop/libensemble/tests/regression_tests/test_branin_aposmm_nlopt_and_then_scipy.py>`_
         for basic APOSMM usage.
-    :See:
-        ``libensemble/tests/regression_tests/test_chwirut_aposmm_one_residual_at_a_time.py``
+
+    .. seealso::
+        `test_chwirut_aposmm_one_residual_at_a_time.py <https://github.com/Libensemble/libensemble/blob/develop/libensemble/tests/regression_tests/test_chwirut_aposmm_one_residual_at_a_time.py>`_
         for an example of APOSMM coordinating multiple local optimization runs
         for an objective with more than one component.
     """
@@ -371,8 +372,8 @@ def update_history_dist(H, n, gen_specs, c_flag):
     """
     Updates distances/indices after new points that have been evaluated.
 
-    :See:
-        ``/libensemble/alloc_funcs/start_persistent_local_opt_gens.py``
+    .. seealso::
+        `start_persistent_local_opt_gens.py <https://github.com/Libensemble/libensemble/blob/develop/libensemble/alloc_funcs/start_persistent_local_opt_gens.py>`_
     """
 
     updated_inds = set()
@@ -766,8 +767,8 @@ def decide_where_to_start_localopt(H, r_k, mu=0, nu=0, gamma_quantile=1):
         Indices where a local opt run should be started
 
 
-    :See:
-        ``/libensemble/alloc_funcs/start_persistent_local_opt_gens.py``
+    .. seealso::
+        `start_persistent_local_opt_gens.py <https://github.com/Libensemble/libensemble/blob/develop/libensemble/alloc_funcs/start_persistent_local_opt_gens.py>`_
     """
 
     if nu > 0:
@@ -890,8 +891,8 @@ def initialize_APOSMM(H, gen_specs):
     """
     Computes common values every time that APOSMM is reinvoked
 
-    :See:
-        ``/libensemble/alloc_funcs/start_persistent_local_opt_gens.py``
+    .. seealso::
+        `start_persistent_local_opt_gens.py <https://github.com/Libensemble/libensemble/blob/develop/libensemble/alloc_funcs/start_persistent_local_opt_gens.py>`_
     """
 
     user_specs = gen_specs['user']

libensemble/gen_funcs/persistent_aposmm.py

@@ -141,11 +141,12 @@ def aposmm(H, persis_info, gen_specs, libE_info):
         active runs, order of points in each run, etc. The allocation function
         must ensure it's always given.
 
-    :See:
-        ``libensemble/tests/regression_tests/test_branin_aposmm.py``
+    .. seealso::
+        `test_branin_aposmm_nlopt_and_then_scipy.py <https://github.com/Libensemble/libensemble/blob/develop/libensemble/tests/regression_tests/test_branin_aposmm_nlopt_and_then_scipy.py>`_
         for basic APOSMM usage.
-    :See:
-        ``libensemble/tests/regression_tests/test_chwirut_aposmm_one_residual_at_a_time.py``
+
+    .. seealso::
+        `test_chwirut_aposmm_one_residual_at_a_time.py <https://github.com/Libensemble/libensemble/blob/develop/libensemble/tests/regression_tests/test_chwirut_aposmm_one_residual_at_a_time.py>`_
         for an example of APOSMM coordinating multiple local optimization runs
         for an objective with more than one component.
     """
@@ -671,8 +672,8 @@ def update_history_dist(H, n):
     """
     Updates distances/indices after new points that have been evaluated.
 
-    :See:
-        ``/libensemble/alloc_funcs/start_persistent_local_opt_gens.py``
+    .. seealso::
+        `start_persistent_local_opt_gens.py <https://github.com/Libensemble/libensemble/blob/develop/libensemble/alloc_funcs/start_persistent_local_opt_gens.py>`_
     """
 
     new_inds = np.where(~H['known_to_aposmm'])[0]
@@ -803,8 +804,8 @@ def decide_where_to_start_localopt(H, n, n_s, rk_const, ld=0, mu=0, nu=0):
         Indices where a local opt run should be started
 
 
-    :See:
-        ``/libensemble/alloc_funcs/start_persistent_local_opt_gens.py``
+    .. seealso::
+        `start_persistent_local_opt_gens.py <https://github.com/Libensemble/libensemble/blob/develop/libensemble/alloc_funcs/start_persistent_local_opt_gens.py>`_
     """
 
     r_k = calc_rk(n, n_s, rk_const, ld)
@@ -895,8 +896,8 @@ def initialize_APOSMM(H, user_specs, libE_info):
     """
     Computes common values every time that APOSMM is reinvoked
 
-    :See:
-        ``/libensemble/alloc_funcs/start_persistent_local_opt_gens.py``
+    .. seealso::
+        `start_persistent_local_opt_gens.py <https://github.com/Libensemble/libensemble/blob/develop/libensemble/alloc_funcs/start_persistent_local_opt_gens.py>`_
     """
     n = len(user_specs['ub'])
 

libensemble/gen_funcs/persistent_uniform_sampling.py

@@ -9,8 +9,8 @@ def persistent_uniform(H, persis_info, gen_specs, libE_info):
     This generation function always enters into persistent mode and returns
     ``gen_specs['gen_batch_size']`` uniformly sampled points.
 
-    :See:
-        ``libensemble/libensemble/tests/regression_tests/test_6-hump_camel_persistent_uniform_sampling.py``
+    .. seealso::
+        `test_6-hump_camel_persistent_uniform_sampling.py <https://github.com/Libensemble/libensemble/blob/develop/libensemble/tests/regression_tests/test_6-hump_camel_persistent_uniform_sampling.py>`_
     """
     ub = gen_specs['user']['ub']
     lb = gen_specs['user']['lb']

libensemble/gen_funcs/sampling.py

@@ -12,8 +12,8 @@ def uniform_random_sample_with_different_nodes_and_ranks(H, persis_info, gen_spe
     ``gen_specs['user']['lb']``. Also randomly requests a different ``number_of_nodes``
     and ``ranks_per_node`` to be used in the evaluation of the generated point.
 
-    :See:
-        ``libensemble/tests/regression_tests/test_6-hump_camel_with_different_nodes_uniform_sample.py``
+    .. seealso::
+        `test_6-hump_camel_with_different_nodes_uniform_sample.py <https://github.com/Libensemble/libensemble/blob/develop/libensemble/tests/regression_tests/test_6-hump_camel_with_different_nodes_uniform_sample.py>`_
     """
     ub = gen_specs['user']['ub']
     lb = gen_specs['user']['lb']
@@ -46,8 +46,8 @@ def uniform_random_sample_obj_components(H, persis_info, gen_specs, _):
     and ``gen_specs['user']['lb']`` but requests each ``obj_component`` be evaluated
     separately.
 
-    :See:
-        ``libensemble/tests/regression_tests/test_chwirut_uniform_sampling_one_residual_at_a_time.py``
+    .. seealso::
+        `test_chwirut_uniform_sampling_one_residual_at_a_time.py <https://github.com/Libensemble/libensemble/blob/develop/libensemble/tests/regression_tests/test_chwirut_uniform_sampling_one_residual_at_a_time.py>`_
     """
     ub = gen_specs['user']['ub']
     lb = gen_specs['user']['lb']
@@ -74,8 +74,8 @@ def uniform_random_sample(H, persis_info, gen_specs, _):
     Generates ``gen_specs['user']['gen_batch_size']`` points uniformly over the domain
     defined by ``gen_specs['user']['ub']`` and ``gen_specs['user']['lb']``.
 
-    :See:
-        ``libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling.py``
+    .. seealso::
+        `test_6-hump_camel_uniform_sampling.py <https://github.com/Libensemble/libensemble/blob/develop/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling.py>`_
     """
     ub = gen_specs['user']['ub']
     lb = gen_specs['user']['lb']

libensemble/gen_funcs/uniform_or_localopt.py

@@ -15,8 +15,8 @@ def uniform_or_localopt(H, persis_info, gen_specs, libE_info):
     ``libE_info['persistent']`` isn't ``True``).  Otherwise, the generation
     function a persistent nlopt local optimization run.
 
-    :See:
-        ``libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling_with_persistent_localopt_gens.py``
+    .. seealso::
+        `test_6-hump_camel_uniform_sampling_with_persistent_localopt_gens.py <https://github.com/Libensemble/libensemble/blob/develop/libensemble/tests/regression_tests/test_6-hump_camel_uniform_sampling_with_persistent_localopt_gens.py>`_
     """
 
     if libE_info.get('persistent'):

libensemble/sim_funcs/chwirut1.py

@@ -260,11 +260,13 @@ def chwirut_eval(H, persis_info, sim_specs, _):
     component of the objective will be evaluated. Otherwise, all 214 components
     are evaluated and returned in the ``'fvec'`` field.
 
-    :See:
-        ``/libensemble/tests/regression_tests/test_chwirut_pounders.py`` for an example where the entire fvec is computed.
+    .. seealso::
+        `test_chwirut_pounders.py <https://github.com/Libensemble/libensemble/blob/develop/libensemble/tests/regression_tests/test_chwirut_pounders.py>`_
+        for an example where the entire fvec is computed each call.
 
-    :See:
-        ``/libensemble/tests/regression_tests/test_chwirut_aposmm_one_residual_at_a_time.py``
+    .. seealso::
+        `test_chwirut_aposmm_one_residual_at_a_time.py <https://github.com/Libensemble/libensemble/blob/develop/libensemble/tests/regression_tests/test_chwirut_aposmm_one_residual_at_a_time.py>`_
+        for an example where one component of fvec is computed per call
     """
 
     batch = len(H['x'])

libensemble/sim_funcs/one_d_func.py

@@ -10,8 +10,8 @@ def one_d_example(x, persis_info, sim_specs, _):
     """
     Evaluates the six hump camel function for a single point ``x``.
 
-    :See:
-        ``/libensemble/libensemble/tests/regression_tests/test_fast_alloc.py``
+    .. seealso::
+        `test_fast_alloc.py <https://github.com/Libensemble/libensemble/blob/develop/libensemble/tests/regression_tests/test_fast_alloc.py>`_
     """
 
     O = np.zeros(1, dtype=sim_specs['out'])

libensemble/sim_funcs/six_hump_camel.py

@@ -15,8 +15,8 @@ def six_hump_camel_with_different_ranks_and_nodes(H, persis_info, sim_specs, lib
     performs a system call with a given number of nodes and ranks per node
     using a machinefile (to show one way of evaluating a compiled simulation).
 
-    :See:
-        ``/libensemble/tests/regression_tests/test_6-hump_camel_with_different_nodes_uniform_sample.py``
+    .. seealso::
+        `test_6-hump_camel_with_different_nodes_uniform_sample.py <https://github.com/Libensemble/libensemble/blob/develop/libensemble/tests/regression_tests/test_6-hump_camel_with_different_nodes_uniform_sample.py>`_
     """
 
     from mpi4py import MPI
@@ -60,8 +60,8 @@ def six_hump_camel(H, persis_info, sim_specs, _):
     ``sim_specs['out']`` and pauses for ``sim_specs['user']['pause_time']]`` if
     defined.
 
-    :See:
-        ``/libensemble/libensemble/tests/regression_tests/test_6-hump_camel_aposmm_LD_MMA.py``
+    .. seealso::
+        `test_6-hump_camel_aposmm_LD_MMA.py <https://github.com/Libensemble/libensemble/blob/develop/libensemble/tests/regression_tests/test_6-hump_camel_aposmm_LD_MMA.py>`_
     """
 
     batch = len(H['x'])
@@ -83,8 +83,8 @@ def six_hump_camel_simple(x, persis_info, sim_specs, _):
     """
     Evaluates the six hump camel function for a single point ``x``.
 
-    :See:
-        ``/libensemble/libensemble/tests/regression_tests/test_fast_alloc.py``
+    .. seealso::
+        `test_fast_alloc.py <https://github.com/Libensemble/libensemble/blob/develop/libensemble/tests/regression_tests/test_fast_alloc.py>`_
     """
 
     O = np.zeros(1, dtype=sim_specs['out'])