#ifndef NETLIST_H
#define NETLIST_H

/*
 * Summary
 * =======
 * This file defines the Netlist class, which stores the connectivity information
 * of the components in a netlist. It is the base class for AtomNetlist and ClusteredNetlist.
 *
 * Overview
 * ========
 * The netlist logically consists of several different components: Blocks, Ports, Pins and Nets
 * Each component in the netlist has a unique template identifier (BlockId, PortId, PinId, NetId)
 * used to retrieve information about it. In this implementation these ID's are unique throughout the
 * netlist (i.e. every port in the netlist has a unique ID, even if the ports share a common type).
 *
 * Block
 * -----
 * A Block is the primitive netlist element (a node in the netlist hyper-graph).
 * Blocks have various attributes (a name, a type etc.) and are associated with sets of
 * input/output/clock ports.
 *
 * Block related information can be retrieved using the block_*() member functions.
 *
 * Pins
 * ----
 * Pins define single-bit connections between a block and a net.
 *
 * Pin related information can be retrieved using the pin_*() member functions.
 *
 * Nets
 * ----
 * Nets represent the connections between blocks (the edges of the netlist hyper-graph).
 * Each net has a single driver pin, and a set of sink pins.
 *
 * Net related information can be retrieved using the net_*() member functions.
 *
 * Ports
 * -----
 * A Port is a (potentially multi-bit) group of pins.
 *
 * For example, the two operands and output of an N-bit adder would logically be grouped as three ports.
 * Ports have a specified bit-width which defines how many pins form the port.
 *
 * Port related information can be retrieved using the port_*() member functions.
 *
 *
 * Usage
 * =====
 *
 * The following provides usage examples for common use-cases.
 *
 * Walking the netlist
 * -------------------
 * To iterate over the whole netlist use the blocks() and/or nets() member functions:
 *
 *      Netlist netlist;
 *
 *      //... initialize the netlist
 *
 *      //Iterate over all the blocks
 *      for(BlockId blk_id : netlist.blocks()) {
 *          //Do something with each block
 *      }
 *
 *
 *      //Iterate over all the nets
 *      for(NetId net_id : netlist.nets()) {
 *          //Do something with each net
 *      }
 *
 * To retrieve information about a netlist component call one of the associated member functions:
 *
 *      //Print out each block's name
 *      for(BlockId blk_id : netlist.blocks()) {
 *
 *          //Get the block name
 *          const std::string& block_name = netlist.block_name(blk_id);
 *
 *          //Print it
 *          printf("Block: %s\n", block_name.c_str());
 *      }
 *
 * Note that the member functions are associated with the type of component (e.g. block_name() yields
 * the name of a block, net_name() yields the name of a net).
 *
 * Tracing cross-references
 * ------------------------
 * It is common to need to trace the netlist connectivity. The Netlist allows this to be done
 * efficiently by maintaining cross-references between the various netlist components.
 *
 * The following diagram shows the main methods and relationships between netlist components:
 *
 *            +---------+      pin_block()
 *            |         |<--------------------------+
 *            |  Block  |                           |
 *            |         |-----------------------+   |
 *            +---------+      block_pins()     |   |
 *               |   ^                          v   |
 *               |   |                       +---------+  net_pins()  +---------+
 *               |   |                       |         |<-------------|         |
 * block_ports() |   | port_block()          |   Pin   |              |   Net   |
 *               |   |                       |         |------------->|         |
 *               |   |                       +---------+  pin_net()   +---------+
 *               v   |                          ^   |
 *            +---------+      port_pins()      |   |
 *            |         |-----------------------+   |
 *            |  Port   |                           |
 *            |         |<--------------------------+
 *            +---------+      pin_port()
 *
 * Note that methods which are plurals (e.g. net_pins()) return multiple components.
 *
 *
 * As an example consider the case where we wish to find all the blocks associated with a particular net:
 *
 *      NetId net_id;
 *
 *      //... Initialize net_id with the net of interest
 *
 *      //Iterate through each pin on the net to get the associated port
 *      for(PinId pin_id : netlist.net_pins(net_id)) {
 *
 *          //Get the port associated with the pin
 *          PortId port_id = netlist.pin_port(pin_id);
 *
 *          //Get the block associated with the port
 *          BlockId blk_id = netlist.port_block(port_id);
 *
 *          //Print out the block name
 *          const std::string& block_name = netlist.block_name(blk_id);
 *          printf("Associated block: %s\n", block_name.c_str());
 *      }
 *
 * Netlist also defines some convenience functions for common operations to avoid tracking the intermediate IDs
 * if they are not needed. The following produces the same result as above:
 *
 *      NetId net_id;
 *
 *      //... Initialize net_id with the net of interest
 *
 *      //Iterate through each pin on the net to get the associated port
 *      for(PinId pin_id : netlist.net_pins(net_id)) {
 *
 *          //Get the block associated with the pin (bypassing the port)
 *          BlockId blk_id = netlist.pin_block(pin_id);
 *
 *          //Print out the block name
 *          const std::string& block_name = netlist.block_name(blk_id);
 *          printf("Associated block: %s\n", block_name.c_str());
 *      }
 *
 *
 * As another example, consider the inverse problem of identifying the nets connected as inputs to a particular block:
 *
 *      BlkId blk_id;
 *
 *      //... Initialize blk_id with the block of interest
 *
 *      //Iterate through the ports
 *      for(PortId port_id : netlist.block_input_ports(blk_id)) {
 *
 *          //Iterate through the pins
 *          for(PinId pin_id : netlist.port_pins(port_id)) {
 *              //Retrieve the net
 *              NetId net_id = netlist.pin_net(pin_id);
 *
 *              //Get its name
 *              const std::string& net_name = netlist.net_name(net_id);
 *              printf("Associated net: %s\n", net_name.c_str());
 *          }
 *      }
 *
 * Here we used the block_input_ports() method which returned an iterable range of all the input ports
 * associated with blk_id. We then used the port_pins() method to get iterable ranges of all the pins
 * associated with each port, from which we can find the associated net.
 *
 * Often port information is not relevant so this can be further simplified by iterating over a block's pins
 * directly (e.g. by calling one of the block_*_pins() functions):
 *
 *      BlkId blk_id;
 *
 *      //... Initialize blk_id with the block of interest
 *
 *      //Iterate over the blocks ports directly
 *      for(PinId pin_id : netlist.block_input_pins(blk_id)) {
 *
 *          //Retrieve the net
 *          NetId net_id = netlist.pin_net(pin_id);
 *
 *          //Get its name
 *          const std::string& net_name = netlist.net_name(net_id);
 *          printf("Associated net: %s\n", net_name.c_str());
 *      }
 *
 * Note the use of range-based-for loops in the above examples; it could also have written (more verbosely)
 * using a conventional for loop and explicit iterators as follows:
 *
 *      BlkId blk_id;
 *
 *      //... Initialize blk_id with the block of interest
 *
 *      //Iterate over the blocks ports directly
 *      auto pins = netlist.block_input_pins(blk_id);
 *      for(auto pin_iter = pins.begin(); pin_iter != pins.end(); ++pin_iter) {
 *
 *          //Retrieve the net
 *          NetId net_id = netlist.pin_net(*pin_iter);
 *
 *          //Get its name
 *          const std::string& net_name = netlist.net_name(net_id);
 *          printf("Associated net: %s\n", net_name.c_str());
 *      }
 *
 *
 * Creating the netlist
 * --------------------
 * The netlist can be created by using the create_*() member functions to create individual Blocks/Ports/Pins/Nets.
 *
 * For instance to create the following netlist (where each block is the same type, and has an input port 'A'
 * and output port 'B'):
 *
 *      -----------        net1         -----------
 *      | block_1 |-------------------->| block_2 |
 *      -----------          |          -----------
 *                           |
 *                           |          -----------
 *                           ---------->| block_3 |
 *                                      -----------
 * We could do the following:
 *
 *      const t_model* blk_model = .... //Initialize the block model appropriately
 *
 *      Netlist netlist("my_netlist"); //Initialize the netlist with name 'my_netlist'
 *
 *      //Create the first block
 *      BlockId blk1 = netlist.create_block("block_1", blk_model);
 *
 *      //Create the first block's output port
 *      //  Note that the input/output/clock type of the port is determined
 *      //  automatically from the block model
 *      PortId blk1_out = netlist.create_port(blk1, "B");
 *
 *      //Create the net
 *      NetId net1 = netlist.create_net("net1");
 *
 *      //Associate the net with blk1
 *      netlist.create_pin(blk1_out, 0, net1, PinType::DRIVER);
 *
 *      //Create block 2 and hook it up to net1
 *      BlockId blk2 = netlist.create_block("block_2", blk_model);
 *      PortId blk2_in = netlist.create_port(blk2, "A");
 *      netlist.create_pin(blk2_in, 0, net1, PinType::SINK);
 *
 *      //Create block 3 and hook it up to net1
 *      BlockId blk3 = netlist.create_block("block_3", blk_model);
 *      PortId blk3_in = netlist.create_port(blk3, "A");
 *      netlist.create_pin(blk3_in, 0, net1, PinType::SINK);
 *
 * Modifying the netlist
 * ---------------------
 * The netlist can also be modified by using the remove_*() member functions. If we wanted to remove
 * block_3 from the netlist creation example above we could do the following:
 *
 *      //Mark blk3 and any references to it invalid
 *      netlist.remove_block(blk3);
 *
 *      //Compress the netlist to actually remove the data associated with blk3
 *      // NOTE: This will invalidate all client held IDs (e.g. blk1, blk1_out, net1, blk2, blk2_in)
 *      netlist.compress();
 *
 * The resulting netlist connectivity now looks like:
 *
 *      -----------        net1         -----------
 *      | block_1 |-------------------->| block_2 |
 *      -----------                     -----------
 *
 * Note that until compress() is called any 'removed' elements will have invalid IDs (e.g. BlockId::INVALID()).
 * As a result after calling remove_block() (which invalidates blk3) we *then* called compress() to remove the
 * invalid IDs.
 *
 * Also note that compress() is relatively slow. As a result avoid calling compress() after every call to
 * a remove_*() function, and instead batch up calls to remove_*() and call compress() only after a set of
 * modifications have been applied.
 *
 * Verifying the netlist
 * ---------------------
 * Particularly after construction and/or modification it is a good idea to check that the netlist is in
 * a valid and consistent state. This can be done with the verify() member function:
 *
 *      netlist.verify()
 *
 * If the netlist is not valid verify() will throw an exception, otherwise it returns true.
 *
 * Invariants
 * ==========
 * The Netlist maintains stronger invariants if the netlist is in compressed form.
 *
 * Netlist is compressed ('not dirty')
 * -----------------------------------
 * If the netlist is compressed (i.e. !is_dirty(), meaning there have been NO calls to remove_*() since the last call to
 * compress()) the following invariant will hold:
 *      - Any range returned will contain only valid IDs
 *
 * In practise this means the following conditions hold:
 *      - Blocks will not contain empty ports/pins (e.g. ports with no pin/net connections)
 *      - Ports will not contain pins with no associated net
 *      - Nets will not contain invalid sink pins
 *
 * This means that no error checking for invalid IDs is needed if simply iterating through netlist (see below for
 * some exceptions).
 *
 * NOTE: you may still encounter invalid IDs in the following cases:
 *      - net_driver() will return an invalid ID if the net is undriven
 *      - port_pin()/port_net() will return an invalid ID if the bit index corresponds to an unconnected pin
 *
 * Netlist is NOT compressed ('dirty')
 * -----------------------------------
 * If the netlist is not compressed (i.e. is_dirty(), meaning there have been calls to remove_*() with no subsequent
 * calls to compress()) then the invariant above does not hold.
 *
 * Any range may return invalid IDs. In practise this means,
 *      - Blocks may contain invalid ports/pins
 *      - Ports may contain invalid pins
 *      - Pins may not have a valid associated net
 *      - Nets may contain invalid sink pins
 *
 * Implementation Details
 * ======================
 * The netlist is stored in Struct-of-Arrays format rather than the more conventional Array-of-Structs.
 * This improves cache locality by keeping component attributes of the same type in contiguous memory.
 * This prevents unneeded member data from being pulled into the cache (since most code accesses only a few
 * attributes at a time this tends to be more efficient).
 *
 * Clients of this class pass nearly-opaque IDs (BlockId, PortId, PinId, NetId, StringId) to retrieve
 * information. The ID is internally converted to an index to retrieve the required value from it's associated storage.
 *
 * By using nearly-opaque IDs we can change the underlying data layout as need to optimize performance/memory, without
 * disrupting client code.
 *
 * Strings
 * -------
 * To minimize memory usage, we store each unique string only once in the netlist and give it a unique ID (StringId).
 * Any references to this string then make use of the StringId.
 *
 * In particular this prevents the (potentially large) strings from begin duplicated multiple times in various look-ups,
 * instead the more space efficient StringId is duplicated.
 *
 * Note that StringId is an internal implementation detail and should not be exposed as part of the public interface.
 * Any public functions should take and return std::string's instead.
 *
 * Block pins/Block ports data layout
 * ----------------------------------
 * The pins/ports for each block are stored in a similar manner, for brevity we describe only pins here.
 *
 * The pins for each block (i.e. PinId's) are stored in a single vector for each block (the block_pins_ member).
 * This allows us to iterate over all pins (i.e. block_pins()), or specific subsets of pins (e.g. only inputs with
 * block_input_pins()).
 *
 * To accomplish this all pins of the same group (input/output/clock) are located next to each other. An example is
 * shown below, where the block has n input pins, m output pins and k clock pins.
 *
 *  -------------------------------------------------------------------------------------------------------------------
 *  | ipin_1 | ipin_2 | ... | ipin_n | opin_1 | opin_2 | ... | opin_m | clock_pin_1 | clock_pin_2 | ... | clock_pin_k |
 *  -------------------------------------------------------------------------------------------------------------------
 *  ^                                ^                                ^                                               ^
 *  |                                |                                |                                               |
 * begin                         opin_begin                    clock_pin_begin                                       end
 *
 * Provided we know the internal dividing points (i.e. opin_begin and clock_pin_begin) we can easily build the various
 * ranges of interest:
 *
 *      all pins   : [begin, end)
 *      input pins : [begin, opin_begin)
 *      output pins: [opin_begin, clock_pin_begin)
 *      clock pins : [clock_pin_begin, end)
 *
 * Since any reallocation would invalidate any iterators to these internal dividers, we separately store the number
 * of input/output/clock pins per block (i.e. in block_num_input_pins_, block_num_output_pins_ and
 * block_num_clock_pins_). The internal dividers can then be easily calculated (e.g. see block_output_pins()), even
 * if new pins are inserted (provided the counts are updated).
 *
 * Adding data to the netlist
 * --------------------------
 * The Netlist should contain only information directly related to the netlist state (i.e. netlist connectivity).
 * Various mappings to/from elements (e.g. what CLB contains an atom block), and algorithmic state (e.g. if a net
 * is routed) do NOT constitute netlist state and should NOT be stored here.
 *
 * Such implementation state should be stored in other data structures (which may reference the Netlist's IDs).
 *
 * The netlist state should be immutable (i.e. read-only) for most of the CAD flow.
 *
 * Interactions with other netlists
 * --------------------------------
 * Currently, the AtomNetlist and ClusteredNetlist are both derived from Netlist. The AtomNetlist has primitive
 * specific details (t_model, TruthTable), and handles all operations with the atoms. The ClusteredNetlist
 * contains information on the CLB (Clustered Logic Block) level, which includes the physical description of the
 * blocks (t_logical_block_type), as well as the internal hierarchy and wiring (t_pb/t_pb_route).
 *
 * The calling-conventions of the functions in the AtomNetlist and ClusteredNetlist is as follows:
 *
 *    Functions where the derived class (Atom/Clustered) calls the base class (Netlist)
 *       create_*()
 *
 *    Functions where the base class calls the derived class (Non-Virtual Interface idiom as described
 *    https://en.wikibooks.org/wiki/More_C%2B%2B_Idioms/Non-Virtual_Interface)
 *       remove_*()
 *       clean_*()
 *       validate_*_sizes()
 *       shrink_to_fit()
 *    The derived functions based off of the virtual functions have suffix *_impl()
 *
 */
