Vertex name changes

[andrewtarzia]

Related Issues: #344
Requested Reviewers: @lukasturcani

This PR makes all vertex classes (except for Cage and Cof base classes) publicly accessible by simply changing class names. Also removes designation of Cage and Cof types within name, as that is designated by the access point. (sorry if my terminology here is wrong). An example of accessing the vertices was added.

The following example shows that this works.

import stk

vertex = stk.Vertex(0, [0, 0, 0])
print(vertex)
try:
    vertex = stk.LinearVertex(1, [0, 0, 0])
    print(vertex, 'should not show')
except AttributeError:
    print('success on fail')
vertex = stk.cage.LinearVertex(1, [0, 0, 0])
print(vertex)
vertex = stk.cage.vertices.LinearVertex(1, [0, 0, 0])
print(vertex)
vertex = stk.cage.OnePlusOneVertex(1, [0, 0, 0], 0)
print(vertex)
vertex = stk.polymer.linear.TailVertex(0, [0, 0, 0], False)
print(vertex)
vertex = stk.cof.NonLinearVertex(0, [0, 0, 0], False)
print(vertex)
vertex = stk.host_guest.HostVertex(0, [0, 0, 0])
print(vertex)
vertex = stk.macrocycle.CycleVertex(0, [0, 0, 0], False, 0)
print(vertex)
vertex = stk.metal_complex.MonoDentateLigandVertex(0, [0, 0, 0])
print(vertex)
vertex = stk.rotaxane.AxleVertex(0, [0, 0, 0])
print(vertex)
try:
    vertex = stk.AxleVertex(1, [0, 0, 0])
    print(vertex, 'should not show')
except AttributeError:
    print('success on fail')
try:
    vertex = stk.HostVertex(1, [0, 0, 0])
    print(vertex, 'should not show')
except AttributeError:
    print('success on fail')

[lukasturcani]

now that the vertices are public, I think they should be accessed in tests by the public API, not by this "unofficial" API. so stk.cage.LinearVertex not vertices.LinearVertex.

[andrewtarzia]

I agree and have replaced all vertices = stk.cage.vertices (for example) with direct calls to stk.cage.VERTEXNAME.

[lukasturcani]

I also have some concerns about exposing all of the vertex classes. I'm not against it, but I guess I would like to know what the arguments for and against this are? For example, what is the cost / benefit of exposing stk.host_guest.HostVertex?

[andrewtarzia]

I see your concern and my main argument is how do you decide which to make public and which not to? There is no technical reason I see for that other than the desire to minimise access until needed.

For example, why make the cage vertex accessible, but not the host vertex? A user may be just as inclined to use that in their own code as an stk.cage.LinearVertex

[lukasturcani]

I guess with cages the extensibility argument is a bit easier. The amount of cage topologies we have already, means that we have a pretty good understanding of how this vertex can be used to easily build new topology graphs. With something like host guest, we have experience in using it in 1 topology graph. so the reusability of it a lot less well understood. I guess I'm not convinced that just because a user wants to use that vertex, that I want to allow them to, because doing so would remove my flexibility to modify it in the future.

Having said that, I think we can expose them because removing them can be easy for the users to fix (just copy paste the code into their own scripts). So I think it is a worthwhile experiment.

[lukasturcani]

Also, I think there is a type error here. the position should be a tuple of float so (0., 0., 0.)

https://stk.readthedocs.io/en/stable/stk.molecular.topology_graphs.topology_graph.vertex.html#stk.molecular.topology_graphs.topology_graph.vertex.Vertex

I realize that this type error exists in the actual code, but I don't want you to change that. This PR just needs to make sure that users get a fully correct example.

[andrewtarzia]

Done.