How should we organize the standard nodes from xod/core?

[nkrkv]

Hi, folks! We need your advice on organizing the standard library. This is the first time we ask to brainstorm for a particular improvement. I hope XOD and you would benefit from it.

Well, we have xod/core library and it starts to become a pile of trash which is hard to navigate and explore. Some xoders already asked to categorize the nodes. Let’s do it. The idea is to evaporate xod/core completely by moving its nodes to new libraries.

Question 1: How many libraries should we have instead of single xod/core

Now, 110 nodes are in the development version of XOD. The number will grow, but it’s likely it would stay at the order of hundreds magnitude for a long time. If the categorization should improve search time, the best theoretical results should we achieved when N_cat = sqrt(N_nodes). I.e. the current optimum is ten categories (libraries) or so.

Feel free to comment if you have other thoughts.

Question 2: What are these new libraries?

Here is a proposal:

Node name               New path
absolute                xod/math/abs
acos                    xod/math/acos
add                     xod/math/add
analog-input            xod/io/analog-input
and                     xod/logic/and
any                     xod/control/any
asin                    xod/math/asin
atan                    xod/math/atan
boot                    xod/time/boot
buffer                  xod/control/buffer
cast-boolean-to-number  xod/logic/to-zero-one
cast-boolean-to-pulse   -- should rely on pulse-on-true
cast-boolean-to-string  xod/text/format-boolean
cast-number-to-boolean  xod/logic/nonzero
cast-number-to-string   -- should rely on xod/text/format-number
ceil                    xod/math/ceil
clip                    xod/math/clip
clock                   xod/time/clock
concat                  xod/list/concat
concat-3                -- [1]
concat-4                -- [1]
concat-5                -- [1]
concat-6                -- [1]
console-log             xod/debug/console-log
constant-boolean        xod/core/constant
constant-number         -- [2]
constant-string         -- [2]
constrain               xod/math/constrain
continuously            xod/time/continuously
continuously-pausable   -- should be merged into `continuously`
cos                     xod/math/cos
count                   xod/control/count
cube                    xod/math/cube
debounce-boolean        xod/time/debounce
defer-boolean           xod/control/defer
defer-number            -- [2]
defer-pulse             -- [2]
defer-string            -- [2]
delay                   xod/time/delay
digital-input           xod/io/digital-input
digital-output          xod/io/digital-output
discretize-2            xod/math/discretize
discretize-3            -- [2]
discretize-4            -- [2]
divide                  xod/math/divide
duty-to-time            xod/time/duty-to-time
equal                   xod/math/equal
fade                    xod/control/fade
flip-flop               xod/control/flip-flop
flip-n-times            xod/time/flip-n-times
floor                   xod/math/floor
format-number           xod/text/format-number
gate                    xod/control/gate
gate-boolean            -- [2]
gate-number             -- [2]
gate-pulse              -- [2]
gate-string             -- [2]
greater                 xod/math/greater
i2c-begin-transmission  xod/io/i2c-begin-transmission
i2c-end-transmission    xod/io/i2c-end-transmission
i2c-read                xod/io/i2c-read
i2c-request             xod/io/i2c-request
i2c-request-bytes-6     xod/io/i2c-fetch-packet
i2c-send-byte           xod/io/i2c-send-packet
i2c-send-bytes-2        -- [1]
i2c-write               xod/io/i2c-write
if-else                 xod/logic/if-else
if-else-string          -- [2]
less                    xod/math/less
log-10                  xod/math/log-10
log-bx                  xod/math/log-bx
log-e                   xod/math/log-e
map-clip-range          xod/math/map-clip
map-range               xod/math/map
modulo                  xod/math/modulo
multiply                xod/math/multiply
nand                    xod/logic/nand
nor                     xod/logic/nor
not                     xod/logic/not
nth-number-2            xod/list/nth
nth-number-3            -- [2]
nth-number-4            -- [2]
or                      xod/logic/or
pi                      xod/math/pi
pow                     xod/math/pow
pulse-on-change         xod/control/pulse-on-change
pulse-on-false          xod/control/pulse-on-false
pulse-on-true           xod/control/pulse-on-true
pwm-output              xod/io/pwm-output
round                   xod/math/round
saw-wave                xod/time/saw-wave
saw-wave-map            xod/math/map-saw
select                  xod/control/select
sin                     xod/math/sin
sine-wave               xod/time/sine-wave
sine-wave-map           xod/math/map-sin
sqrt                    xod/math/sqrt
square                  xod/math/square
square-wave             xod/time/square-wave
subtract                xod/math/subtract
system-time             xod/time/time
tan                     xod/math/tan
time-to-duty            xod/time/time-to-duty
timer                   xod/time/timer
to-percent              xod/text/to-percent
tri-wave                xod/time/tri-wave
tri-wave-map            xod/math/map-tri
watch                   xod/debug/watch
word-to-number          xod/bits/word-to-number
xor                     xod/logic/xor