#include <string>
#include <vector>
#include <unordered_map>
#include "vtr_range.h"
#include "vtr_logic.h"
#include "vtr_vector_map.h"

#include "logic_types.h"

#include "netlist_fwd.h"
#include "netlist_utils.h"

//Forward declaration for private methods
template<typename BlockId, typename PortId, typename PinId, typename NetId>
class NetlistIdRemapper {
  public:
    BlockId new_block_id(BlockId old_blk) const;
    PortId new_port_id(PortId old_port) const;
    PinId new_pin_id(PinId old_pin) const;
    NetId new_net_id(NetId old_net) const;

  private:
    friend Netlist<BlockId, PortId, PinId, NetId>;

    vtr::vector_map<BlockId, BlockId> block_id_map_;
    vtr::vector_map<PortId, PortId> port_id_map_;
    vtr::vector_map<PinId, PinId> pin_id_map_;
    vtr::vector_map<NetId, NetId> net_id_map_;
};

template<typename BlockId, typename PortId, typename PinId, typename NetId>
class Netlist {
  public: //Public Types
    typedef typename vtr::vector_map<BlockId, BlockId>::const_iterator block_iterator;
    typedef typename std::unordered_map<std::string, std::string>::const_iterator attr_iterator;
    typedef typename std::unordered_map<std::string, std::string>::const_iterator param_iterator;
    typedef typename vtr::vector_map<NetId, NetId>::const_iterator net_iterator;
    typedef typename vtr::vector_map<PinId, PinId>::const_iterator pin_iterator;
    typedef typename vtr::vector_map<PortId, PortId>::const_iterator port_iterator;

