This is might not exist as a “file”, as such, but exists as a data structure entity to be the owner of the circuits required in a particular design. The “root circuit” is the uppermost level of hierarchy.
A circuit entity is the key concept in this model. It defines an electrical block by a its external connections (MPorts). A schematic is one way of representing a circuit, hence a circuit object may own or more page of schematics.
We may also define a symbolic (graphic) representation of a circuit - this is like a schematic page, however its representation should fit within a single sheet. The minimum a symbolic representation must contain is the pins which connect it to higher levels of circuit hierarchy.
If it is to be useful as a re-usable block, a sub-circuit must expose electrical connectivity for a parent circuit to connect with. Each such connection is represented by an Mport (Master port). This term (re-used from gnetman) represents the fact that once a circuit is instantiated, we need to differentiate between the connections of each specific instance. This is done with instance specific Port structures. The ports point back at the Mports (master ports) of the circuit representation.
A circuit represents a re-usable electrical entity which we may replicate at various points in our design hierarchy. This is done by instantiating the sub-circuit in a higher level of hierarchy. Each instance is associated with an Instance structure, which is a placeholder for instance specific attributes such as the sub-circuit's hierarchical refdes.
An Attrib defines meta-data attached which might be attached to a circuit, a circuit's Mport, a specific circuit instance, or a Net.
In a break from gEDA's current attrib model, it makes sense to associate the meta-data directly with the particular entity it pertains to, rather than the graphic representation. This is because some forms of sub-circuit entity may be defined without a schematic, and could still require this meta-data. It will be possible to reference any attrib within the realm of a circuit for display on its schematic page(s) where that is desired.
A Netlist defines the electrical connectivity of a circuit. It owns a number of Nets, which individually represent a single connection between Mports belonging to this circuit, and ports of instantiated sub-circuits.
Initially, it is likely there will only be one netlist for a circuit - the one constructed from processing the electrically relevant objects on page(s) of the circuit's schematic.
Future developments may see multiple netlists for a circuit, possibly some generated / written in an HDL language, and critically, re-exported from a layout package (e.g. PCB). It will be possible to identify and flag up differences in connectivity throughout a design flow, be that from HDL to schematic, or schematic to layout.
This has real applications in back-annotation and in design verification.
A net associates with structures forming a given electrical connection within this circuit.
As we also have a graphical representation of the wires (ConnSegments) which make up this connection, each Net can be associated with multiple ConnSegments. The association to Pins representing Mports of this circuit and to the Pins of any instantiated sub-circuits is made via a net's association to the appropriate Mport and port structures.
A page is a canvas for placing graphical objects representing a circuit. A page can be used to draw an electrically meaningful schematic, or it can be used to draw a symbolic representation of the circuit entity.
Whilst most objects on a page are graphic primitives, there are some which have a relation to the circuit's electrical specification.
(from conversation on MSN/IRC on 10th April 2007 – Peter Brett / Peter Clifton)