¹ Arity would be eradicated in future versions by using lists
² Nodes that differ only in types would be generalized using generic types in future versions

If we’d sort the list above by the new path column and remove the nodes which should go:

Node name               New path
word-to-number          xod/bits/word-to-number
any                     xod/control/any
buffer                  xod/control/buffer
count                   xod/control/count
defer-boolean           xod/control/defer
fade                    xod/control/fade
flip-flop               xod/control/flip-flop
gate                    xod/control/gate
pulse-on-change         xod/control/pulse-on-change
pulse-on-false          xod/control/pulse-on-false
pulse-on-true           xod/control/pulse-on-true
select                  xod/control/select
constant-boolean        xod/core/constant
console-log             xod/debug/console-log
watch                   xod/debug/watch
analog-input            xod/io/analog-input
digital-input           xod/io/digital-input
digital-output          xod/io/digital-output
i2c-begin-transmission  xod/io/i2c-begin-transmission
i2c-end-transmission    xod/io/i2c-end-transmission
i2c-request-bytes-6     xod/io/i2c-fetch-packet
i2c-read                xod/io/i2c-read
i2c-request             xod/io/i2c-request
i2c-send-byte           xod/io/i2c-send-packet
i2c-write               xod/io/i2c-write
pwm-output              xod/io/pwm-output
concat                  xod/list/concat
nth-number-2            xod/list/nth
and                     xod/logic/and
if-else                 xod/logic/if-else
nand                    xod/logic/nand
cast-number-to-boolean  xod/logic/nonzero
nor                     xod/logic/nor
not                     xod/logic/not
or                      xod/logic/or
cast-boolean-to-number  xod/logic/to-zero-one
xor                     xod/logic/xor
absolute                xod/math/abs
acos                    xod/math/acos
add                     xod/math/add
asin                    xod/math/asin
atan                    xod/math/atan
ceil                    xod/math/ceil
clip                    xod/math/clip
constrain               xod/math/constrain
cos                     xod/math/cos
cube                    xod/math/cube
discretize-2            xod/math/discretize
divide                  xod/math/divide
equal                   xod/math/equal
floor                   xod/math/floor
greater                 xod/math/greater
less                    xod/math/less
log-10                  xod/math/log-10
log-bx                  xod/math/log-bx
log-e                   xod/math/log-e
map-range               xod/math/map
map-clip-range          xod/math/map-clip
saw-wave-map            xod/math/map-saw
sine-wave-map           xod/math/map-sin
tri-wave-map            xod/math/map-tri
modulo                  xod/math/modulo
multiply                xod/math/multiply
pi                      xod/math/pi
pow                     xod/math/pow
round                   xod/math/round
sin                     xod/math/sin
sqrt                    xod/math/sqrt
square                  xod/math/square
subtract                xod/math/subtract
tan                     xod/math/tan
cast-boolean-to-string  xod/text/format-boolean
format-number           xod/text/format-number
to-percent              xod/text/to-percent
boot                    xod/time/boot
clock                   xod/time/clock
continuously            xod/time/continuously
debounce-boolean        xod/time/debounce
delay                   xod/time/delay
duty-to-time            xod/time/duty-to-time
flip-n-times            xod/time/flip-n-times
saw-wave                xod/time/saw-wave
sine-wave               xod/time/sine-wave
square-wave             xod/time/square-wave
system-time             xod/time/time
time-to-duty            xod/time/time-to-duty
timer                   xod/time/timer
tri-wave                xod/time/tri-wave