    typedef typename vtr::Range<block_iterator> block_range;
    typedef typename vtr::Range<attr_iterator> attr_range;
    typedef typename vtr::Range<param_iterator> param_range;
    typedef typename vtr::Range<net_iterator> net_range;
    typedef typename vtr::Range<pin_iterator> pin_range;
    typedef typename vtr::Range<port_iterator> port_range;

    typedef NetlistIdRemapper<BlockId, PortId, PinId, NetId> IdRemapper;

  public:
    Netlist(std::string name = "", std::string id = "");
    virtual ~Netlist();

  public: //Public Accessors
    /*
     * Netlist
     */
    //Retrieve the name of the netlist
    const std::string& netlist_name() const;

    //Retrieve the unique identifier for this netlist
    //This is typically a secure digest of the input file.
    const std::string& netlist_id() const;

    /*
     * Utility
     */
    //Sanity check for internal consistency (throws an exception on failure)
    bool verify() const;

    //Returns true if the netlist has invalid entries due to modifications (e.g. from remove_*() calls)
    bool is_dirty() const;

    //Returns true if the netlist has *no* invalid entries due to modifications (e.g. from remove_*() calls)
    //Note that this is a convenience method which is the logical inverse of is_dirty()
    bool is_compressed() const;

    //Item counts and container info (for debugging)
    void print_stats() const;

