Feature / user-function input/output field decorators

[jlnav]

Addresses #1011

So immutable input/output fields of user functions are attributes. Users don't need to specify data-types of functions they're not actively developing, and upon discovering a function can immediately tell what the function inputs and outputs:

import numpy as np

from libensemble.specs import input_fields, output_data


@input_fields(["x"])
@output_data([("f", float)])
def one_d_example(x, persis_info, sim_specs, _):

    H_o = np.zeros(1, dtype=sim_specs["out"])

    H_o["f"] = np.linalg.norm(x)

    return H_o, persis_info

WHY?

Consider the common example request or scenario:

• "I want to use a calibration function"
• "Okay, try using Surmise (or another)"
• "What inputs and outputs does that function use?"
• "The ones we wrote in our gen_specs in our Surmise example"

The user can't currently browse functions and immediately tell what fields are both required and configurable the way they can for the rest of libE's Python interface. They need to copy/paste the gen/sim_specs from an example. Furthermore, unless the user is also adjusting the function much of the copy/pasted specs currently can't be modified by the user.

---

If a given function, say APOSMM, has been decorated with its immutable data-types, the user should still append
the fields with attributes chosen later, e.g. dimension:

gen_specs = GenSpecs(
   gen_f = persistent_aposmm,
   user= {
            "initial_sample_size": 100,
            ...
            "ub": np.array([3, 2]),
        },
   )
gen_specs.out.append(("x", float, 2))
gen_specs.out.append(("x_on_cube", float, 2))

---

Any user function that has been decorated has those input/output fields automatically appended to the function's docstring:

https://libensemble--1072.org.readthedocs.build/en/1072/examples/sim_funcs.html#six_hump_camel.six_hump_camel

[codecov]

Codecov Report

Attention: Patch coverage is 69.11765% with 21 lines in your changes missing coverage. Please review.

Project coverage is 71.78%. Comparing base (62dde20) to head (cdfd5d3).
Report is 577 commits behind head on develop.

Files	Patch %	Lines
libensemble/utils/validators.py	61.90%	8 Missing and 8 partials ⚠️
libensemble/specs.py	75.00%	5 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff              @@
##           develop    #1072       +/-   ##
============================================
- Coverage    90.23%   71.78%   -18.45%     
============================================
  Files           91       92        +1     
  Lines         8200     8328      +128     
  Branches      1454     1483       +29     
============================================
- Hits          7399     5978     -1421     
- Misses         569     2090     +1521     
- Partials       232      260       +28     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.