Allow custom Property integration

[mrossinek]

What is the expected enhancement?

After #303 will be merged, it will not yet be possible to add custom Property objects to the GroupedProperty object used within the BaseProblem implementations. A major reason for holding off on this, is that we really need Qiskit/qiskit#6772 to be implemented. Otherwise, a lot of edge cases can break down when we allow arbitrary sets of properties.

As of Qiskit Nature 0.2.0, the tutorial on the Property framework will explain how to implement a custom Property and contain a note linking to this issue. A workaround by means of passing the operators of interest as aux_operators to the solver will be included.

[mrossinek]

This issue will become resolvable once #406 is merged. However, even then, using the feature proposed in this issue will always require dictionary-based aux_operators. The reason being that only then will it become possible to refactor the GroupedElectronicProperty and GroupedVibrationalProperty classes such that they are no longer abstract (in contrast, currently they are because the second_q_ops() method cannot be implemented on their level).

Anyways, details aside, once we can ensure dict-based aux_operators, we will be able to add this feature. In terms of interface, I am envisioning that custom properties can be added via the BaseProblem.__init__ methods. It will be the user's responsibility to ensure the correct Property implementation.

Such a use case will always be limited in potential with regards to arbitrary transformer support, since a transformer may not know how to handle a certain property. This caveat should be possible to workaround in most scenarios though, especially via leveraging the electronic.IntegralProperty base class (which all electronic transformers know how to handle).

[mrossinek]

I gave this some more thought and wanted to query @pbark and @woodsp-ibm for the following ideas:

• aux_properties (or whatever we may call them) should be supplied BaseProblem.__init__
  The reason being that the properties are blueprints for operators which should be able to undergo the transformer. Hence, these should be supplied at problem level construction rather than during .solve() like the aux_operators.

• We should support both, instances and generators, to be passed into aux_properties.
  Simply accepting instances is pretty straight forward. These would then simply be inserted in the GroupedProperty which was returned by the driver.
  However, also accepting generators which take the GroupedProperty into which they will be inserted as an input, will allow things like dynamic construction of the correct system size (prominent examples are AngularMomentum and Magnetization which require num_spin_orbitals as input)

• How should we handle scenarios in which a user provides an auxiliary property which is already present in the GroupedProperty? Raise an error? Log a warning?
  We could take a similar approach to the HDF5 case where we raise an error by default but provide a way of suppressing the error to a warning.

[woodsp-ibm]

Hopefully I understood the intent of the above; anyway here is my thought back

aux_properties (or whatever we may call them) should be supplied BaseProblem.init

Are we always able to do this? If they are dependent on the problem being further processed, which I think what we generate today are e.g. at least going through the driver to get more information on the problem, does it work at that level in general? The current properties are the result of the driver being run, they are not formulated on the input, rather some entity, which is part of the problem configuration supplied to the init, i.e. the driver, produces them - they are not directly supplied as such.

We should support both, instances and generators,

A generator is pretty much saying one supports a list right - albeit that its a bit more lazily done. In the past in Aqua VQE supported aux_ops as a single instance or a list so as to be convenient in that the user did not have to wrap it in a list if they just had a single instance (not that its of course must to actually do that). Maybe a Generator is what you had in mind for the above so it can be input and only lazily created on demand later - but isn;t information that it might need still an issue.

How should we handle scenarios in which a user provides an auxiliary property which is already present in the GroupedProperty

How do you define already present? I think internally we store these via their name in some map. Hence a unique name would allow it to be stored whereas presumably storing something with the same name (key) would overwrite any existing one. If someone came up with different implementation of something we have is that supported/ok if its called by the same name. I believe we expect/refer to them by name to get them from the current driver result group. In a regular Python dict I any object that existed is overwritten by a new one with the same key right. That seems to be what happens today when you add a property. (Just as an aside I guess the reason the GroupedProperty does not implement Mapping is because we get the key from the item, it name or class name).

As a thought the other way, although this is more about customizing the built-in property behavior rather than strictly custom properties, one of the things we had talked about in the past when having more granular properties was allowing a user to say exclude dipole, or some other other properties from the computation. Though of course in practice the overhead is just some creation of smaller operators and a single evaluation at the result state(s).

[mrossinek]

Are we always able to do this?

No, this is not generally possible. As you point out correctly, cases like e.g. the ElectronicEnergy or ElectronicDipoleMoment could not be handled in such a way. If a user creates a custom property which relies on data that needs to be extracted manually from the driver, they also need to write a custom driver to construct such a property.
However, some cases can be handled quite simply. One example is the OccupiedModals in the vibrational stack. It does not require any input data and is a pure blueprint method to construct operators. Almost the same can be said for AngularMomentum, Magnetization and in the future ElectronicDensity (to some degree) which can be constructed with merely the number of spin orbitals as input. If a user knows this a priori, it is easy to inject these in the initializer. If they do not know them a prior, see below.

A generator is pretty much saying one supports a list right

This is not quite what I meant. In general I think we will support ListOrDictType but I also would like to be able to pass in a function (or list there of) which gets the (e.g.) ElectronicStructureDriverResult as input and can generate additional properties from it. Here is a very simple example:

def construct_magnetization(driver_result: ElectronicStructureDriverResult) -> Magnetization:
    num_spin_orbitals = driver_result.get_property("ParticleNumber").num_spin_orbitals
    return Magnetization(num_spin_orbitals)

problem = ElectronicStructureProblem(driver, transformers=[], aux_properties=[construct_magnetization])

This is a very minimal example but more fancy operations could be done, too.

I think internally we store these via their name in some map.

Yes this is correct. And you're right I guess a user can use an identical name if they want to overwrite, and a different one if they do not want to do that. This will need clear documentation.

was allowing a user to say exclude dipole, or some other other properties from the computation.

This is a very good point actually. Maybe we do not need to provide aux_properties at all but instead expand on my generator idea above and simply allow the user to pass in a callback which can modify the driver result in place? This would allow not only extraction of data for further property construction and addition but could also allow removal of unwanted properties.
Converting the above example:

def extend_properties(driver_result: ElectronicStructureDriverResult) -> None:
    num_spin_orbitals = driver_result.get_property("ParticleNumber").num_spin_orbitals

    driver_result.add_property(Magnetization(num_spin_orbitals))

    driver_result.pop("ElectronicDipoleMoment")

problem = ElectronicStructureProblem(driver, transformers=[], property_cb=extend_properties)

[mrossinek]

In the design described in #701 this feature will directly be available without further changes. Thus, I am closing this issue as it is superseded by that new design.