    /*
     * Blocks
     */
    //Returns the name of the specified block
    const std::string& block_name(const BlockId blk_id) const;

    //Returns true if the block is purely combinational (i.e. no input clocks
    //and not a primary input
    bool block_is_combinational(const BlockId blk_id) const;

    // Returns a range of all attributes associated with the specified block
    attr_range block_attrs(const BlockId blk_id) const;

    // Returns a range of all parameters associated with the specified block
    param_range block_params(const BlockId blk_id) const;

    //Returns a range of all pins associated with the specified block
    pin_range block_pins(const BlockId blk_id) const;

    //Returns a range of all input pins associated with the specified block
    pin_range block_input_pins(const BlockId blk_id) const;

    //Returns a range of all output pins associated with the specified block
    // Note this is typically only data pins, but some blocks (e.g. PLLs) can produce outputs
    // which are clocks.
    pin_range block_output_pins(const BlockId blk_id) const;

    //Returns a range of all clock pins associated with the specified block
    pin_range block_clock_pins(const BlockId blk_id) const;

    //Returns a range of all ports associated with the specified block
    port_range block_ports(const BlockId blk_id) const;

    //Returns a range consisting of the input ports associated with the specified block
    port_range block_input_ports(const BlockId blk_id) const;

    //Returns a range consisting of the output ports associated with the specified block
    // Note this is typically only data ports, but some blocks (e.g. PLLs) can produce outputs
    // which are clocks.
    port_range block_output_ports(const BlockId blk_id) const;