So, we have nine libraries:

• xod/bits — bitwise operations, bit shifts, bit masks, low-level data packing
• xod/control — the nodes to store the state and control the execution flow
• xod/debug — nodes to monitor the program, set breakpoints, adjust parameters
• xod/io — very basic hardware-native input and output
• xod/lists — operations on vectors/lists
• xod/logic — boolean operations
• xod/math — the algebra from a school
• xod/text — operations on strings of text
• xod/time — time-signal generators

Does it looks OK?

Question 3: Does xod/control looks like a new pile?

Intuitively I feel when a node should fall into a particular lib. But that’s not a case for xod/control. Can someone suggest an alternative or a strong metaphor?

BTW, should debounce and delay belong to time or they should be in control?

Question 4: Where we should put the constant node?

There’s no xod/core anymore, it lost the home One solution is to have something called xod/atoms instead of current xod/patch-nodes and put it there. Is it OK?

Question 5: Should we use widely adopted abbreviations for names?

• divide → div
• subtract → sub
• multiply → mul
• absolute → abs

If so, where should we stop?

• modulo → mod?
• constant → const?
• greater → gt?
• time → t?
• i2c-send-packet →i2c-snd-pk?

---

Looking forward for your thoughts!

[zhuk]

need:

1. simple convenient cycle
   from X to Y step
2. operator IF THEN ELSE
3. output DATA to port on PC COM

Moderator note Sorry, your reply is not related to the thread topic. Please, create new thread to discuss your proposal.

[awgrover]

Yes, break up the xod/core!

I have a conflict about how to categorize: One of the main reasons for my interest in XOD is its usability by non-programmers. Thus, the categories need to make sense to them. So, “logic” doesn’t mean “and” to them. On the other hand, as a programmer, I do want the categories to have some relation to how we refer to things in programming. So, for example, I can never find functions in Excel because their categories don’t make sense some of the time. I don’t have the experience to suggest good categories for non-programmers.

I think, as a reference, we could look at Excel’s categories. Many people are familiar with using it, though maybe they don’t like the categories either. But, don’t just copy Excel’s categories, I’m pretty sure we can do better.

A problem with the categories is that they are the identifier (path) for a node: if you want to change categories, then you’ve just renamed the node. I had this problem with my libraries, when I realized that the path was wrong. I had to find all projects that used it and edit them. Perhaps treat the “path” as a petname? And category is a property (like “description”)?

Should we be more thoughtful about the categories and terminology, because this is flow-based and not text-imperative programming? For example, “control” rubs me the wrong way. “count” is not a control structure! I see nodes that “choose” whose output is “conditional”, or that “count”. I ended up with several sequence/count nodes as I was writing some nodes, and that felt like a category.

As a programmer (with a weak attempt to have some meaning for non-programmers):

xod/operators    abs, add, <, and, or... Combines inputs
xod/counters     Various sequence generators 
xod/wave         shapes
xod/conditional  if, select, ... Chooses output(s)
xod/i2c          because i2c is a thing
xod/pins         digital r/w, pwm, analog-read, debounce-pin, pin stuff, 
xod/values       constants, pi, etc.
xod/time         boot, clock, continous, delay, duty-cycle: Pulses from millis()

I’ve left a bunch of stuff off, but you can see I’m going more for semantic categories. And now I want multiple-categories for a node!

[awgrover]

@nkrkv

Question 5: Should we use widely adopted abbreviations for names?

Why do they need to be short? In textual code there are reasons: compactness for understanding, typing.

In FBP, we need to understand what a visible node does. So, the name needs to be visible. Long names have been a problem, since the nodes are sized according to the number of inputs/outputs.

In any event, only abbreviate for common things. i2c is not common compared to “add”.

[nkrkv]

@awgrover, thanks for sharing your thoughts!

@awgrover

One of the main reasons for my interest in XOD is its usability by non-programmers. Thus, the categories need to make sense to them.