    //Returns a range consisting of the input clock ports associated with the specified block
    port_range block_clock_ports(const BlockId blk_id) const;

    //Removes a block from the netlist. This will also remove the associated ports and pins.
    //  blk_id  : The block to be removed
    void remove_block(const BlockId blk_id);

    /*
     * Ports
     */
    //Returns the name of the specified port
    const std::string& port_name(const PortId port_id) const;

    //Returns the block associated with the specified port
    BlockId port_block(const PortId port_id) const;

    //Returns the set of valid pins associated with the port
    pin_range port_pins(const PortId port_id) const;

    //Returns the pin (potentially invalid) associated with the specified port and port bit index
    //  port_id : The ID of the associated port
    //  port_bit: The bit index of the pin in the port
    //Note: this function is a synonym for find_pin()
    PinId port_pin(const PortId port_id, const BitIndex port_bit) const;

    //Returns the net (potentially invalid) associated with the specified port and port bit index
    //  port_id : The ID of the associated port
    //  port_bit: The bit index of the pin in the port
    NetId port_net(const PortId port_id, const BitIndex port_bit) const;

    //Returns the width (number of bits) in the specified port
    BitIndex port_width(const PortId port_id) const;

    //Returns the type of the specified port
    PortType port_type(const PortId port_id) const;

    //Removes a port from the netlist.
    //The port's pins are also marked invalid and removed from any associated nets
    //  port_id: The ID of the port to be removed
    void remove_port(const PortId port_id);

    /*
     * Pins
     */
    //Returns the constructed name (derived from block and port) for the specified pin
    std::string pin_name(const PinId pin_id) const;

    //Returns the type of the specified pin
    PinType pin_type(const PinId pin_id) const;

    //Returns the net associated with the specified pin
    NetId pin_net(const PinId pin_id) const;

    //Returns the index of the specified pin within it's connected net
    int pin_net_index(const PinId pin_id) const;

    //Returns the port associated with the specified pin
    PortId pin_port(const PinId pin_id) const;

    //Returns the port bit index associated with the specified pin
    BitIndex pin_port_bit(const PinId pin_id) const;

    //Returns the block associated with the specified pin
    BlockId pin_block(const PinId pin_id) const;

    //Returns the port type associated with the specified pin
    PortType pin_port_type(const PinId pin_id) const;

    //Returns true if the pin is a constant (i.e. its value never changes)
    bool pin_is_constant(const PinId pin_id) const;

    //Removes a pin from the netlist.
    //The pin is marked invalid, and removed from any assoicated nets
    //  pin_id: The pin_id of the pin to be removed
    void remove_pin(const PinId pin_id);

    /*
     * Nets
     */
    //Returns the name of the specified net
    const std::string& net_name(const NetId net_id) const;

    //Returns a range consisting of all the pins in the net (driver and sinks)
    //The first element in the range is the driver (and may be invalid)
    //The remaining elements (potentially none) are the sinks
    pin_range net_pins(const NetId net_id) const;

    //Returns the net_pin_index'th pin of the specified net
    PinId net_pin(const NetId net_id, int net_pin_index) const;

    //Returns the block associated with the net_pin_index'th pin of the specified net
    BlockId net_pin_block(const NetId net_id, int net_pin_index) const;

    //Returns the (potentially invalid) net driver pin
    PinId net_driver(const NetId net_id) const;

    //Returns the (potentially invalid) net driver block
    BlockId net_driver_block(const NetId net_id) const;

    //Returns a (potentially empty) range consisting of net's sink pins
    pin_range net_sinks(const NetId net_id) const;

    //Returns true if the net is driven by a constant pin (i.e. its value never changes)
    bool net_is_constant(const NetId net_id) const;

    //Removes a net from the netlist.
    //This will mark the net's pins as having no associated.
    //  net_id  : The net to be removed
    void remove_net(const NetId net_id);

    //Removes a connection betwen a net and pin. The pin is removed from the net and the pin
    //will be marked as having no associated net
    //  net_id  : The net from which the pin is to be removed
    //  pin_id  : The pin to be removed from the net
    void remove_net_pin(const NetId net_id, const PinId pin_id);

    /*
     * Aggregates
     */
    //Returns a range consisting of all blocks in the netlist
    block_range blocks() const;

    //Returns a range consisting of all ports in the netlist
    port_range ports() const;

    //Returns a range consisting of all nets in the netlist
    net_range nets() const;

    //Returns a range consisting of all pins in the netlist
    pin_range pins() const;

    /*
     * ID Checks
     * 
     * Validates that the specified ID is valid in the current netlist state
     */
    bool valid_block_id(BlockId block_id) const;
    bool valid_port_id(PortId port_id) const;
    bool valid_port_bit(PortId port_id, BitIndex port_bit) const;
    bool valid_pin_id(PinId pin_id) const;
    bool valid_net_id(NetId net_id) const;

    /*
     * Lookups
     */
    //Returns the BlockId of the specified block or BlockId::INVALID() if not found
    //  name: The name of the block
    BlockId find_block(const std::string& name) const;

    //Returns the PortId of the specifed port if it exists or PortId::INVALID() if not
    //Note that this method is typically less efficient than searching by a t_model_port
    //With the overloaded AtomNetlist method
    //  blk_id: The ID of the block who's ports will be checked
    //  name  : The name of the port to look for
    PortId find_port(const BlockId blk_id, const std::string& name) const;

    //Returns the NetId of the specified net or NetId::INVALID() if not found
    //  name: The name of the net
    NetId find_net(const std::string& name) const;

    //Returns the PinId of the specified pin or PinId::INVALID() if not found
    //  port_id : The ID of the associated port
    //  port_bit: The bit index of the pin in the port
    PinId find_pin(const PortId port_id, BitIndex port_bit) const;

  public: //Public Mutators
    //Add the specified pin to the specified net as pin_type. Automatically removes
    //any previous net connection for this pin.
    //  pin      : The pin to add
    //  pin_type : The type of the pin (i.e. driver or sink)
    //  net      : The net to add the pin to
    void set_pin_net(const PinId pin, PinType pin_type, const NetId net);

    //Mark a pin as being a constant generator.
    // There are some cases where a pin can not be identified as a is constant until after
    // the full netlist has been built; so we expose a way to mark existing pins as constants.
    //  pin_id  : The pin to be marked
    //  value   : The boolean value to set the pin_is_constant attribute
    void set_pin_is_constant(const PinId pin_id, const bool value);

    //Re-name a block
    //  blk_id   : The block to be renamed
    //  new_name : The new name for the specified block
    void set_block_name(const BlockId blk_id, const std::string new_name);

    //Set a block attribute
    //  blk_id   : The block to which the attribute is attached
    //  name     : The name of the attribute to set
    //  value    : The new value for the specified attribute on the specified block
    void set_block_attr(const BlockId blk_id, const std::string& name, const std::string& value);

    //Set a block parameter
    //  blk_id   : The block to which the parameter is attached
    //  name     : The name of the parameter to set
    //  value    : The new value for the specified parameter on the specified block
    void set_block_param(const BlockId blk_id, const std::string& name, const std::string& value);

    //Merges sink_net into driver_net
    //After merging driver_net will contain all the sinks of sink_net
    //  driver_net: The net which includes the driver pin
    //  sink_net: The target net to be merged into driver_net (must have no driver pin)
    void merge_nets(const NetId driver_net, const NetId sink_net);

    /*
     * Note: all remove_*() will mark the associated items as invalid, but the items
     * will not be removed until compress() is called.
     */
    //Wrapper for remove_unused() & compress()
    // This function should be used in the case where a netlist is fully modified
    IdRemapper remove_and_compress();

    //This should be called after completing a series of netlist modifications
    //(e.g. removing blocks/ports/pins/nets).
    //
    //Marks netlist components which have become redundant due to other removals
    //(e.g. ports with only invalid pins) as invalid so they will be destroyed during
    //compress()
    void remove_unused();

    //Compresses the netlist, removing any invalid and/or unreferenced
    //blocks/ports/pins/nets.
    //
    //NOTE: this invalidates all existing IDs!
    IdRemapper compress();

  protected: //Protected Mutators
    //Create or return an existing block in the netlist
    //  name        : The unique name of the block
    BlockId create_block(const std::string name);

    //Create or return an existing port in the netlist
    //  blk_id      : The block the port is associated with
    //  name        : The name of the port (must match the name of a port in the block's model)
    //  width       : The width (number of bits) of the port
    //  type        : The type of the port (INPUT, OUTPUT, CLOCK)
    PortId create_port(const BlockId blk_id, const std::string name, BitIndex width, PortType type);

    //Create or return an existing pin in the netlist
    //  port_id    : The port this pin is associated with
    //  port_bit   : The bit index of the pin in the port
    //  net_id     : The net the pin drives/sinks
    //  pin_type   : The type of the pin (driver/sink)
    //  is_const   : Indicates whether the pin holds a constant value (e. g. vcc/gnd)
    PinId create_pin(const PortId port_id, BitIndex port_bit, const NetId net_id, const PinType pin_type, bool is_const = false);