Agree

@awgrover

So, “logic” doesn’t mean “and” to them… I think, as a reference, we could look at Excel’s categories.

Funny enough, =AND is a logical function in Excel I think, I can ask a non-programmer to break up the xod/core and take a look at the result.

@awgrover

Perhaps treat the “path” as a petname? And category is a property (like “description”)?

Many things in XOD implementation depend on the so-called PatchPath which is <owner>/<library>/<node>. It has to be considered as “limitation” that we can turn into a useful aspect. For example, take a look at the Python standard library which has a multitude of functions/classes and each of them belongs exactly to a single module.

However, having this limitation doesn’t mean we can’t introduce another classification axis with a many-to-many relation. Let’s call it “Tags”. There could be a dozen or so of tags and any node (XOD standard or contributed) could declare it belongs to a particular set (zero or more) of tags.

@awgrover

“count” is not a control structure!

Agree, you’re right.

I like the categories you suggested although not sure where some nodes (modulo, acos) should belong to in that case. Need to gather non-tech opinions.

@awgrover

In any event, only abbreviate for common things.

Yeah, that makes sense. i2c-snd-pk was irony. I can’t find a clear line though. mod or modulo, abs or absolute, log or logarithm, etc.

[dox]

I thought even in the last weeks it would be useful to mark the nodes with different colors depending on the information they will handle (or output).

Example:
mark “add” in the menu with a green color, because this node handles numbers
mark “buffer” in the menu with a green color, because this node handles numbers
mark “and” in the menu with a pink color, because this node handles booleans
mark “clock” in the menu with a violet color, because this node outputs pulses
mark “gate-string” in the menu with a yellow color, because this node handles a string
etc.

[nkrkv]

I see what you mean. Color is a most expressive design tool, so let keep it a trump card for a while. Or we have a chance to make yet another Scratch Someday we employ color to distinguish nodes, but it requires a hard and careful discussion, another discussion.

[luci]

Hi ! First of all, xod is an great visual programming software and i love it !!!
Question 1: Up to 10, in a quick window, if posible at right click on patch window, with posibility to extend to full tree for each line);
2: I think he must do configurable (for each person use or retain the last used);
3: …
4:… for me it’s ok this way;
5: I think that is easier with full name for each node, at least for a beginer.
Thank you and goodluck !!!

[nkrkv]

Hello, @luci and welcome!

Thank you for motivating words and sharing your thoughts.

Question 2: What are these new libraries?

I think he must do configurable (for each person use or retain the last used);

Hmm… That would be an interesting feature. Although we need to provide a starting point. So some initial arrangement should be done anyway, I guess.

[scotty]

Hello friends,

Disclaimer- I know I’m not commenting on the right post, but I can’t seem to figure out how to make my own post to ask this question.

I’m very new to programming/Arduino/XOD/electronics in general, but I have a question- is there a way to expand the amount of nodes that are available to use? If so, how? I find the selection of the
"common hardware" tab somewhat limiting, as I want to use a photoresistor in a project.

Thanks!

Moderator note Your question is fine, but it is not related to this topic. Please, create a new topic with “+ New Topic” button at the top-right corner on the https://forum.xod.io If it is not available to you, just read few more posts so the system understand you’re human.

[scotty]

Sorry for the stupid question, I just remembered that there was a project with a photoresistor in the tutorial, and that I simply need to use an analog input node. But just for clarification- will adding a ‘library’ add new nodes? and if yes, how do I do that?

Thanks!

[i3laze]

So, what’s the state of this great RFC?

I’m really missing ‘Time’ and ‘Condition’ categories: it’s currently hard to find the most suitable patch in overloaded ‘Core’ pile. Without full-text search implemented.

[nkrkv]

The first split (albeit a soft one) is done already. Next, many things from common-hardware will get a new home in dedicated libraries. The xod/core is kept as is because there is no consensus on what should be extracted out and where to draw the lines.

You’ve mentioned time and condition, that’s interesting. Would you describe in more detail? What should go to each of them, what are the criteria? I’m in doubt about some nodes (should they move or not) and so would like to understand your vision.