    //Create an empty, or return an existing net in the netlist
    //  name    : The unique name of the net
    NetId create_net(const std::string name); //An empty or existing net

    //Create a completely specified net from specified driver and sinks
    //  name    : The name of the net (Note: must not already exist)
    //  driver  : The net's driver pin
    //  sinks   : The net's sink pins
    NetId add_net(const std::string name, PinId driver, std::vector<PinId> sinks);

  protected: //Protected Base Types
    struct string_id_tag;

    //A unique identifier for a string in the netlist
    typedef vtr::StrongId<string_id_tag> StringId;

  protected: //Protected Base Members
    /*
     * Lookups
     */
    //Returns the StringId of the specifed string if it exists or StringId::INVALID() if not
    //  str : The string to look for
    StringId find_string(const std::string& str) const;

    //Returns the BlockId of the specifed block if it exists or BlockId::INVALID() if not
    //  name_id : The block name to look for
    BlockId find_block(const StringId name_id) const;

    //Returns the NetId of the specifed port if it exists or NetId::INVALID() if not
    //  name_id: The string ID of the net name to look for
    NetId find_net(const StringId name_id) const;

    /*
     * Mutators
     */
    //Create or return the ID of the specified string
    //  str: The string whose ID is requested
    StringId create_string(const std::string& str);

    //Updates net cross-references for the specified pin
    //Returns the pin's index within the net
    int associate_pin_with_net(const PinId pin_id, const PinType type, const NetId net_id);

    //Updates port cross-references for the specified pin
    void associate_pin_with_port(const PinId pin_id, const PortId port_id);

    //Updates block cross-references for the specified pin
    void associate_pin_with_block(const PinId pin_id, const PortType type, const BlockId blk_id);

    //Updates block cross-references for the specified port
    void associate_port_with_block(const PortId port_id, const PortType type, const BlockId blk_id);

    /*
     * Netlist compression/optimization
     */
    //Builds the new mappings from old to new IDs.
    //The various IdMap's should be initialized with invalid mappings
    //for all current ID's before being called.
    IdRemapper build_id_maps();

    //Removes invalid and reorders blocks
    void clean_blocks(const vtr::vector_map<BlockId, BlockId>& block_id_map);

    //Removes invalid and reorders ports
    void clean_ports(const vtr::vector_map<PortId, PortId>& port_id_map);

    //Removes invalid and reorders pins
    void clean_pins(const vtr::vector_map<PinId, PinId>& pin_id_map);

    //Removes invalid and reorders nets
    void clean_nets(const vtr::vector_map<NetId, NetId>& net_id_map);

    //Re-builds fast look-ups
    void rebuild_lookups();

    //Re-builds cross-references held by blocks
    void rebuild_block_refs(const vtr::vector_map<PinId, PinId>& pin_id_map,
                            const vtr::vector_map<PortId, PortId>& port_id_map);

    //Re-builds cross-references held by ports
    void rebuild_port_refs(const vtr::vector_map<BlockId, BlockId>& block_id_map,
                           const vtr::vector_map<PinId, PinId>& pin_id_map);

    //Re-builds cross-references held by pins
    void rebuild_pin_refs(const vtr::vector_map<PortId, PortId>& port_id_map,
                          const vtr::vector_map<NetId, NetId>& net_id_map);

    //Re-builds cross-references held by nets
    void rebuild_net_refs(const vtr::vector_map<PinId, PinId>& pin_id_map);

    void shrink_to_fit();

    /*
     * Sanity Checks
     */
    //Verify the internal data structure sizes match
    bool verify_sizes() const;
    bool validate_block_sizes() const;
    bool validate_port_sizes() const;
    bool validate_pin_sizes() const;
    bool validate_net_sizes() const;
    bool validate_string_sizes() const;

    //Verify that internal data structure cross-references are consistent
    bool verify_refs() const; //All cross-references
    bool validate_block_port_refs() const;
    bool validate_block_pin_refs() const;
    bool validate_port_pin_refs() const;
    bool validate_net_pin_refs() const;
    bool validate_string_refs() const;

    //Verify that block invariants hold (i.e. logical consistency)
    bool verify_block_invariants() const;

    //Verify that fast-lookups are consistent with internal data structures
    bool verify_lookups() const;

    //Validates that the specified ID is valid in the current netlist state
    bool valid_string_id(StringId string_id) const;

  protected: //Protected virtual functions implemented in derived classes
    //The functions follow the Non-Virtual Interface (NVI) idiom, and
    //are called from this class in their respective non-impl() functions.
    virtual void shrink_to_fit_impl() = 0;

    virtual bool validate_block_sizes_impl(size_t num_blocks) const = 0;
    virtual bool validate_port_sizes_impl(size_t num_ports) const = 0;
    virtual bool validate_pin_sizes_impl(size_t num_pins) const = 0;
    virtual bool validate_net_sizes_impl(size_t num_nets) const = 0;

    virtual void clean_blocks_impl(const vtr::vector_map<BlockId, BlockId>& block_id_map) = 0;
    virtual void clean_ports_impl(const vtr::vector_map<PortId, PortId>& port_id_map) = 0;
    virtual void clean_pins_impl(const vtr::vector_map<PinId, PinId>& pin_id_map) = 0;
    virtual void clean_nets_impl(const vtr::vector_map<NetId, NetId>& net_id_map) = 0;

    virtual void remove_block_impl(const BlockId blk_id) = 0;
    virtual void remove_port_impl(const PortId port_id) = 0;
    virtual void remove_pin_impl(const PinId pin_id) = 0;
    virtual void remove_net_impl(const NetId net_id) = 0;

    virtual void rebuild_block_refs_impl(const vtr::vector_map<PinId, PinId>& pin_id_map, const vtr::vector_map<PortId, PortId>& port_id_map) = 0;
    virtual void rebuild_port_refs_impl(const vtr::vector_map<BlockId, BlockId>& block_id_map, const vtr::vector_map<PinId, PinId>& pin_id_map) = 0;
    virtual void rebuild_pin_refs_impl(const vtr::vector_map<PortId, PortId>& port_id_map, const vtr::vector_map<NetId, NetId>& net_id_map) = 0;
    virtual void rebuild_net_refs_impl(const vtr::vector_map<PinId, PinId>& pin_id_map) = 0;

  protected:
    constexpr static int INVALID_INDEX = -1;
    constexpr static int NET_DRIVER_INDEX = 0;

  private:                     //Data
    std::string netlist_name_; //Name of the top-level netlist
    std::string netlist_id_;   //Unique identifier for the netlist
    bool dirty_ = false;       //Indicates the netlist has invalid entries from remove_*() functions

    //Block data
    vtr::vector_map<BlockId, BlockId> block_ids_;    //Valid block ids
    vtr::vector_map<BlockId, StringId> block_names_; //Name of each block

    vtr::vector_map<BlockId, std::vector<PortId>> block_ports_; //Ports of each block
    vtr::vector_map<BlockId, unsigned> block_num_input_ports_;  //Input ports of each block
    vtr::vector_map<BlockId, unsigned> block_num_output_ports_; //Output ports of each block
    vtr::vector_map<BlockId, unsigned> block_num_clock_ports_;  //Clock ports of each block

    vtr::vector_map<BlockId, std::vector<PinId>> block_pins_;  //Pins of each block
    vtr::vector_map<BlockId, unsigned> block_num_input_pins_;  //Number of input pins on each block
    vtr::vector_map<BlockId, unsigned> block_num_output_pins_; //Number of output pins on each block
    vtr::vector_map<BlockId, unsigned> block_num_clock_pins_;  //Number of clock pins on each block

    vtr::vector_map<BlockId, std::unordered_map<std::string, std::string>> block_params_; //Parameters of each block
    vtr::vector_map<BlockId, std::unordered_map<std::string, std::string>> block_attrs_;  //Attributes of each block

    //Port data
    vtr::vector_map<PortId, PortId> port_ids_;              //Valid port ids
    vtr::vector_map<PortId, StringId> port_names_;          //Name of each port
    vtr::vector_map<PortId, BlockId> port_blocks_;          //Block associated with each port
    vtr::vector_map<PortId, std::vector<PinId>> port_pins_; //Pins associated with each port
    vtr::vector_map<PortId, BitIndex> port_widths_;         //Width (in bits) of each port
    vtr::vector_map<PortId, PortType> port_types_;          //Type of the port (INPUT, OUTPUT, CLOCK)

    //Pin data
    vtr::vector_map<PinId, PinId> pin_ids_;          //Valid pin ids
    vtr::vector_map<PinId, PortId> pin_ports_;       //Type of each pin
    vtr::vector_map<PinId, BitIndex> pin_port_bits_; //The pins bit position in the port
    vtr::vector_map<PinId, NetId> pin_nets_;         //Net associated with each pin
    vtr::vector_map<PinId, int> pin_net_indices_;    //Index of the specified pin within it's associated net
    vtr::vector_map<PinId, bool> pin_is_constant_;   //Indicates if the pin always keeps a constant value

    //Net data
    vtr::vector_map<NetId, NetId> net_ids_;               //Valid net ids
    vtr::vector_map<NetId, StringId> net_names_;          //Name of each net
    vtr::vector_map<NetId, std::vector<PinId>> net_pins_; //Pins associated with each net

    //String data
    // We store each unique string once, and reference it by an StringId
    // This avoids duplicating the strings in the fast look-ups (i.e. the look-ups
    // only store the Ids)
    vtr::vector_map<StringId, StringId> string_ids_; //Valid string ids
    vtr::vector_map<StringId, std::string> strings_; //Strings

  private: //Fast lookups
    vtr::vector_map<StringId, BlockId> block_name_to_block_id_;
    vtr::vector_map<StringId, NetId> net_name_to_net_id_;
    std::unordered_map<std::string, StringId> string_to_string_id_;
};

#include "netlist.tpp"
#endif